-
Notifications
You must be signed in to change notification settings - Fork 49
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Clean up language around tag listing and repository naming #50
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -103,19 +103,16 @@ 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. | ||
An endpoint for listing image repository names within a registry is considered out of scope for this specification. | ||
|
||
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 | ||
* 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]. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The distribution mandate needs to be broader than CAS. I don't think this sentence is broad enough to justify including the mutable, name-addressable tag-listing and tag -> manifest endpoints, which you list as in-scope above. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This sentence is describing the protocol which is based on content-addressable objects. Naming just maps to these objects, the objects themselves are not mutable. It is clearly listed up above that these mapping endpoints are in scope and will be supported. The protocol however can be used without this tagging. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
The protocol uses content-addressable objects with a mutable, name-addressable layer on top (like Git's refs). Of the endpoints listed here, only
So add a sentence that includes this naming in the scope? As long as any mentions of “naming” are clearly distinct from the out-of-scope “… DNS based naming…” entry.
Right, but that text is just informative background that won't end up in the scope table. I think we want normative language that will end up in the scope table to explain why tag listing and name-addressable references are in scope. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Can you propose a sentence to add and we can discuss. I don't want to go back and forth on the correctness of the description. I am not sure how the scope table is generated, sounds like the previous sentences are just there for the proposal but unrelated to the scope table at https://www.opencontainers.org/about/oci-scope-table There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
My previous attempt is what you're removing here ;). I was trying to lean on image-spec indexes and There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I think @caniszczyk just updates WordPress based on the instructions here after the TOB approves the proposal. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I get that, the problem is that image-spec indexes and that annotation have nothing to do with the distribution specification, so it was confusing. The annotation may be the same as what the registry has, but there is no relationship in the API. The reason the current tag endpoints are included are for backwards compatibility and there are discussions which need to be had about updating that interface and capabilities. However the point of this proposal is to take the specification as is and keep the scope narrowed down. The CAS part of the specification has already been widely agreed on and is good to have in the scope table, we can always broaden later as the discussion matures. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
So add a sentence saying which endpoints are needed for backwards compat? And making it clear that backwards-compat with those endpoints is in-scope while backwards-compat with There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is why I was asking about the format of these entries, these sentences are already there. Are you saying we should just move the sentences from before the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
My intention with the formatting was: * “{What entry}”.
{Detailed informative discussion, intended for the proposal only}.
* What: {What entry}
* In/Out/Future: {Scope entry}
* Status: {Status entry}
* Description: {Normative definiton}
* Why: {High-level informative motivation} If you want to drop the detailed-informative-discussion section entirely because you find it not-very-informative, that's fine with me. For the “Description” entry, how about something like: * Description: Define a protocol for creating, retrieving, updating, and deleting content-addressable objects, such as those defined in the [image specification][image-spec].
Also define, as an optional layer, the `/v2/<name>/tags/list` and `/v2/<name>/manifests/<reference>` endpoints needed for backwards compatibility with existing clients. |
||
* 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. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not totally convinced that tag listing should be included in distribution.
Does "backwards compatibility with clients" here refer to just
docker pull -a
?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Specifically tag listing or tag operations in general?
Also
skopeo inspect
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd argue tags in general but I doubt that would get much traction :)
Reading through the distribution spec, it seems to me that tags are an implicitly-defined mutable layer on top of the CAS with some missing features (e.g. deleting a tag). It would be nice if tags were first class. Merging distribution/distribution#2169 would help with some of my concerns, but I'm not sure what the plan is for the PRs under Related GitHub Issues.
Happy to punt on this for now if it can be improved later, but the registry is currently a mix of a DAG/CAS/CMS and I'd like to scope down 'distribution' to be as narrow as we can get away with.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree with everything you just said 😄
There is where we are with tags right now (what we need to include so clients can continue to work just using the OCI specification) and where we want to be with tagging, which I believe is an explicit tags endpoint like you listed. Ideally the CAS and tagging elements are distinct and the registry API can be used as CAS only. I am trying to communicate that here so we remain open to extension, backwards compatible, and still support just CAS with tagging elsewhere. I think maybe this isn't fully accomplishing that, other than dropping do you have any recommendations for making the point more clear?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jonjohnsonjr The intent of "Related Github Issues" was that these would be merged as part of the specification process. I am not sure at all how my comment about "These should be included" became "Related Github Issues".
In general, for the registry to be useful, you need CAS plus name pinning, so I don't think we can go full CAS here.