2.0 Release Notes

2.0.2

See the bugs fixed in 2.0.2.

The fix for #1831 required that during sync, if the remote registry has a v2 API, but getting tags fails, the sync will stop and report an error that the requested repository was not found. With 2.0.0, the sync would not report an error. This would allow a graceful fall-back to the v1 API. But, the “enable_v1” setting defaults to False, so that resulted in a default behavior to report success in the case of failure. Since use of v1 content is now an edge case, and requires manually enabling v1 sync, we recommend disabling v2 sync if you do not expect a repository to be available via a v2 API.

2.0.1

See the bugs fixed in 2.0.1.

pulp_docker 2.0.1 includes a migration to bring pulp_docker’s file storage scheme in-line with the scheme used in the Pulp platform.

To apply this migration, follow the Upgrade steps seen below, in the 2.0.0 release notes.

See https://pulp.plan.io/issues/1818 for more details.

2.0.0

pulp_docker 2.0.0 is a major version update from the 1.0.x series. The primary highlight is that it is capable of managing both Docker v1 and Docker v2 content. As a result, there are some new unit types introduced in 2.0:

  • Blob - This unit represents a single layer of the Docker Image.
  • Manifest - This unit contains the metadata about a Docker Image and references Blobs.
  • Tag - This unit is used to mark Manifests as being tagged within a repository.

Unfortunately, docker save does not output Docker v2 content so it is not currently possible to upload Docker v2 content into Pulp. Users who wish to manage Docker v2 content must use the sync feature to bring the objects into Pulp. Docker v1 content can still be uploaded as before.

Another exciting development in pulp_docker 2.0 is that it is now included as part of the upcoming Fedora 24 release.

pulp_docker 2.0 requires at least Pulp 2.8.

pulp-admin Changes

The pulp-admin extensions have been updated to reflect these new content types. With Docker v1 content, users would interact with Image objects when promoting content between repositories. With the new v2 content types, users will now primarily interact with the Tag and Manifest objects which will automatically bring along the correct Blob objects when being copied or removed. The heirarchy of some of the commands has changed since users now need to specify whether they wish to operate on Images, Tags, or Manifests where in pulp-docker 1.x the client assumed the user was interacting with Images.

There are also new --enable-v1 and --enable-v2 flags when creating or updating repositories. These flags allow users to specify whether they want Pulp to attempt to use the Docker v1 and/or v2 APIs when synchronizing with a remote registry.

Users will also notice that many of the TLS flags that are commonly used in other content types have also been added to the repo create and update commands in pulp-docker 2.0.

Feed Changes

If you are used to synchronizing content from index.docker.io and you want to start using v2 content, you will now need to use registry-1.docker.io as your feed URL. Additionally, you will need to make use of the –enable-v1 and –enable-v2 flags when using either of these feeds because each feed reports that it can do both protocols when they do not. For example, if you wish to synchronize v2 content you need to make sure you use registry-1.docker.io with --enable-v1 false (this is the default).

API Changes

  • There are some new importer keys called enable_v1 and enable_v2. These are each boolean values that enable or disable the importer from attempting to synchronize with the v1 or v2 Docker APIs when communicating with a feed.
  • There are two new error codes:
    • DKR1007 indicates a failure to find the requested repository when synchronizing with a remote feed.
    • DKR1008 indicates a failure to find the requested Docker API version(s) when synchronizing with a remote feed.
  • A new V2 Redirect File format has been introduced to describe Pulp repositories to Crane for Docker v2 content.
  • The publishing paths have changed to insert /v1 and /v2. For example, what had been published to /var/lib/pulp/published/docker/ before is now published to /var/lib/pulp/published/docker/v1/.

Upgrade

To upgrade, simply follow these steps (substituting for systemctl as appropriate, if you are not using systemd):

  1. Stop all Pulp services on every machine that is part of the installation:

    $ for s in {pulp_workers,pulp_resource_manager,pulp_celerybeat,httpd,goferd}; do sudo systemctl stop $s; done;

  2. Upgrade the Pulp packages on every machine:

    $ sudo yum update

  3. Apply database migrations:

    $ sudo -u apache pulp-manage-db

  4. Start the Pulp services:

    $ for s in {pulp_workers,pulp_resource_manager,pulp_celerybeat,httpd,goferd}; do sudo systemctl start $s; done;

Bugfixes

See the bugs fixed in 2.0.0.