From 8dd6a19666a9142ef62f63a820223fb90f06f114 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 1 Mar 2018 12:27:37 -0800 Subject: [PATCH] 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 | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 18c4d62..ed49d7b 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 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. + * 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 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-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,11 @@ 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 [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