Skip to content

Loosen restrictions #44

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.

Sign up for GitHub

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

Closed
wants to merge 11 commits into from
Closed

Loosen restrictions #44

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1bde248
Add distribution spec project proposal
caniszczyk Jan 23, 2018
c1a5479
Make updates after community feedback
caniszczyk Jan 23, 2018
6dc227c
Join Maintainers
ArangoGutierrez Jan 23, 2018
e2fc9af
Merge pull request #36 from ArangoGutierrez/patch-2
caniszczyk Jan 23, 2018
d20c56d
README: Link to the distribution proposal
wking Jan 26, 2018
a928e2b
distribution: Add in-scope and out-of-scope wording
wking Jan 26, 2018
6f1f720
Merge pull request #38 from wking/distribution-readme-link
caniszczyk Feb 7, 2018
6587fa0
Merge pull request #37 from wking/docker-bearer-token-spec
caniszczyk Feb 27, 2018
5e0175e
distribution: Copy-edits for the scope table
wking Feb 27, 2018
5dcd80a
Merge pull request #43 from wking/distribution-scope-copy-edits
caniszczyk Feb 27, 2018
95a6c41
remove will not provide language placed on common distribution use cases
mikebrow Feb 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 2 additions & 6 deletions proposals/distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

@wking wking Feb 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you want to add this line here, you should remove it below.


## Proposal

TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec).
Expand Down Expand Up @@ -107,16 +109,10 @@ The following entries should be added to the [scope table][scope]:
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.
Copy link
Contributor

@wking wking Feb 28, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@mikebrow mikebrow Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@wking wking Mar 1, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@mikebrow mikebrow Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@wking wking Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@mikebrow mikebrow Mar 1, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@wking wking Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/list in 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.

Copy link
Member Author

@mikebrow mikebrow Mar 1, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@wking wking Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@mikebrow mikebrow Mar 1, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well done @wking I like new version. Tower of babel has been brought down.. for the moment anyway :-)

* 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.

Expand Down