You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 included /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]: opencontainers#44 (comment)
[2]: distribution/distribution#653 (comment)
[3]: distribution/distribution#653 (comment)
[4]: distribution/distribution#653 (comment)
Copy file name to clipboardExpand all lines: proposals/distribution.md
+14-11Lines changed: 14 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -104,30 +104,30 @@ The following entries should be added to the [scope table][scope]:
104
104
* “Specifying a distribution method”.
105
105
This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries.
106
106
107
-
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].
107
+
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].
108
108
Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well.
109
109
110
-
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.
110
+
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.
111
111
For example, “what images are under `library/`?” is out of scope for this project.
112
112
113
113
* What: Specifying a distribution method
114
114
* In/Out/Future: In scope
115
115
* Status: In progress (see opencontainers/distribution-spec)
116
-
* Description: Define a protocol for image, manifest, config, and blob creation, retrieval, and deletion.
117
-
Listing repositories is a multi-repository action, which is out of scope for this entry.
118
-
Creating and deleting repositories are per-repository actions, which are out of scope for this entry.
119
-
Listing images within repositories is a per-repository action, which is out of scope for this entry.
116
+
* Description: Define a protocol for creating, retrieving, updating, and deleting objects defined in the [image specification][image-spec].
117
+
Listing repositories (like `/v2/_catalog`][catalog]) is a multi-[image-index][] action, which is out of scope for this entry.
118
+
Managing groups of image indexes requires multi-[image-index][] actions, which are out of scope for this entry.
119
+
Listing image indexes within a group is a multi-[image-index][] action, which is out of scope for this entry.
120
120
* Why: This specification will provide one (of possibly many) distribution specifications.
121
121
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.
122
122
123
-
* “Retrieving images by their content-addressable hash”.
124
-
Docker's registery API already provides endpoints for fetching manifest objects by digest][get-manifest].
125
-
Docker's registery API does not currently provide endpoints for fetching image objects by digest, but this is the project where that will happen.
123
+
* “Retrieving image content by its content-addressable hash”.
124
+
Docker's registery API already provides [endpoints for fetching manifest objects by digest][get-manifest].
125
+
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.
126
126
127
-
* What: Retrieving images by their content-addressable hash
127
+
* What: Retrieving image content by its content-addressable hash
128
128
* In/Out/Future: In scope
129
129
* Status: In progress (see opencontainers/distribution-spec)
130
-
* Description: Specify a protocol for retrieving an image from a distribution engine by the image's content-addressable hash.
130
+
* 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.
131
131
* 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.
132
132
Using hashing for name is an acceptable addition as it does not encode any centralized namespace.
133
133
@@ -142,8 +142,11 @@ The following entries should remain in the [scope table][scope] but not be addre
142
142
* Allows listing of manifests: docker/distribution#2199
0 commit comments