Skip to content

Commit 3619df2

Browse files
caniszczykcaniszczyk
authored
Merge pull request #35 from opencontainers/add-distribution-proposal
Add distribution spec project proposal
2 parents 3cfd045 + b6ec853 commit 3619df2

File tree

2 files changed

+152
-0
lines changed

2 files changed

+152
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ https://groups.google.com/a/opencontainers.org/forum/#!forum/tob (tob@opencontai
2121
## Project Proposals
2222

2323
* [Digest](https://github.com/opencontainers/tob/blob/master/proposals/digest.md)
24+
* [Distribution Spec](https://github.com/opencontainers/tob/blob/master/proposals/distribution.md)
2425
* [Image Format Spec](https://github.com/opencontainers/tob/tree/master/proposals/image-format)
2526
* [SELinux](https://github.com/opencontainers/tob/blob/master/proposals/selinux.md)
2627
* [Tools](https://github.com/opencontainers/tob/blob/master/proposals/tools.md)

‎proposals/distribution.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Abstract
2+
3+
The Docker registry protocol has become the defacto standard across the container registry world.
4+
5+
In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem.
6+
7+
## Proposal
8+
9+
TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec).
10+
11+
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).
12+
13+
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.
14+
This proposal also provides the container ecosystem with a means to discuss and schedule extensions to the distribution specification.
15+
16+
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.
17+
18+
## Initial Maintainers
19+
20+
* Stephen Day <[email protected]> (@stevvooe)
21+
* Vincent Batts <[email protected]> (@vbatts)
22+
* Derek McGowan <[email protected]> (@dmcgowan)
23+
24+
Additional Maintainers to consider:
25+
26+
* Ahmet Alp Balkan (Google)
27+
* Matt Moore (Google)
28+
* Yuwa (MSFT)
29+
* Clayton Coleman (Red Hat)
30+
* Antonio Murdaca (@runcom) (Red Hat)
31+
* Samuel Karp (@samuelkarp) (AWS)
32+
* Mike Brown (IBM)
33+
* Jimmy Zelinskie [email protected] (@jzelinskie)
34+
* Liu Genping <[[email protected]](mailto:[email protected])>
35+
* Vanessa Sochat (@vsoch) (Stanford) <[email protected]>
36+
* Eduardo Arango (@ArangoGutierrez) (Sylabs) <[email protected]>
37+
38+
## Code of Conduct
39+
40+
This project would incorporate (by reference) the OCI Code of Conduct ([https://github.com/opencontainers/tob/blob/master/code-of-conduct.md](https://github.com/opencontainers/tob/blob/master/code-of-conduct.md)).
41+
42+
## Governance and Releases
43+
44+
This project would incorporate the Governance and Releases processes from the OCI project template: [https://github.com/opencontainers/project-template](https://github.com/opencontainers/project-template).
45+
46+
## Project Communications
47+
48+
Both of the proposed projects would continue to use existing channels in use by the OCI developer community for communication including:
49+
50+
* GitHub for issues and pull requests
51+
* The [email protected] email list
52+
* The monthly OCI developer community conference call
53+
* The #OpenContainers freenode IRC channel
54+
55+
## Versioning / Roadmap
56+
57+
The API spec is currently considered v2 and we will start the specification at v2.0. Fewer places to change and compare, and it would keep with it being a lateral move.
58+
59+
## Frequently Asked Questions (FAQ)
60+
61+
**Q: Does this include the code of the docker-registry?**
62+
63+
A: No. This is an API specification discussion.
64+
65+
**Q: Does this change the OCI Charter or Scope Table?**
66+
67+
A: Not the charter, but it does change the scope table.
68+
This project is scoped to specifying per-image client ↔ registry interaction with an [HTTP][rfc7230]-based protocol.
69+
The following scope entries should be removed from the [scope table][scope]:
70+
71+
* “Use of Hash as Content Addressable name for immutable containers”.
72+
This entry is in scope for this project, and a more detailed entry will be added as described below.
73+
* “Creating Reference spec for optional DNS based naming & distribution”.
74+
This entry conflates naming and distribution, which will be separated by this proposal.
75+
* “Standardizing on a particular Distribution method”.
76+
This proposal will provide one (of possibly many) distribution specifications, so the old “There is no current agreement on how to distribute content” no longer applies.
77+
78+
The following entries should be added to the [scope table][scope]:
79+
80+
* “Specifying authentication and authorization schemes”.
81+
Docker's current registry uses an [extension][token] of the [`Bearer`][rfc6750] [auth scheme][rfc7235-s2.1].
82+
Work on specifying Docker's scheme will continue independently, and is orthogonal to the registry API.
83+
84+
* What: Specifying authentication and authorization schemes
85+
* In/Out/Future: Out of scope
86+
* Status: N/A
87+
* Description: Defining protocols for authenticating and authorizing distribution access.
88+
* Why: As an HTTP-based protocol, clients and servers can negotiate authentication via HTTP's [challenge-response authentication framework][rfc7235-s2.1].
89+
90+
* “Creating a reference spec for optional DNS based naming and discovery”.
91+
Discovery and registry protocols are completely separate and do not need to be added together.
92+
This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” entry.
93+
94+
* What: Creating a reference spec for optional DNS based naming and discovery
95+
* In/Out/Future: In scope for future specification
96+
* Status: Work not yet started
97+
* Description: Define a protocol for resolving an image name to retrieval information.
98+
When we address this, we will also allow for alternative name-to-image discovery protocols in parallel with the OCI-specified protocol.
99+
* Why: It is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use.
100+
There are many good use cases for DNS based distribution, but not all use cases support this.
101+
Furthermore, encoding the location of a bundle into the bundle can cause issues with downloads from alternate locations other than the origin specified in the name.
102+
103+
* “Specifying a distribution method”.
104+
This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries.
105+
106+
Tag-listing (e.g. “what named manifests are in `library/busybox`?”) endpoints are in scope and required for backwards compatibility with clients.
107+
An endpoint for listing image repository names within a registry is considered out of scope for this specification.
108+
109+
Managing the grouping of image repository names is considered part of distribution policy or content management, which are out of scope.
110+
For example, “which image repositories are under `library/`?” is out of scope for this project.
111+
112+
* What: Specifying a distribution method
113+
* In/Out/Future: In scope
114+
* Status: In progress (see opencontainers/distribution-spec)
115+
* Description: Define a protocol for creating, retrieving, updating, and deleting content-addressable objects, such as those defined in the [image specification][image-spec].
116+
* Why: This specification will provide one (of possibly many) distribution specifications.
117+
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.
118+
119+
* “Retrieving image content by its content-addressable hash”.
120+
Docker's registry API already provides [endpoints for fetching manifest objects by digest][get-manifest].
121+
Docker's registry API does not currently provide endpoints for fetching [image-index][] objects by digest, but this is the project where that will happen.
122+
123+
* What: Retrieving image content by its content-addressable hash
124+
* In/Out/Future: In scope
125+
* Status: In progress (see opencontainers/distribution-spec)
126+
* Description: Specify a protocol for retrieving an [image index][image-index], [manifest][], or other [image specification][image-spec] object from a distribution engine by its content-addressable hash.
127+
* Why: Using a hash as a name is a way to ensure a unique image name without relying on a particular naming authority or system.
128+
Using hashing for name is an acceptable addition as it does not encode any centralized namespace.
129+
130+
The following entries should remain in the [scope table][scope] but not be addressed by this project:
131+
132+
* “Specifying way to attach signatures”.
133+
We don't need to address this as part of distribution, because all resources are content-addressable and can be signed in external systems.
134+
135+
## Related GitHub Issues
136+
137+
* Simplifies tag listing: docker/distribution#2169
138+
* Allows listing of manifests: docker/distribution#2199
139+
140+
[api.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md
141+
[catalog]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#catalog
142+
[get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest
143+
[image-spec]: https://github.com/opencontainers/image-spec/
144+
[image-index]: https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md
145+
[manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.1/manifest.md
146+
[manifests]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23
147+
[rfc6750]: https://tools.ietf.org/html/rfc6750
148+
[rfc7230]: https://tools.ietf.org/html/rfc7230
149+
[rfc7235-s2.1]: https://tools.ietf.org/html/rfc7235#section-2.1
150+
[scope]: https://www.opencontainers.org/about/oci-scope-table
151+
[token]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md

0 commit comments

Comments
 (0)