Loosen restrictions #44
Conversation
Signed-off-by: Chris Aniszczyk <caniszczyk@gmail.com>
Signed-off-by: Chris Aniszczyk <caniszczyk@gmail.com>
Hi I would like to be part of the Maintainers team: affiliation: Sylabs / Singularity email: eduardo@sylabs.io
Join Maintainers
Signed-off-by: W. Trevor King <wking@tremily.us>
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]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) [5]: opencontainers#35 (comment) [6]: opencontainers#37 (comment) [7]: opencontainers#35 (comment) [8]: opencontainers#37 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
README: Link to the distribution proposal
distribution: Add in-scope and out-of-scope wording
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 <wking@tremily.us>
…py-edits distribution: Copy-edits for the scope table
Signed-off-by: Mike Brown <brownwm@us.ibm.com>
|
I think you meant to target |
proposals/distribution.md
Outdated
| @@ -4,6 +4,8 @@ The Docker registry protocol has become the defacto standard across the containe | |||
|
|
|||
| In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem. | |||
|
|
|||
| This proposal also provides the container ecosystem with a means to discuss and schedule extensions to the distribution specification. | |||
There was a problem hiding this comment.
If you want to add this line here, you should remove it below.
proposals/distribution.md
Outdated
| * 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. |
There was a problem hiding this comment.
I think removing these opens the door for the scope to creep into the content-management slippery-slope. You don't need these to list repositories, create or delete wking, or list wking's images in order to push and pull a wking/busybox image. If the OCI wants to cover some of content-management, that's fine with me, but I'd like it to be clearly separated from distribution so implementations could be compliant distribution engines without needing to implement it. However, I'm happy to take that distinction up with the coming distribution maintainers if the TOB wants to punt on it by removing these lines here.
There was a problem hiding this comment.
One could easily argue specifying a / in a path is a slippery slope.
Listing an item is not the same as managing an item. The whole point of a distribution spec is to enable content management. One can argue that enabling retrieval of a list of contents is content management, however I disagree. IMO retrieving a list of contents that have been pushed is enabling content management not providing content management.
There was a problem hiding this comment.
One could easily argue specifying a / in a path is a slippery slope.
True, but backing that out would break compat with the established API.
The whole point of a distribution spec is to enable content management. One can argue that enabling retrieval of a list of contents is content management, however I disagree. IMO retrieving a list of contents that have been pushed is enabling content management not providing content management.
To avoid getting lost in “enabling” vs. “providing”, I think we should focus on “what workflows should the coming spec enable?”. That's a TOB-level scoping question. We all agree it should enable push/pull of wking/busybox and constituent tags. If you add additional language to the spec for other features (like the ones I was making out-of-scope), you'll want to make sure to label them as OPTIONAL for distribution servers that don't want to implement them. Otherwise you burden those implementations in order to support the content-management API.
There was a problem hiding this comment.
Yes that's the key thing to specify here.. what workflows should the coming spec enable. Specifying what it won't enable is in and of itself a slippery slope :-) If there's a phrasing you want to add to ensure the resulting spec must delineate MUST items necessary to certain primary workflows and further delineate as OPTIONAL the portions of the spec not necessary for the primary workflows that works for me.
There was a problem hiding this comment.
Yes that's the key thing to specify here.. what workflows should the coming spec enable.
So what workflows do these repository endpoints enable? Is the idea that folks can write clients for creating new repositories in an OCI registry before pushing images to it? Or do you need repo create/delete for other purposes?
For listing images with a repository, you mentioned the “I wonder what the rest of my team has created” usecase. If that's an intended usecase, then we should put that this proposal. And the implementation would probably be along the lines of /{repo}/actions, since there are more types of activity than image creation/deletion (e.g. adding/removing tags from images).
I can't think of a usecase for “here are the names of all the images inside this repository” besides getting an overview of small repositories. For browsing larger repositories, I'd expect an image count and a richer search.
If there's a phrasing you want to add to ensure the resulting spec…
This scoping language is about whether the distribution project touches it at all. I think things like REQUIRED vs. OPTIONAL are better discussed in the spec repo once it's created.
There was a problem hiding this comment.
Agree. I see where _catalog has been proposed as out of scope. Would be nice to have versioning design decided in the first spec vs tossed in on the second spec.
Haven't seen a definitive discussion on is <name> in or out of scope, only that it's out of scope with regard to repository (catalog) actions.
Also haven't seen a definitive is GET /v2/<name>/tags/list in or out.. discussion and this is mostly why I want to hold off on saying it or anything similar is out of scope.
Maybe @stevvooe or another maintainer could print out the table and / or spec and use highlighters to show what they think should be out scope, what should be in scope, and what would be a nice to have in scope item once the must have items are finished.
There was a problem hiding this comment.
Haven't seen a definitive is discussion on is
<name>in or out of scope, only that it's out of scope with regard to repository (catalog) actions.
Yeah, we can probably clarify that more. The Docker spec has:
All endpoints will be prefixed by the API version and the repository name:
/v2/<name>/
and then later on:
An "image" is a combination of a JSON manifest and individual layer files. The
process of pulling an image centers around retrieving these two components.The first step in pulling an image is to retrieve the manifest. For reference,
the relevant manifest fields for the registry are the following:
field description name The name of the image. tag The tag for this version of the image.
That isn't particularly clear on whether <name> is a repository (as the first excerpt suggests) or an image (as the second excerpt suggests). I've been using “image” to mean “a collection of tagged/named references”. The image-spec phrasing for that is an “image index”. I think operations that take an image-index name as an argument are in-scope, because image-spec's index object can represent them in manifests. Operations that take or return collections of image-indexes (which I've been referring to as “repositories”) are out-of-scope.
Also haven't seen a definitive is
GET /v2/<name>/tags/listin or out…
I'd been arguing to put that in-scope based on the distinction between “image” (-index) and “manifest” here. I also discuss tag-listing here, although that's currently outside of the scope-table entry.
There was a problem hiding this comment.
Sounds like we are in full agreement on these details then. Just a matter of terminology and approach. That we can be in agreement on the detail but not the proposal is why I think less is more in the proposal wrt to what should be drawn as out of scope (to reduce confusion). Well unless we are going to go the extra mile and describe it to the spec level of detail in the proposal, which then arguably makes it tldr.
There was a problem hiding this comment.
That we can be in agreement on the detail but not the proposal is why I think less is more in the proposal wrt to what should be drawn as out of scope (to reduce confusion).
Ye of little faith ;). I've filed #46 with an attempt at less ambiguous wording.
There was a problem hiding this comment.
well done @wking I like new version. Tower of babel has been brought down.. for the moment anyway :-)
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)
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]: opencontainers#44 (comment) [2]: distribution/distribution#653 (comment) [3]: distribution/distribution#653 (comment) [4]: distribution/distribution#653 (comment)
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]: opencontainers#44 (comment) [2]: distribution/distribution#653 (comment) [3]: distribution/distribution#653 (comment) [4]: distribution/distribution#653 (comment)
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]: opencontainers#44 (comment) [2]: distribution/distribution#653 (comment) [3]: distribution/distribution#653 (comment) [4]: distribution/distribution#653 (comment)
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]: opencontainers#44 (comment) [2]: distribution/distribution#653 (comment) [3]: distribution/distribution#653 (comment) [4]: distribution/distribution#653 (comment)
|
lovely |
This commit removes a few of the restrictions placed on the distribution method proposed in #35. For example, the maintainers should have the freedom to explore adding image listing protocols to go along with the protocols for image, manifest, config, and blob creation, retrieval, and deletion.