distribution: Add in-scope and out-of-scope wording #37

wking · 2018-01-26T18:36:16Z

Docker's use of Bearer requires information beyond what's covered in RFC 6749 and 6750. So 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. While I prefer off-the-shelf RFCs for HTTP auth, the Docker registry additions are small enough, and widely used. This change adds the client side of their specification to the new distribution-spec project. [Lots more about which parts of the auth scope would need to be in scope to cover the vanilla vs. Docker-flavored Bearer distinction].

Based on this comment, I've pivoted to not including auth in the distribution scope at all.

wking · 2018-01-26T18:41:40Z

As it stands in 27b0932, this commit also addresses my request for pinned references. I can factor that out if it's a blocker.

wking · 2018-01-26T19:32:23Z

I've pushed 27b0932 → 206fb30, adding explicit notes on scoping this project. The registry ↔ auth-server exclusion is my own suggestion. The signing exclusion is from @stevvooe, and the discovery exclusion is from @dmcgowan.

wking · 2018-01-26T19:58:23Z

On the scoping front, there's also the content-mangement vs. distribution discussion starting here, with @stevvooe putting content-management out of scope. But it's not clear to me where that line gets drawn. Why are listing repositories and adding/deleting images in-scope, while rich search and deleting (and presumably adding) repositories are out of scope? I think some scope limits would be useful here, but we probably want the wording to come from a TOB member or future/current distribution-API maintainer.

stevvooe · 2018-01-26T21:27:27Z

@wking The distinction between content management and distribution is quite clear. The specification was mostly focused on what is needed by a container runtime to interact with a registry. The other parts, such as listing, are to support integration with content management systems, although that has mostly been covered by notification implementations in the registry.

dmcgowan · 2018-01-26T21:47:42Z

This change looks reasonable, the tokens are indeed intended to be opaque and therefore I agree that the relationship between any auth server and the registry is out of scope. Ideally, I would like to exclude the auth server altogether, but first I think we need to enumerate what the current deviations are from the RFCs and how they are applied by the registries. This doc was my attempt to get rid of some of these deviations, but use of the non-standard GET endpoint still persists on many registries. I am not sure why this would need to make it into the spec though, registries are free to support more than what is in the spec. If we specify it, now we are implying that registries which use bearer auth should implement this non-standard method for getting tokens

wking · 2018-01-26T22:12:30Z

Ideally, I would like to exclude the auth server altogether…

The auth protocol is different from the registry API. The overlap is because Docker recycled RFC 6750's Bearer and added additional semantics. Clients which receive a WWW-Authenticate: Bearer … need to be able to say “ah, this is probably a Docker-flavored Bearer token”. The specs could be completely decoupled if Docker coined (and registered with IANA?) a new spec with a DockerBearer (or whatever) auth-scheme.

And yeah, folks could use other auth schemes (e.g. Basic) as they like, since in those cases they wouldn't need to resolve “is this a Docker-flavored Bearer scheme or another Bearer scheme?”.

… but first I think we need to enumerate what the current deviations are from the RFCs and how they are applied by the registries.

I've taken a stab at that here. A vanilla Bearer may not be achievable though, because OAuth2 expects auth-server discovery to happen out of band (e.g. with a “log in with {select-box}” UI”). I don't think they built in a protocol for having the resource server provide the client with that information.

And over to @stevvooe:

The other parts, such as listing, are to support integration with content management systems, although that has mostly been covered by notification implementations in the registry.

So you are in favor of pulling in some content-management, but want to keep the rest outside this distribution spec? That doesn't seem like a clear line to me. And I still don't think that explains why you'd cover image creation/deletion but not repository creation/deletion. I think the boundary would be much clearer with a whitelist like:

In scope:

Image, manifest, config, and blob creation, retrieval, and deletion. Retrieving images covers the current “tag listing”, because tags are entries in the image format's manifests array. Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well.

Out of scope:

Listing, creating, and deleting repositories.
Listing images within repositories.

dmcgowan · 2018-01-26T22:35:32Z

@wking I get that there is a difference in what Docker expects for the WWW-Authenticate header, that does not make it in any way a non-standard scheme by making use of those values in a way that is specific to a client. I am just leery of codifying those non-standard client expectations as part of the specification rather than just using the RFC.

I very much understand that there is a gap today in properly configuring the client to speak oauth with the registry that gave rise to these non-standard interpretations. I have tried to rectify this is in multiple ways, see this or this. We know this is a problem we need to solve because it is a real problem clients face. I just want to make sure we don't unexpectedly enforce one approach at the expense at making a better solution more complex in the future. It is better to start narrow and more general and move to solution that best solves these problems. My expectation is that authorization and discovery is an area that clients will need to be updated for in the future.

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 language is from Stephen in [3]. The discovery scope language is from Derek [4]. [1]: xiekeyang/oci-discovery#64 (comment) [2]: opencontainers#37 (comment) [3]: opencontainers#35 (comment) [4]: opencontainers#34 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

wking · 2018-01-26T22:58:23Z

I am just leery of codifying those non-standard client expectations as part of the specification rather than just using the RFC.

If you think the existing Docker-flavored Bearer scheme is salvageable, that's enough for me (and in the worst case, it could be saved with a new auth-scheme registration). I've pushed 1f9e4a0 → 1d2f7bc, which pivots to listing all auth as out of scope.

Still open for this issue is wording on the content-management scope boundary.

dmcgowan · 2018-01-26T23:09:32Z

proposals/distribution.md


 This proposal covers the distribution API spec, and while it does not cover the code for the docker-registry, that implementation is considered the reference implementation. There are other implementations of this protocol, not all are open-source though (Google gcr.io, Amazon ECR, CoreOS Quay, Gitlab registry, JFrog Artifactory registry, Huawei Dockyard, etc).

 In the past when the topic of having an OCI specification around the distribution of container images was discussed, it was deferred as "let’s get the image format defined, meanwhile the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images.

 There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move.

+This project is scoped to cover the client ↔ registry interaction.  The following are out of scope:
+
+* Authentication and authorization.  Docker's current registry uses an [extension][token] of the [`Bearer`][rfc6750] [auth scheme][rfc7235-s2.1].  Work on specifying Docker's scheme will continue independently, and is orthogonal to the registry API.


Is there anything today which you see as incompatible with standard bearer or basic auth. I think this needs to highlight that bearer and basic auth are in scope as supported mechanisms, however, the extra fields, interpretation of the specified fields, and method for getting a bearer token are not currently in scope.

Is there anything today which you see as incompatible with standard bearer or basic auth.

Nothing in the API spec; it can support anything via the vanilla WWW-Authenticate header. And that would work perfectly for Basic auth or most other auth schemes out of the box. The issue I see with Docker's Bearer extensions is just that they're extensions. Someone getting a WWW-Authenticate: Bearer … response and looking in the IANA registry wouldn't be able to discover the Docker extensions (e.g. the fact that realm is the recommended auth-server). And it's not obvious from the WWW-Authenticate header alone whether the server intended vanilla Bearer semantics or the Docker extension semantics.

I think this needs to highlight that bearer and basic auth are in scope as supported mechanisms…

I don't think you need to do that with normative language, and this scope restriction does not restrict your ability to add informative notes. So you can certainly mention that many registries will use Bearer. But a full decoupling would mean that the only normative link would be via WWW-Authenticate and the IANA scheme list.

liangchenye · 2018-01-27T08:13:01Z

So you are in favor of pulling in some content-management, but want to keep the rest outside this distribution spec? That doesn't seem like a clear line to me. And I still don't think that explains why you'd cover image creation/deletion but not repository creation/deletion. ...

I think image operations are predictable, but repository operations are not. The 'repository' could be explained in a complicated way up to the hub service provider. To me, 'image operation' is the mechanism and 'repository operation' is the policy.

While developing our dockyard project for customer, we meet the 'multiple tenant' requirement and the 'multiple domain' requirement. The 'name' in GET /v2/<name>/manifests/<reference> will be recognized as: GET /v2/<domain-name>/<tenant-name>/<repo-name>/manifests/<reference>.
We have create a repo, create a tenant and create a domain, these operations return different types of response. This kind of policy is meaningless to other hub providers. Unless one day it became another de-fact, maybe we can have a new oci project then, 'management'?

wking · 2018-01-27T15:36:02Z

I think image operations are predictable, but repository operations are not.

That seems to match the white/black lists later in that comment. How do they look to you?

liangchenye · 2018-01-29T08:31:35Z

That seems to match the white/black lists later in that comment. How do they look to you?

In scope and out of scope wording in 'tob/proposal' looks too detail to me.
If we following other proposal/spec style, we need to:

Add a Q&A in the 'FAQ' part of the proposal

Frequenty Asked Questions (FAQ)
Q: Does this change the OCI Charter or Scope Table?
A:  blablabla (we need to change https://www.opencontainers.org/about/oci-scope-table)

Add a Q&A in the 'FAQ' part of the distribution spec

Q: Why doesn't this project mention namespace management?
A:  blablabla
     for exampe namespace operations are taken as namespace management.

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]. [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) Signed-off-by: W. Trevor King <wking@tremily.us>

wking · 2018-01-29T18:39:14Z

On Mon, Jan 29, 2018 at 12:31:35AM -0800, 梁辰晔 (Liang Chenye) wrote: Frequenty Asked Questions (FAQ) Q: Does this change the OCI Charter or Scope Table? A: blablabla (we need to change https://www.opencontainers.org/about/oci-scope-table)

I don't mind if the scoping lives in a FAQ entry or not, but explicitly addressing changes to the scope table is a good idea. I've pushed 1d2f7bc → 847c722 with an initial stab at this. How does that look to you?

mikebrow · 2018-01-29T20:25:48Z

proposals/distribution.md

+    * Status: N/A
+    * Description: Defining protocols for authenticating and authorizing distribution access.
+    * Why: As a HTTP-based protocol, clients and servers can negotiate authentication via HTTP's [challenge-response authentication framework][rfc7235-s2.1].
+        There is no need for the distribution specificaiton to choose a particular authentication scheme, because clients receiving 401 and 407 responses can use IANA's [HTTP Authentication Scheme Registry][iana-auth] to look up referenced schemes and take appropriate action.


/s/specificaiton/specification

/s/specificaiton/specification

Thanks. Fixed with 847c722 → 5cefabc.

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]. [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) Signed-off-by: W. Trevor King <wking@tremily.us>

mikebrow · 2018-01-29T20:34:54Z

proposals/distribution.md

+    Retrieving images covers the current “tag listing”, because tags are entries in the image format's manifests array.
+    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.


We should discuss this. If I can't list or at least search the contents of a repository.. how do I find out what images are in the repository? Is there some valid pattern of use of an image repository without listing and search of the contents within? At the minimum I'd like to see such issues as open for discussion vs explicitly listed as out of scope.

We should discuss this.

Agreed. Previous discussion starting here and here, but pinning this sort of thing down is what this helper PR is about.

If I can't list or at least search the contents of a repository.. how do I find out what images are in the repository?

I think that use-case (like listing/adding/removing repos) is part of a separate content-management API. This distribution spec, on the other hand, is only scoped for per-image actions. For example, how to pull a particular image from a registry is in scope, but discovering an image name to pull is not.

It sounds like you are saying I should be able to get a full manifest list for something explicitly requested eg. namespace "library/" image name "busybox". But listing / searching for "busybox" irregardless of namespace would be out of scope. Let's at least separate the issues a bit more. Content management seems to be to broadly defined here. Managing lists of repos should not be in the same scope as managing manifest lists in a repo.

It sounds like you are saying I should be able to get a full manifest list for something explicitly requested eg. namespace "library/" image name "busybox". But listing / searching for "busybox" irregardless of namespace would be out of scope.

Yes.

Let's at least separate the issues a bit more. Content management seems to be to broadly defined here.

The per-issue scoping is my guess based on these comments.

Managing lists of repos should not be in the same scope as managing manifest lists in a repo.

I'm fine with splitting them up into separate levels, but I don't see why you'd need to be able to list images in a repository to be able to push/pull a given image/manifest. Listing tags/manifests within an image, on the other hand, is in scope with my current wording. Can you provide more detail about how you'd like to see that adjusted?

I'm fine with splitting them up into separate levels, but I don't see why you'd need to be able to list images in a repository to be able to push/pull a given image/manifest.

I guess the point is you might not know what the namespace is for a "given" image, "library/" only works if it's in the default namespace. Other points include, "how do you know what you want if you don't know what's in there."

Listing tags/manifests within an image, on the other hand, is in scope with my current wording. Can you provide more detail about how you'd like to see that adjusted?

I think your wording might be ok, I just wanted to get clarification that I read it correctly. Feel free to add my example. Maybe @stevvooe will inject some comments.

I guess the point is you might not know what the namespace is for a "given" image, "library/" only works if it's in the default namespace.

Right. I'd consider library/busybox to be the image, not just the unqualified busybox.

Other points include, "how do you know what you want if you don't know what's in there."

This is discovery. It's important, but orthogonal and out of scope for this project.

I think your wording might be ok, I just wanted to get clarification that I read it correctly. Feel free to add my example.

Ok, I've pushed 28a8ab3 → 14ad993 incorporating your library/busybox example.

mikebrow · 2018-01-29T20:38:25Z

In the discussion on #35 I was proposing the following type of wording vs explicit out of scope language:

This proposal also provides the container ecosystem with a means to discuss and schedule extensions to the distribution specification.

I worry that we'll have to have a new release and/or go back to the tob for vote for basic reasonable extensions.

wking · 2018-01-29T20:43:09Z

In the discussion on #35 I was proposing the following type of wording vs explicit out of scope language:

This proposal also provides the container ecosystem with a means to discuss and schedule extensions to the distribution specification.

I like that wording, but think it's more about “why are we moving the distribution API from Docker into the OCI?” and less about “what is the scope of the distribution API?”. So I'd like to add both your wording and (orthogonally) the scope-table adjustments. Can you file a separate PR adding your wording?

mikebrow · 2018-01-29T21:16:03Z

It was more about whether we were going to state what MUST be and what CAN NOT be in the distribution API without having to go back to the tob and request approval to extend the api after we have had some reasonable discussion about an extension that the maintainers would like to add. IOW it was about the language provided in the proposal.. whether it has a scope table or a scope process.

wking · 2018-01-29T21:28:55Z

It was more about whether we were going to state what MUST be and what CAN NOT be in the distribution API without having to go back to the tob and request approval to extend the api after we have had some reasonable discussion about an extension that the maintainers would like to add. IOW it was about the language provided in the proposal.. whether it has a scope table or a scope process.

I'm fine with projects getting a scope process and the TOB reaching in only if they feel a particular project is getting too broad. But I'm not sure how to square that with a scope table linked from the charter. Are you suggesting making the scope table entries more vague? Do you think the TOB should be providing scope guidance at all? Maybe just open a new PR as an alternative to this one, so the TOB can compare/contrast the two approaches?

wking · 2018-01-30T05:57:24Z

On Tue, Jan 30, 2018 at 03:43:22AM +0000, 梁辰晔 (Liang Chenye) wrote: I'm not sure about the official process: should we change the scope first? If so, you may need to modify this PR after that change.

The TOB can change both at the same time (with annyone who has write access to opencontainers.org bumping the scope table if/when this proposal is accepted), so I don't see a need to vote on the changes separately. I'd prefer to have the charter and scope table version controlled (in this repository? In a revived web repo [1]?), but without that there's no way to help the opencontainers.org maintainers. But either way, I don't think we need to put two separate proposals in front of the TOB, it can approve the proposal with the associated scope-table changes as a single motion. [1]: opencontainers/web#20 (comment)

mikebrow · 2018-01-30T15:25:20Z

@wking I've gone back and looked at the support you linked regarding marking list and search operations against a repository as out of scope and I just don't find any support in those links. What I did find is listing "repositories" managing repositories in a registry as out of scope. Which is different than listing the contents of a repository. Or maybe I read it wrong. But this seems to be a very important detail.

wking · 2018-01-30T18:23:17Z

On Tue, Jan 30, 2018 at 07:25:20AM -0800, Mike Brown wrote: @wking I've gone back and looked at the support you linked regarding marking list and search operations against a repository as out of scope and I just don't find any support in those links. What I did find is listing "repositories" managing repositories in a registry as out of scope. Which is different that listing the contents of a repository.

I agree that listing repositories and listing images within a repository are different, which is why I specifically mention both as out of scope [1]. The motivation for marking image-listing as out of scope is (following the links from [2]): * @yuwaMSFT2 asked for richer listing [3]. They said “lots of images”, but from the rest of the comment (“list tag by creation time, list manifest by creation”) they may have been talking about listing manifests within an image (which, at least for simple tag-listing, is in-scope [4]). * @stevvooe makes a general comment about many of @yuwaMSFT2's proposals being out-of-scope as content management [5]. * @stevvooe mentions listing as content-management, although he doesn't clarify which sort of listing [6]. He also says that listing is for content-managment systems, and has mostly been replaced by notifications (although notifications don't seem to be covered in docker/distribution's docs/spec). * @liangchenye makes a distinction between repository operations (out of scope) and image operations (in scope) [7], which is the source of my per-image scoping [8]. So listing repositories would be the highest level of operation (out of scope). Creating and deleting repositories, as well as listing images with a repository would be per-repository activity at the next highest level (also out of scope). Creating and deleting images, as well as creating, deleting, and listing tagged manifests and sub-images within an image are per-image activity. That's in-scope, because the necessary structure to back them up is part of image-spec [9]. Does that make sense? [1]: #37 (comment) [2]: #37 (comment) [3]: #35 (comment) [4]: https://github.com/opencontainers/tob/pull/37/files#diff-748aea9c83a752af811a80671d8803d2R108 [5]: #35 (comment) [6]: #37 (comment) [7]: #37 (comment) [8]: https://github.com/opencontainers/tob/pull/37/files#diff-748aea9c83a752af811a80671d8803d2R68 [9]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23

mikebrow · 2018-01-30T19:27:34Z

So listing repositories would be the highest level of operation (out
of scope). Creating and deleting repositories, as well as listing
images with a repository would be per-repository activity at the next
highest level (also out of scope). Creating and deleting images, as
well as creating, deleting, and listing tagged manifests and
sub-images within an image are per-image activity. That's in-scope,
because the necessary structure to back them up is part of image-spec

@wking Most of what you said does make sense. But I don't see support for (or against) "...as well as listing images with[in] a repository would be per-repository activity at the next
highest level (also out of scope)."

I do see support for "Creating and deleting repositories,...would be per-repository activity at the next
highest level (also out of scope)"

I recommend splitting up those two concepts into shorter sentences. IMO combining the two concepts into single decisions is driving the view that they should both be out because they are both similar issues. But really they are not similar issues. One is related to supporting a plural number of repositories in a registry, the other is supporting, properly, a plural number of images (irregardless of which manifest list it is in) in a particular repository.

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>

wking · 2018-01-30T19:37:31Z

On Tue, Jan 30, 2018 at 07:27:35PM +0000, Mike Brown wrote: @wking Most of what you said does make sense. But I don't see support for "...as well as listing images with[in] a repository would be per-repository activity at the next highest level (also out of scope).

Do you disagree my categorizing “listing images within a repository” as a per-repository action? Do you disagree with @liangchenye categorizing repository operations as out of scope [1]? If you agree with both of those, then I think you have to conclude that “listing images within a repository” is out of scope.

I recommend splitting up those two concepts into shorter sentences.

I've pushed fa29c25 → ba3be34, which splits it into three sentences [2]. [1]: #37 (comment) [2]: https://github.com/opencontainers/tob/pull/37/files#diff-748aea9c83a752af811a80671d8803d2R118

mikebrow · 2018-01-30T19:49:37Z

Do you disagree my categorizing “listing images within a repository” as a per-repository action?

no.

Do you disagree with @liangchenye categorizing repository operations as out of scope [1]?

No.

If you agree with both of those, then I think you have to conclude that “listing
images within a repository” is out of scope.

No. IMO listing images, within a registry that supports multiple repositories, is an image listing operation per repository. Image operations performed on a registry that supports multiple repositories can be said to be an image operation per repository, no? The "per repository" part might be conflating the issue. Maybe change the word from repository to registry.. IMO the issue is can you get a list of images through the api, yes or no. A list of images located in one manifest list isn't enough to support being able to get a list of images in the registry, or in a repository if the registry supports multiple repositories. FYI I'm trying not to conflate the issue by introducing name spaces, tags etc..

mikebrow · 2018-01-30T20:09:56Z

@wking a really confusing part of all this is what is the difference between a manifest list and a repository of images based on arch/platform.

wking · 2018-01-30T20:12:13Z

If you agree with both of those, then I think you have to conclude that “listing images within a repository” is out of scope.

No. IMO listing images, within a registry that supports multiple repositories, is an image listing operation per repository.

Ah. I think the focus is on the action argument (in this case, a repository) and not on the results (in this case, a list of images).

IMO the issue is can you get a list of images through the api, yes or no.

I think “no”, because listing images is not a per-image action. I think that scoping distribution as “actions that take image arguments and things that are more granular than that (configs, layers, and other blobs)” is a very clean boundary. Once you start taking other arguments (repositories, users, etc.), you need to define and standardize a whole new set of terms.

But that's just me hanging a more detailed interpretation on @liangchenye's original comment. If the TOB and distribution maintainers feel like they want to embrace (some?) per-repository actions, then more power to them (and they should probably file their own helper PR against #35 with the wording they think makes sense).

@wking a really confusing part of all this is what is the difference between a manifest list and a repository of images based on arch/platform.

An image is something you can represent with the image-spec index structure. That can include as many related (or unrelated) entries as you like. I don't think the distribution API should care about the semantics of each entry.

mikebrow · 2018-01-30T20:29:35Z

For simplicity sake let's call this a list of items. Most folks would agree, I think, that beyond the absolutely necessary apis for performing crud operations on the items, the next most important set of apis is listing and searching the list for the items. Then beyond that one could argue ways to categorize portions of the list and maybe create more lists, then authentication, yada yada.

No argument, on crud. I'm arguing sans any current obvious and explicit language stating that listing and search is not to be considered... that we leave that decision to either the maintainers or the tob.

Not really sure why "list" is such a controversial action. How do I know what I need to delete if I don't have the list of contents? How do I know if anything is even there if I don't know the list of contents?

wking · 2018-01-30T20:54:46Z

For simplicity sake let's call this a list of items. Most folks would agree, I think, that beyond the absolutely necessary apis for performing crud operations on the items, the next most important set of apis is listing and searching the list for the items.

Agreed. But listing/searching images within a repository is not something you need for “a container runtime to interact with a registry” (@stevvooe's wording from here). So it's the next most important operation, but still not important enough to be required for that use case. And as your “yada yada” suggests, it may be a slippery slope if you want to draw the line somewhere outside of what you need for runtimes to push/pull images from a registry.

I'm arguing sans any current obvious and explicit language stating that listing and search is not to be considered... that we leave that decision to either the maintainers or the tob.

This PR is up to the TOB. It's not going to land in #35 without @caniszczyk's approval, and #35 is not going to land in this repo without a TOB vote. More feedback from TOB members on how they would like to scope the distribution-spec project would certainly be welcome (here, or in #35, or on the tob@ mailing list, etc.). Feedback from distribution-spec maintainers would also be welcome, although they won't be a formal body until the TOB accepts #35. This PR is just my recommendation to @caniszczyk for clarifying the scoping in his #35, I'm not the one who's making the decisions.

Not really sure why "list" is such a controversial action.

The use-cases it enables are important, but they are different from “I want to pull/push library/busybox (or whatever) to repository $X”. If you grow the scope to include listing, you'll need to also add clarity on the new use-cases you're trying to cover. Otherwise it's hard to tell if @yuwaMSFT2's rich search request is in or out of scope without per-feature, reactive rulings. Of course, per-feature, reactive rulings are a viable approach. I think we can save some future confusion by thinking through these scoping questions now, but the TOB and/or distribution maintainers may well feel that they'd rather handle the scope questions reactively.

How do I know what I need to delete if I don't have the list of contents?

You keep track of what you've pushed, and you delete it when you don't need it anymore. Alternatively, if you want to delete library/busybox, you just DELETE /v2/<name> (not actually covered in the current Docker API), and see if it 404s or not.

How do I know if anything is even there if I don't know the list of contents?

If you want to pull the library/busybox image, you'd GET /v2/<name> (not actually covered in the current Docker API either). If it 404s, it wasn't there. Discovering the library/busybox[#tag] name is out of scope, and figuring out which registry to pull it from is also out of scope. That doesn't mean that discovering names or host registries is unimportant, they're just complicated issues that are orthogonal to distribution. And as @dmcgowan says, “there is no common way in which discovery is being done”.

mikebrow · 2018-01-30T21:13:40Z

But listing/searching images within a repository is not something you need for “a container runtime to interact with a registry” (@stevvooe's wording from here).

You keep citing that but I don't see where Steve says anything about listing images. What I see him responding to wrt. "listing" is your statement about "listing repositories." Again this is not a subtle difference. Listing images is not the same as listing repositories. You seem to be the only one that has said listing images is out of scope. Or I'm missing some subtlety.

And as your “yada yada” suggests, it may be a slippery slope if you want to draw the line somewhere outside of what you need for runtimes to push/pull images from a registry.'

Yes it's a slippery slope but I think the goal was/is a distribution api not an image crud api.. or again maybe I'm missing something.

The use-cases it enables are important, but they are different from “I want to pull/push library/busybox (or whatever) to repository $X”. If you grow the scope to include listing, you'll need to also add clarity on the new use-cases you're trying to cover. Otherwise it's hard to tell if @yuwaMSFT2's rich search request is in or out of scope without per-feature, reactive rulings. Of course, per-feature, reactive rulings are a viable approach. I think we can save some future confusion by thinking through these scoping questions now, but the TOB and/or distribution maintainers may well feel that they'd rather handle the scope questions reactively.

Yes it might be easier to just say list/search for images might not be included in a first release depending on feedback from the maintainers and/or tob.

mikebrow · 2018-01-30T21:16:25Z

You keep track of what you've pushed, and you delete it when you don't need it anymore. Alternatively, if you want to delete library/busybox, you just DELETE /v2/ (not actually covered in the current Docker API), and see if it 404s or not.

Most use cases will have multiple users for the registry.

... they're just complicated issues that are orthogonal to distribution. And as @dmcgowan says, “there is no common way in which discovery is being done”.

One of the reasons we're discussing this :-)

wking · 2018-01-30T21:28:54Z

On Tue, Jan 30, 2018 at 09:13:41PM +0000, Mike Brown wrote: > But listing/searching images within a repository is not something > you need for “a container runtime to interact with a registry” > ***@***.***'s wording from here). You keep citing that but I don't see where Steve says anything about listing images…

@stevvooe's comment is my source for the intended in-scope use case. The flow for pulling library/busybox#latest *starts* with [1]: * GET /v2/library/busybox/manifests/latest and the flow for pushing library/busybox#latest ends with [2]: * PUT /v2/library/busybox/manifests/latest There's no need in either workflow for “what images are under library/?”.

> And as your “yada yada” suggests, it may be a slippery slope if > you want to draw the line somewhere outside of what you need for > runtimes to push/pull images from a registry.' Yes it's a slippery slope but I think the goal was/is a distribution api not an image crud api.. or again maybe I'm missing something.

I may be missing something too. TOB members and distribution-spec maintainers haven't weighed in on this issue with much clarity, so we're both hunting around for internally-consistent approaches to suggest to them.

Yes it might be easier to just say list/search for images might not be included in a first release depending on feedback from the maintainers and/or tob.

@caniszczyk and/or the TOB are certainly free to go that way. It's not an approach that I'd recommend (so it doesn't go into this PR with my recommendations), but it can certainly go into #35 through another channel. And @caniszczyk and/or the TOB are free to close this PR or suggest changes if they don't like some/all of my recommendations.

Most use cases will have multiple users for the registry.

So you have Alice pushing library/busybox but not telling Bob about it. And you want to support a use case where Bob discovers, using only the registry API, the existence of library/busybox. That's fine. But Alice could also tell Bob about it directly, or write a blog post which Bob discovers via a generic search engine, etc. So, while the TOB and/or distribution maintainers are entitled to their own opinions, I don't see the need to support that workflow in the distribution project. And if they decide to support it, I don't see why @yuwaMSFT2's rich search request [3] would be out of scope (as it apparently is [4]). [1]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest [2]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pushing-an-image-manifest [3]: #35 (comment) [4]: #35 (comment)

mikebrow · 2018-01-30T21:40:41Z

@wking though still don't think anyone said list images is out of scope.. even if one did read it that way a very important part of the thread you link in [4] above is the part where Steve says "there may be an argument about pulling this in."

So just to iterate I'm not asking you to change out of plan to in plan. I'm asking you to reflect in the proposal that "there may be an argument about pulling this in." But yes if you wish, I'll wait till you've finished your edit then I'll pr an update to use the less restrictive language.

wking · 2018-01-30T21:51:39Z

I'm asking you to reflect in the proposal that "there may be an argument about pulling this in."

Having scope discussions is fine. But at the end of the day, the TOB is going to vote for a distribution proposal that makes changes to the scope table. I expect they'd prefer entries like “$A is in scope” and “$B is out of scope”. Things like “$C may be in scope” are important parts of the discussion that happen before the vote while building the proposal, not part of the voted proposal. This is also why I think the TOB should review #35's current “Additional Maintainers to consider” section, update the maintainer set as it sees fit, and then remove the “Additional Maintainers to consider” section before voting.

But yes if you wish, I'll wait till you've finished your edit then I'll pr an update to use the less restrictive language.

Sounds good to me. Then @caniszczyk and the TOB can respond to your recommended changes without me having to be a middle man for that discussion. Can we take that approach with the remainder of your outstanding suggestions as well? They also seem to be about introducing pre-vote, discussion-time wiggle room.

yuwaMSFT2 · 2018-01-30T19:41:27Z

proposals/distribution.md

+    * 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.
+    * Why: Using a hash as a name is a way to ensure a unique and container name without relying on a particular naming authority/or system.


do you mean "a unique image name"?

do you mean "a unique image name"?

Yes, thanks. Fixed with ba3be34 → 110297e. This is an upstream typo:

$ curl -s https://www.opencontainers.org/about/oci-scope-table | grep 'ensure a unique and container' <td style="width: 178px; height: 177px;">Using a hash as a name is a way to ensure a unique and container 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.</td>

so if this PR doesn't land, the TOB probably wants to update that scope-table entry though another channel.

yuwaMSFT2 · 2018-01-30T19:42:22Z

proposals/distribution.md

+        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 does not currently provide endpoints for fetching image or manifest objects by digest, but this is the project where that will happen.


Docker's registry API already supports fetching image or manifest by digest?

Docker's registry API already supports fetching image or manifest by digest?

Ah, I'd missed “The reference may include a tag or digest”. Updated with 110297e → a928e2b. As far as I can tell, the current API doesn't support index CRUD (just per-reference CRUD), so I've left that described as “not currently provid[ed]”.

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>

mikebrow · 2018-01-30T23:13:09Z

[wrt less restrictive language via pr] Can we take that approach with the remainder of your outstanding suggestions as well? They also seem to be about introducing pre-vote, discussion-time wiggle room.

Yes, unless of course this pr is not approved. Cheers!

wking · 2018-01-30T23:21:36Z

[wrt less restrictive language via pr] Can we take that approach with the remainder of your outstanding suggestions as well? They also seem to be about introducing pre-vote, discussion-time wiggle room.

Yes, unless of course this pr is not approved. Cheers!

@caniszczyk, I'm not sure what your plans are for #35. Do you want to weigh in here on whether you think this PR is moving in a useful direction (possibly including @mikebrow's planned follow-up work)? Or would you rather close this and have @mikebrow work up his proposal against #35's current tip?

caniszczyk · 2018-02-27T16:32:54Z

@mikebrow feel free to push any updates in a separate PR

wking · 2018-02-27T16:52:59Z

proposals/distribution.md

+    * Description: Defining protocols for authenticating and authorizing distribution access.
+    * Why: As a HTTP-based protocol, clients and servers can negotiate authentication via HTTP's [challenge-response authentication framework][rfc7235-s2.1].
+        There is no need for the distribution specification to choose a particular authentication scheme, because clients receiving 401 and 407 responses can use IANA's [HTTP Authentication Scheme Registry][iana-auth] to look up referenced schemes and take appropriate action.
+        It is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use.


Oops, this line should be dropped (it's part of the next entry). I'll file a follow-up PR.

wking mentioned this pull request Jan 26, 2018

Add distribution spec project proposal #35

Merged

wking force-pushed the docker-bearer-token-spec branch from 27b0932 to 206fb30 Compare January 26, 2018 19:29

wking force-pushed the docker-bearer-token-spec branch 2 times, most recently from 60cb2d8 to 1f9e4a0 Compare January 26, 2018 19:33

wking changed the title ~~distribution: Also move the Bearer token and OAuth docs~~ distribution: Add in-scope and out-of-scope wording Jan 26, 2018

wking force-pushed the docker-bearer-token-spec branch from 1f9e4a0 to 1d2f7bc Compare January 26, 2018 22:56

dmcgowan reviewed Jan 26, 2018

View reviewed changes

wking force-pushed the docker-bearer-token-spec branch from 1d2f7bc to 847c722 Compare January 29, 2018 18:37

mikebrow reviewed Jan 29, 2018

View reviewed changes

wking force-pushed the docker-bearer-token-spec branch from 847c722 to 5cefabc Compare January 29, 2018 20:31

mikebrow reviewed Jan 29, 2018

View reviewed changes

wking force-pushed the docker-bearer-token-spec branch from fa29c25 to ba3be34 Compare January 30, 2018 19:32

yuwaMSFT2 reviewed Jan 30, 2018

View reviewed changes

wking force-pushed the docker-bearer-token-spec branch from ba3be34 to 110297e Compare January 30, 2018 22:02

wking force-pushed the docker-bearer-token-spec branch from 110297e to a928e2b Compare January 30, 2018 22:08

caniszczyk merged commit 6587fa0 into opencontainers:add-distribution-proposal Feb 27, 2018

wking commented Feb 27, 2018

View reviewed changes

This was referenced Feb 28, 2018

Loosen restrictions #44

Closed

remove will not provide language placed on common distribution use cases #45

Closed

wking deleted the docker-bearer-token-spec branch April 4, 2018 23:18

distribution: Add in-scope and out-of-scope wording #37

distribution: Add in-scope and out-of-scope wording #37

Conversation

wking commented Jan 26, 2018 • edited Loading

wking commented Jan 26, 2018

wking commented Jan 26, 2018 • edited Loading

wking commented Jan 26, 2018

stevvooe commented Jan 26, 2018

dmcgowan commented Jan 26, 2018

wking commented Jan 26, 2018 • edited Loading

dmcgowan commented Jan 26, 2018

wking commented Jan 26, 2018

Choose a reason for hiding this comment

wking Jan 26, 2018 • edited Loading

Choose a reason for hiding this comment

liangchenye commented Jan 27, 2018 • edited Loading

wking commented Jan 27, 2018

liangchenye commented Jan 29, 2018

wking commented Jan 29, 2018 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikebrow commented Jan 29, 2018 • edited Loading

wking commented Jan 29, 2018

mikebrow commented Jan 29, 2018

wking commented Jan 29, 2018 • edited Loading

wking commented Jan 30, 2018 via email

mikebrow commented Jan 30, 2018 • edited Loading

wking commented Jan 30, 2018 via email

mikebrow commented Jan 30, 2018 • edited Loading

wking commented Jan 30, 2018 via email

mikebrow commented Jan 30, 2018 • edited Loading

mikebrow commented Jan 30, 2018

wking commented Jan 30, 2018

mikebrow commented Jan 30, 2018 • edited Loading

wking commented Jan 30, 2018 • edited Loading

mikebrow commented Jan 30, 2018

mikebrow commented Jan 30, 2018

wking commented Jan 30, 2018 via email

mikebrow commented Jan 30, 2018 • edited Loading

wking commented Jan 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikebrow commented Jan 30, 2018

wking commented Jan 30, 2018

caniszczyk commented Feb 27, 2018

wking Feb 27, 2018 • edited Loading

Choose a reason for hiding this comment

wking commented Jan 26, 2018 •

edited

Loading

wking commented Jan 26, 2018 •

edited

Loading

wking commented Jan 26, 2018 •

edited

Loading

wking Jan 26, 2018 •

edited

Loading

liangchenye commented Jan 27, 2018 •

edited

Loading

mikebrow commented Jan 29, 2018 •

edited

Loading

wking commented Jan 29, 2018 •

edited

Loading

mikebrow commented Jan 30, 2018 •

edited

Loading

mikebrow commented Jan 30, 2018 •

edited

Loading

mikebrow commented Jan 30, 2018 •

edited

Loading

mikebrow commented Jan 30, 2018 •

edited

Loading

wking commented Jan 30, 2018 •

edited

Loading

mikebrow commented Jan 30, 2018 •

edited

Loading

wking commented Jan 30, 2018 •

edited

Loading

wking Feb 27, 2018 •

edited

Loading