From 5cefabcae103c79a4783191a575f50c510c28832 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 26 Jan 2018 10:27:15 -0800 Subject: [PATCH] distribution: Add in-scope and out-of-scope wording Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750 [1]. Folks writing a client that will interact with a Docker registry that uses that auth approach will need a "Docker registry's 'Bearer' additions" spec to follow, but Derek believes the situation is salvageable with external work [2]. Also pin the docker/registry links to a specific version so the links will survive future docker/registry changes (including removing the docs after the OCI picks them up). As long as the TOB-selected version isn't far behind (how far will the spec move during a week of voting?), it should be easy for the new maintainets to catch up on any subsequent drift. The signing scope is from Stephen in [3]. The discovery scope is from Derek [4]. The content-management scope is from Stephen [5] and Liang [6]. [1]: https://github.com/xiekeyang/oci-discovery/pull/64#issue-291807003 [2]: https://github.com/opencontainers/tob/pull/37#issuecomment-360923589 [3]: https://github.com/opencontainers/tob/pull/35#discussion_r164012767 [4]: https://github.com/opencontainers/tob/issues/34#issuecomment-350529321 [5]: https://github.com/opencontainers/tob/pull/35#discussion_r164012767 [6]: https://github.com/opencontainers/tob/pull/37#issuecomment-360968873 Signed-off-by: W. Trevor King --- proposals/distribution.md | 88 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 4 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 1dcdccb..42c9847 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -1,12 +1,12 @@ # Abstract -The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/api.md](https://github.com/docker/distribution/blob/master/docs/spec/api.md)). +The Docker registry protocol has become the defacto standard across the container registry world. In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem. ## Proposal -TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https://github.com/docker/distribution/tree/master/docs/spec) to [https://github.com/opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec) +TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec). This proposal covers the distribution API spec, and while it does not cover the code for the docker-registry, that implementation is considered the reference implementation. There are other implementations of this protocol, not all are open-source though (Google gcr.io, Amazon ECR, CoreOS Quay, Gitlab registry, JFrog Artifactory registry, Huawei Dockyard, etc). @@ -57,10 +57,90 @@ The API spec is currently considered v2 and we will start the specification at v ## Frequently Asked Questions (FAQ) -* Does this include the code of the docker-registry? - * No. This is an API specification discussion. +**Q: Does this include the code of the docker-registry?** + +A: No. This is an API specification discussion. + +**Q: Does this change the OCI Charter or Scope Table?** + +A: Not the charter, but it does change the scope table. +This project is scoped to specifying per-image client ↔ registry interaction with an [HTTP][rfc7230]-based protocol. +The following scope entries should be removed from the [scope table][scope]: + +* “Use of Hash as Content Addressable name for immutable containers”. + This entry is in scope for this project, and a more detailed entry will be added as described below. +* “Creating Reference spec for optional DNS based naming & distribution”. + This entry conflates naming and distribution, which will be separated by this proposal. +* “Standardizing on a particular Distribution method”. + This proposal will provide one (of possibly many) distribution specifications, so the old “There is no current agreement on how to distribute content” no longer applies. + +The following entries should be added to the [scope table][scope]: + +* “Specifying authentication and authorization schemes”. + Docker's current registry uses an [extension][token] of the [`Bearer`][rfc6750] [auth scheme][rfc7235-s2.1]. + Work on specifying Docker's scheme will continue independently, and is orthogonal to the registry API. + + * What: Specifying authentication and authorization schemes + * In/Out/Future: Out of scope + * Status: N/A + * Description: Defining protocols for authenticating and authorizing distribution access. + * Why: As a HTTP-based protocol, clients and servers can negotiate authentication via HTTP's [challenge-response authentication framework][rfc7235-s2.1]. + There is no need for the distribution specification to choose a particular authentication scheme, because clients receiving 401 and 407 responses can use IANA's [HTTP Authentication Scheme Registry][iana-auth] to look up referenced schemes and take appropriate action. +frameworkIt is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use. + +* “Creating a reference spec for optional DNS based naming and discovery”. + Discovery and registry protocols are completely separate and do not need to be added together. + This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” entry. + + * What: Creating a reference spec for optional DNS based naming and discovery + * In/Out/Future: In scope for future specification + * Status: Not currently being worked + * Description: Define a protocol for resolving an image name to retrieval information. + When we address this, we will also allow for alternative, parallel name-to-image discovery protocols in parallel with the OCI-specified protocol. + * Why: It is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use. + There are many good use cases for DNS based distribution, but not all use cases support this. + Furthermore, encoding the location of a bundle into the bundle can cause issues with downloads from alternate locations other than the origin specified in the name. + +* “Specifying a distribution method”. + This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries. + + Retrieving images covers the current “tag listing”, because tags are entries in the image format's manifests array. + Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well. + + Repository actions and listing images within a repository are considered part of distribution policy or content management and are out of scope for this entry's per-image action. + + * What: Specifying a distribution method + * In/Out/Future: In scope + * Status: In progress (see opencontainers/distribution-spec) + * Description: Define a protocol for image, manifest, config, and blob creation, retrieval, and deletion. + Listing, creating, and deleting repositories and listing images within repositories are both out of scope for this entry. + * Why: This specification will provide on (of possibly many) distribution specifications. + Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is out of scope for the OCI. + +* “Retrieving images by their content-addressable hash”. + Docker's registery API does not currently provide endpoints for fetching image or manifest objects by digest, but this is the project where that will happen. + + * What: Retrieving images by their content-addressable hash + * In/Out/Future: In scope + * Status: In progress (see opencontainers/distribution-spec) + * Description: Specify a protocol for retrieving an image from a distribution engine by the image's content-addressable hash. + * Why: Using a hash as a name is a way to ensure a unique and container name without relying on a particular naming authority/or system. + Using hashing for name is an acceptable addition as it does not encode any centralized namespace. + +The following entries should remain in the [scope table][scope] but not be addressed by this project: + +* “Specifying way to attach signatures”. + We don't need to address this as part of distribution, because all resources are content-addressable and can be signed in external systems. ## Related GitHub Issues * Simplifies tag listing: docker/distribution#2169 * Allows listing of manifests: docker/distribution#2199 + +[api.md]: https://github.com/docker/distribution/blob/cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md +[iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml +[rfc6750]: https://tools.ietf.org/html/rfc6750 +[rfc7230]: https://tools.ietf.org/html/rfc7230 +[rfc7235-s2.1]: https://tools.ietf.org/html/rfc7235#section-2.1 +[scope]: https://www.opencontainers.org/about/oci-scope-table +[token]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md