From 1bde24826eb245b3501431212ed5011227091230 Mon Sep 17 00:00:00 2001 From: Chris Aniszczyk Date: Tue, 23 Jan 2018 09:53:48 -0600 Subject: [PATCH 01/11] Add distribution spec project proposal Signed-off-by: Chris Aniszczyk --- proposals/distribution.md | 61 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 proposals/distribution.md diff --git a/proposals/distribution.md b/proposals/distribution.md new file mode 100644 index 0000000..a082774 --- /dev/null +++ b/proposals/distribution.md @@ -0,0 +1,61 @@ +# Abstract + +The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/index.md](https://github.com/docker/distribution/blob/master/docs/spec/index.md)). + +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) + +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). + +In the past when the topic of having an OCI specification around the distribution of container images, it was deferred as "let’s get the image format defined, mean while the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images. + +There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move. + +## Initial Maintainers + +* Stephen Day (@stevvooe) +* Vincent Batts (@vbatts) +* Derek McGowan (@dmcgowan) + +Additional Maintainers to consider: + +* Ahmet Alp Balkan (Google) +* Matt Moore (Google) +* Yuwa (MSFT) +* Clayton Coleman (Red Hat) +* Antonio Murdaca (@runcom) (Red Hat) +* Samuel Karp (@samuelkarp) (AWS) +* Mike Brown (IBM) +* Jimmy Zelinskie jimmy@coreos.com (@jzelinskie) +* Liu Genping <[liugenping@huawei.com](mailto:liugenping@huawei.com)> +* Vanessa Sochat (@vsoch) + +## Code of Conduct + +This project would incorporate (by reference) the OCI Code of Conduct ([https://github.com/opencontainers/tob/blob/master/code-of-conduct.md](https://github.com/opencontainers/tob/blob/master/code-of-conduct.md)). + +## Governance and Releases + +This project would incorporate the Governance and Releases processes from the OCI project template: [https://github.com/opencontainers/project-template](https://github.com/opencontainers/project-template). + +## Project Communications + +Both of the proposed projects would continue to use existing channels in use by the OCI developer community for communication including: + +* GitHub for issues and pull requests +* The dev@opencontainers.org email list +* The monthly OCI developer community conference call +* The #OpenContainers freenode IRC channel + +## Versioning / Roadmap + +The API spec is currently considered v2 and we will start the specification at v2.0. Fewer places to change and compare, and it would keep with it being a lateral move. + +## Frequently Asked Questions (FAQ) + +* Does this include the code of the docker-registry? + * No. This is an API specification discussion. + From c1a5479665e4ee14d824ab9c1ddb5e8de51d6e1e Mon Sep 17 00:00:00 2001 From: Chris Aniszczyk Date: Tue, 23 Jan 2018 14:42:46 -0600 Subject: [PATCH 02/11] Make updates after community feedback Signed-off-by: Chris Aniszczyk --- proposals/distribution.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index a082774..24f2047 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -1,6 +1,6 @@ # Abstract -The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/index.md](https://github.com/docker/distribution/blob/master/docs/spec/index.md)). +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)). In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem. @@ -10,7 +10,7 @@ TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https 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). -In the past when the topic of having an OCI specification around the distribution of container images, it was deferred as "let’s get the image format defined, mean while the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images. +In the past when the topic of having an OCI specification around the distribution of container images was discussed, it was deferred as "let’s get the image format defined, meanwhile the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images. There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move. @@ -31,7 +31,7 @@ Additional Maintainers to consider: * Mike Brown (IBM) * Jimmy Zelinskie jimmy@coreos.com (@jzelinskie) * Liu Genping <[liugenping@huawei.com](mailto:liugenping@huawei.com)> -* Vanessa Sochat (@vsoch) +* Vanessa Sochat (@vsoch) (Stanford) ## Code of Conduct @@ -59,3 +59,7 @@ The API spec is currently considered v2 and we will start the specification at v * Does this include the code of the docker-registry? * No. This is an API specification discussion. +## Related GitHub Issues + +* Simplifies tag listing: docker/distribution#2169 +* Allows listing of manifests: docker/distribution#2199 From 6dc227c86698e7f51e04332bc150c8f73da2b4e3 Mon Sep 17 00:00:00 2001 From: Eduardo Arango Date: Tue, 23 Jan 2018 16:46:33 -0500 Subject: [PATCH 03/11] Join Maintainers Hi I would like to be part of the Maintainers team: affiliation: Sylabs / Singularity email: eduardo@sylabs.io --- proposals/distribution.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/distribution.md b/proposals/distribution.md index 24f2047..1dcdccb 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -32,6 +32,7 @@ Additional Maintainers to consider: * Jimmy Zelinskie jimmy@coreos.com (@jzelinskie) * Liu Genping <[liugenping@huawei.com](mailto:liugenping@huawei.com)> * Vanessa Sochat (@vsoch) (Stanford) +* Eduardo Arango (@ArangoGutierrez) (Sylabs) ## Code of Conduct From d20c56d8c3f64f813f79ccb3853461748313c854 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 26 Jan 2018 10:38:38 -0800 Subject: [PATCH 04/11] README: Link to the distribution proposal Signed-off-by: W. Trevor King --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 3157a21..3c4470a 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ https://groups.google.com/a/opencontainers.org/forum/#!forum/tob (tob@opencontai ## Project Proposals * [Digest](https://github.com/opencontainers/tob/blob/master/proposals/digest.md) +* [Distribution Spec](https://github.com/opencontainers/tob/blob/master/proposals/distribution.md) * [Image Format Spec](https://github.com/opencontainers/tob/tree/master/proposals/image-format) * [SELinux](https://github.com/opencontainers/tob/blob/master/proposals/selinux.md) * [Tools](https://github.com/opencontainers/tob/blob/master/proposals/tools.md) From a928e2b49b2b3718ccd2ca595a882a8ce933f76b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 26 Jan 2018 10:27:15 -0800 Subject: [PATCH 05/11] 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]. This commit also add's Mike's interoperability statement [7], which mentions one reason for the OCI inclusion is the implementation-agnostic location where implementers can collaborating on a common specification. The project scoping is open to drift with the limits imposed by the TOB's scope table. If the TOB thinks subsequent drift is excessive, they are free to make further scope-table adjustments in follow-up proposals. I've also added Mike's library/busybox scoping example [8]. [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 [7]: https://github.com/opencontainers/tob/pull/35#discussion_r163644412 [8]: https://github.com/opencontainers/tob/pull/37#discussion_r164564620 Signed-off-by: W. Trevor King --- proposals/distribution.md | 95 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 4 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 1dcdccb..b7d01bd 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -1,16 +1,17 @@ # 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). In the past when the topic of having an OCI specification around the distribution of container images was discussed, it was deferred as "let’s get the image format defined, meanwhile the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images. +This proposal also provides the container ecosystem with a means to discuss and schedule extensions to the distribution specification. There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move. @@ -57,10 +58,96 @@ 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. + It 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” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests]. + 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. + For example, “what images are under `library/`?” is out of scope for this project. + + * 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 repositories is a multi-repository action, which is out of scope for this entry. + Creating and deleting repositories are per-repository actions, which are out of scope for this entry. + Listing images within repositories is a per-repository action, which is out of scope for this entry. + * Why: This specification will provide one (of possibly many) distribution specifications. + Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is currently out of scope for the OCI. + +* “Retrieving images by their content-addressable hash”. + Docker's registery API already provides endpoints for fetching manifest objects by digest][get-manifest]. + Docker's registery API does not currently provides endpoints for fetching image 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 image 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/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md +[get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest +[iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml +[manifests]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23 +[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 From 5e0175e255f12d7cc44658ee73bd5889ef339ec1 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 27 Feb 2018 09:13:12 -0800 Subject: [PATCH 06/11] distribution: Copy-edits for the scope table There's precendent in the scope table for "Not currently being worked" (the "Creating Reference spec for optional DNS based naming & distribution" entry [1]), but "Work not yet started" (from the "Archival Format" entry [1]) is a more complete fragment. The "...provide a standardized way to use DNS..." line is part of the "Creating a reference spec for optional DNS based naming and discovery" entry, so I'm dropping it from the "Specifying authentication and authorization schemes" entry. I've dropped one of the "parallel" instances for from the parallel-naming/discovery sentence. No need to say that twice in once sentence. [1]: https://www.opencontainers.org/about/oci-scope-table Signed-off-by: W. Trevor King --- proposals/distribution.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index b7d01bd..18c4d62 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -85,9 +85,8 @@ The following entries should be added to the [scope table][scope]: * 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]. + * Why: As an 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. - It 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. @@ -95,9 +94,9 @@ The following entries should be added to the [scope table][scope]: * 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 + * Status: Work not yet started * 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. + When we address this, we will also allow for alternative 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. @@ -123,13 +122,13 @@ The following entries should be added to the [scope table][scope]: * “Retrieving images by their content-addressable hash”. Docker's registery API already provides endpoints for fetching manifest objects by digest][get-manifest]. - Docker's registery API does not currently provides endpoints for fetching image objects by digest, but this is the project where that will happen. + Docker's registery API does not currently provide endpoints for fetching image 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 image name without relying on a particular naming authority/or system. + * Why: Using a hash as a name is a way to ensure a unique image 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: From 75ede78c007dca8c3b79794ba7507ff846c077d6 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 1 Mar 2018 12:27:37 -0800 Subject: [PATCH 07/11] distribution: Reword scope table to avoid repository/image distinction Mike and I have had a lengthy discussion before realizing that we were not interpreting these terms the same way [1]. This commit replaces some explicit object-type lists with "objects defined in the image specification", which is more concrete than using terms without local definitions. I've also added image-spec links where I do use object-type terms. And I've used the wordy but more explicit "groups of image indexes" instead of "repositories" in most cases. I've also explicitly listed /v2/_catalog as out of scope. It's a higher-level endpoint than the image-spec objects. As Patrick [2] and Stephen [3] pointed out when the endpoint landed, it's for internal administration. Matt suggested keeping it out of the user-facing API on those grounds [4], and while that didn't happen in docker/distribution, I think we want to keep the endpoint out of our distribution spec in order to avoid burdening implementors (because as Patrick pointed out [2], it's an expensive endpoint unrelated to image push/pull). [1]: https://github.com/opencontainers/tob/pull/44#discussion_r171677870 [2]: https://github.com/docker/distribution/pull/653#issue-38160279 [3]: https://github.com/docker/distribution/pull/653#issuecomment-121098561 [4]: https://github.com/docker/distribution/pull/653#issuecomment-121099454 --- proposals/distribution.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 18c4d62..53add39 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -104,30 +104,30 @@ The following entries should be added to the [scope table][scope]: * “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” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests]. + Retrieving image indexes covers the current “tag listing” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests]. 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. + Grouping image indexes in repositories is considered part of distribution policy or content management, which are out of scope for this entry's per-image action. For example, “what images are under `library/`?” is out of scope for this project. * 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 repositories is a multi-repository action, which is out of scope for this entry. - Creating and deleting repositories are per-repository actions, which are out of scope for this entry. - Listing images within repositories is a per-repository action, which is out of scope for this entry. + * Description: Define a protocol for creating, retrieving, updating, and deleting objects defined in the [image specification][image-spec]. + Listing repositories (like [`/v2/_catalog`][catalog]) is a multi-[image-index][] action, which is out of scope for this entry. + Managing groups of image indexes requires multi-[image-index][] actions, which are out of scope for this entry. + Listing image indexes within a group is a multi-[image-index][] action, which is out of scope for this entry. * Why: This specification will provide one (of possibly many) distribution specifications. Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is currently out of scope for the OCI. -* “Retrieving images by their content-addressable hash”. - Docker's registery API already provides endpoints for fetching manifest objects by digest][get-manifest]. - Docker's registery API does not currently provide endpoints for fetching image objects by digest, but this is the project where that will happen. +* “Retrieving image content by its content-addressable hash”. + Docker's registry API already provides [endpoints for fetching manifest objects by digest][get-manifest]. + Docker's registry API does not currently provide endpoints for fetching [image-index][] objects by digest, but this is the project where that will happen. - * What: Retrieving images by their content-addressable hash + * What: Retrieving image content by its 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. + * Description: Specify a protocol for retrieving an [image index][image-index], [manifest][], or other [image specification][image-spec] object from a distribution engine by its content-addressable hash. * Why: Using a hash as a name is a way to ensure a unique image 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. @@ -142,8 +142,12 @@ The following entries should remain in the [scope table][scope] but not be addre * Allows listing of manifests: docker/distribution#2199 [api.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md +[catalog]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#catalog [get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest [iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml +[image-spec]: https://github.com/opencontainers/image-spec/ +[image-index]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md +[manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md [manifests]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23 [rfc6750]: https://tools.ietf.org/html/rfc6750 [rfc7230]: https://tools.ietf.org/html/rfc7230 From 0c2ad7755b0c0e83deef2b4b57e5d408af4d5575 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 6 Mar 2018 15:46:26 -0800 Subject: [PATCH 08/11] distribution: Change from blame to rendered URI for image-index We only need blame views when the Markdown does not provide a specific-enough anchor, and this is a link to the whole file. Signed-off-by: W. Trevor King --- proposals/distribution.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 53add39..457d2da 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -146,7 +146,7 @@ The following entries should remain in the [scope table][scope] but not be addre [get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest [iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml [image-spec]: https://github.com/opencontainers/image-spec/ -[image-index]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md +[image-index]: https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md [manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md [manifests]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23 [rfc6750]: https://tools.ietf.org/html/rfc6750 From 4798414ec5606e8901620b0dbfc70d6561ff864c Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 6 Mar 2018 16:09:48 -0800 Subject: [PATCH 09/11] distribution: Remove IANA auth-scheme sentence Stephen points out that the response code list was missing 403 and that the line is fairly low-level [1]. I agree with Derek [2] that the RFC 7235 reference is sufficient to express the idea, and the less we say, the less likely we are to be wrong ;). [1]: https://github.com/opencontainers/tob/pull/35#discussion_r172687857 [2]: https://github.com/opencontainers/tob/pull/35#discussion_r172702752 Signed-off-by: W. Trevor King --- proposals/distribution.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 53add39..5b371b3 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -86,7 +86,6 @@ The following entries should be added to the [scope table][scope]: * Status: N/A * Description: Defining protocols for authenticating and authorizing distribution access. * Why: As an 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. * “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. @@ -144,7 +143,6 @@ The following entries should remain in the [scope table][scope] but not be addre [api.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md [catalog]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#catalog [get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest -[iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml [image-spec]: https://github.com/opencontainers/image-spec/ [image-index]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md [manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md From d4b530c8cf898bae730842f619bf68e2a0048480 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Wed, 14 Mar 2018 16:58:31 -0700 Subject: [PATCH 10/11] Clean up language around tag listing and repository naming Tag listing should mention the endpoints and external method relying on content addressability. Image repositories should not be referred to as indexes, but rather as image repositories. Signed-off-by: Derek McGowan --- proposals/distribution.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index d6b1f10..efec1cb 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -103,11 +103,10 @@ The following entries should be added to the [scope table][scope]: * “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 image indexes covers the current “tag listing” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests]. - Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well. + Tag-listing (e.g. “what named manifests are in `library/busybox`?”) endpoints are in scope and required for backwards compatibility with clients. - Grouping image indexes in repositories is considered part of distribution policy or content management, which are out of scope for this entry's per-image action. - For example, “what images are under `library/`?” is out of scope for this project. + Managing the grouping of image repository names is considered part of distribution policy or content management, which are out of scope. + For example, “which image repositories are under `library/`?” is out of scope for this project. * What: Specifying a distribution method * In/Out/Future: In scope From 2b4308e02a3ef4d0c03fb48faba5ac2137f7098c Mon Sep 17 00:00:00 2001 From: Stephen J Day Date: Wed, 14 Mar 2018 16:41:32 -0700 Subject: [PATCH 11/11] proposals/distribution: remove non-sense about image indexes Signed-off-by: Stephen J Day --- proposals/distribution.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index efec1cb..e0bb561 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -104,6 +104,7 @@ The following entries should be added to the [scope table][scope]: This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries. Tag-listing (e.g. “what named manifests are in `library/busybox`?”) endpoints are in scope and required for backwards compatibility with clients. + An endpoint for listing image repository names within a registry is considered out of scope for this specification. Managing the grouping of image repository names is considered part of distribution policy or content management, which are out of scope. For example, “which image repositories are under `library/`?” is out of scope for this project. @@ -111,10 +112,7 @@ The following entries should be added to the [scope table][scope]: * What: Specifying a distribution method * In/Out/Future: In scope * Status: In progress (see opencontainers/distribution-spec) - * Description: Define a protocol for creating, retrieving, updating, and deleting objects defined in the [image specification][image-spec]. - Listing repositories (like [`/v2/_catalog`][catalog]) is a multi-[image-index][] action, which is out of scope for this entry. - Managing groups of image indexes requires multi-[image-index][] actions, which are out of scope for this entry. - Listing image indexes within a group is a multi-[image-index][] action, which is out of scope for this entry. + * Description: Define a protocol for creating, retrieving, updating, and deleting content-addressable objects, such as those defined in the [image specification][image-spec]. * Why: This specification will provide one (of possibly many) distribution specifications. Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is currently out of scope for the OCI.