Clarify repository vs registry terminology #325
Conversation
Signed-off-by: Brandon Mitchell <git@bmitch.net>
sudo-bmitch
requested review from
dmcgowan,
jzelinskie,
jonjohnsonjr,
jdolitsky,
mikebrow,
stevvooe and
vbatts
as code owners
|
+1. |
| @@ -53,6 +53,7 @@ These headers are OPTIONAL and clients SHOULD NOT depend on them. | |||
| Several terms are used frequently in this document and warrant basic definitions: | |||
|
|
|||
| - **Registry**: a service that handles the required APIs defined in this specification | |||
| - **Repository**: a namespace within the registry, commonly represented here as `<name>` between the `/v2/` and API call | |||
There was a problem hiding this comment.
repository is a bit more than just a namespace..
hmm..
There was a problem hiding this comment.
... a concept in registries for isolating API requests from one connection to another, such as for isolating public and private access to the registry in the execution of the APIs in this specification. Referred herein as a namespace in the registry and as <name> in the API examples. This specification does not limit the registry implementation of repositories to any type of namespace or namespace model, nor does this specification define how the registry performs isolation/authentication of the connections.
There was a problem hiding this comment.
@mikebrow if we strip out the "in the registry" text from other parts, would a more minimal definition of Repository that doesn't get into isolation and authentication make sense? I'm trying to mirror the other definitions in their brevity.
There was a problem hiding this comment.
@sudo-bmitch even after removing the "in the registry" text we still have a number of uses of the term repository throughout the spec that hint around at the normal uses of the term. The last sentence could be moved to the requirements section to make it clear that although the specification mentions repositories, it does not restrict or define their namespace isolation models authentication apis etc..
There was a problem hiding this comment.
note the "definition" part was fairly thin.. "a concept in registries for isolating API requests from one connection to another" the rest is examples, the other commonly used terms, and the disclaimer...
There was a problem hiding this comment.
| - **Repository**: a namespace within the registry, commonly represented here as `<name>` between the `/v2/` and API call | |
| - **Repository**: a concept in registries for isolating API requests from one connection to another -- such as for isolating public and private access to the registry in the execution of the APIs in this specification. Referred herein as a namespace in the registry and as`<name>` in the API examples. **Note**: This specification does not limit the registry implementation of repositories to any type of namespace or namespace model, nor does this specification define how the registry performs isolation/authentication of the connections. |
There was a problem hiding this comment.
Circling back to this, the reasoning for using the "namespace" term is because we defined it with the following text throughout the spec:
<name>is the namespace of the repository
I'm avoiding mentioning access restrictions because the spec doesn't go there anywhere else and we don't have a spec for authentication and authorization defined yet (though I would like to see that added). I think the most we can say is that references with a descriptor (index to manifest, manifest to blob) are within a repository and don't cross that boundary. The best word I can think of for that is "namespace" since we've used it so many other places in the spec already.
a concept in registries for isolating API requests from one connection to another
I'm not a fan of defining it based on connections. It implies that the pull of a manifest in one connection could reference blobs in another repository by having a separate connection for that blob. We've leaned pretty heavily on saying that all descriptors are references within the same repository and registries depend on that for implementing access and GC on top of this spec.
| @@ -160,7 +161,7 @@ If the digest does differ, it MAY be the case that the hashing algorithms used d | |||
| See [Content Digests](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) <sup>[apdx-3](#appendix)</sup> for information on how to detect the hashing algorithm in use. | |||
| Most clients MAY ignore the value, but if it is used, the client MUST verify the value against the uploaded blob data. | |||
|
|
|||
| If the manifest is not found in the registry, the response code MUST be `404 Not Found`. | |||
| If the manifest is not found in the repository, the response code MUST be `404 Not Found`. | |||
There was a problem hiding this comment.
repository is optional here...
maybe registry, or repository if restricted to a repository in the registry,
wouldn't say it each time though just this once?
There was a problem hiding this comment.
All of these "in the registry" statements could almost just be removed. I agree it is up to the implementation to determine the scope of a blob or manifest. Repository scope makes the most sense but that might need more explanation above or as part of the implementation guide.
|
Registry implementations define a registry, org, namespace and repository differently, depending on how they share the domain name of the registry: Here's a writeup I did a while ago to help with the terminology: Registry Names, Namespaces, Images, Artifacts & Tags |
Signed-off-by: Brandon Mitchell git@bmitch.net
Several parts of the spec should specify repository instead of registry. This corrects many of them and adds a definition of repository at the top. I opted to leave the Error Codes descriptions unchanged for now since that could be more of a debate. But if you'd like those updated as well, let me know and I can adjust them too.