docker/docker — pull request #9784 by stevvooe (2014-12-23 01:40:14+00:00)
Title: Client Support for Docker Registry HTTP API V2

This PR updates Docker core to support pushes and pulls of images from registries that support Docker Registry HTTP API V2, as proposed in docker/docker#9015. Specifically, functionality has been added to support the V2 API while minimizing changes to the end user experience. The reasons behind this move are to improve security and access control by moving to content addressable layers and using sign-able manifests.

This PR affects the following behavior in docker core:

- `docker login`
- Pull of images.
- Push of images

While the distribution side of docker core may need some refactoring work, the goal of this particular PR is to provide equivalent functionality with the new registry API. Use of a V2 registry should be transparent to the user.

This set of changes will be supported by some accompanying PR:

- Docker Registry HTTP V2 specification (unsubmitted).
- docker logout (unsubmitted)

## Overview

Images may now be pushed and pulled from registries, public and private, that implement the Docker Registry HTTP API V2. Using `registry/v2.URLBuilder`, the client code has been ported to use the URI layout described in the proposal. Definitions for routes and error codes from [next generation docker registry](https://github.com/docker/docker-registry/tree/next-generation) are included. The rest of the changes are devoted to authentication handling and modifying the flow to support image push.

During login, if a registry supports the V2 api, the client will use the base endpoint (“/v2/”) to solicit an authentication challenge. The challenge is then used to login to the appropriate authentication provider. The results are tested against the base endpoint to confirm the credentials are correct. After login, authorization of operations on the registry is maintained using challenges and the stored credentials. If a challenge is issued during an operation against the registry, the client attempts to re-authorize the operation, if possible.

Use of the new image format, covered in docker/docker#8093, is effectively transparent. Image manifests are created and signed transparently. This paves the way for future image verification features. A new API endpoint has been added to the docker engine to get the image manifest for an image. This endpoint can be used to get the image manifest from a daemon, sign it on the client, and push the signed image. The push API endpoint has also been updated to allow a signed manifest to be sent in the post body.

Pulling images is roughly the same as before, with most modifications to this code path consisting of URL updates and authentication management. For pushing images, the POST + PUT monolithic flow is implemented as proposed.

## Testing

There are numerous cases under which the new registry may be used. We suggest that reviewers do take the time to test cases that they care about directly. To ensure that this PR is somewhat ready, we have tested the following combinations against the [next generation registry](https://github.com/docker/docker-registry/tree/next-generation):

- “Production” registry with token auth
- Private registry with token auth
- Private registry with basic auth
- Private registry with no auth

If you need help with reproducing these scenarios, please contact us directly.