From 1d2f7bc3f16faecbd75a744256bed447446e0b78 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Fri, 26 Jan 2018 10:27:15 -0800 Subject: [PATCH] distribution: Add in-scope and out-of-scope wording 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]: https://github.com/xiekeyang/oci-discovery/pull/64#issue-291807003 [2]: https://github.com/opencontainers/tob/pull/37#issuecomment-360923589 [3]: https://github.com/opencontainers/tob/pull/35#discussion_r164012767 [4]: https://github.com/opencontainers/tob/issues/34#issuecomment-350529321 Signed-off-by: W. Trevor King --- proposals/distribution.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/proposals/distribution.md b/proposals/distribution.md index 1dcdccb..d59f3c5 100644 --- a/proposals/distribution.md +++ b/proposals/distribution.md @@ -1,12 +1,12 @@ # Abstract -The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/api.md](https://github.com/docker/distribution/blob/master/docs/spec/api.md)). +The Docker registry protocol has become the defacto standard across the container registry world. In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem. ## Proposal -TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https://github.com/docker/distribution/tree/master/docs/spec) to [https://github.com/opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec) +TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec). 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). @@ -14,6 +14,12 @@ In the past when the topic of having an OCI specification around the distributio 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. +* Signing images. All resources are content-addressable and can be signed in external systems. +* Discovering images. Discovery and registry protocols are completely separate and do not need to be added together. + ## Initial Maintainers * Stephen Day (@stevvooe) @@ -64,3 +70,8 @@ The API spec is currently considered v2 and we will start the specification at v * Simplifies tag listing: docker/distribution#2169 * Allows listing of manifests: docker/distribution#2199 + +[api.md]: https://github.com/docker/distribution/blob/cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md +[token]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md +[rfc6750]: https://tools.ietf.org/html/rfc6750 +[rfc7235-s2.1]: https://tools.ietf.org/html/rfc7235#section-2.1