2.0 Release Notes
=================

2.0.2
-----

See the :fixedbugs:`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 :fixedbugs:`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 :ref:`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):

#. 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;

#. Upgrade the Pulp packages on every machine::

   $ sudo yum update

#. Apply database migrations::

   $ sudo -u apache pulp-manage-db

#. 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 :fixedbugs:`2.0.0`.
