From 049c4326af1aab097e196a398d1529c7f69062b5 Mon Sep 17 00:00:00 2001 From: James Hewitt Date: Thu, 25 Nov 2021 11:49:44 +0000 Subject: [PATCH] Clarifications around manifest reference validation Be more specific for missing references in all manifests and not just image manifests. Signed-off-by: James Hewitt --- spec.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 3a96ee42..e55debe7 100644 --- a/spec.md +++ b/spec.md @@ -57,7 +57,7 @@ Several terms are used frequently in this document and warrant basic definitions - **Push**: the act of uploading Blobs and Manifests to a Registry - **Pull**: the act of downloading Blobs and Manifests from a Registry - **Blob**: the binary form of content that is stored by a Registry, addressable by a Digest -- **Manifest**: a JSON document which defines an Artifact. Manifests are defined under the OCI Image Spec [apdx-2](#appendix) +- **Manifest**: a JSON document which defines an artifact uploaded via the manifests endpoint. A manifest may reference other blobs in a repository via descriptors. Examples of manifests are defined under the OCI Image Spec [apdx-2](#appendix), such as the image manifest or the image index. - **Config**: a blob referenced in the Manifest which contains Artifact metadata. Config is defined under the OCI Image Spec [apdx-4](#appendix) - **Artifact**: one conceptual piece of content stored as Blobs with an accompanying Manifest containing a Config - **Digest**: a unique identifier created from a cryptographic hash of a Blob's content. Digests are defined under the OCI Image Spec [apdx-3](#appendix) @@ -190,9 +190,9 @@ If the blob or manifest is not found in the registry, the response code MUST be #### Push Pushing an artifact typically works in the opposite order as a pull: the blobs making up the artifact are uploaded first, -and the manifest last. Strictly speaking, content can be uploaded to the registry in any order, but a registry MAY reject -a manifest if it references blobs that are not yet uploaded, resulting in a `BLOB_UNKNOWN` error [code-1](#error-codes). -A useful diagram is provided [here](https://github.com/google/go-containerregistry/tree/d7f8d06c87ed209507dd5f2d723267fe35b38a9f/pkg/v1/remote#anatomy-of-an-image-upload). +and the manifest last. A useful diagram is provided [here](https://github.com/google/go-containerregistry/tree/d7f8d06c87ed209507dd5f2d723267fe35b38a9f/pkg/v1/remote#anatomy-of-an-image-upload). + +A registry MAY reject a manifest of any type uploaded to the manifest endpoint if it references blobs that do not exist in the registry. Where a manifest is rejected for this reason, it must result in one or more `MANIFEST_BLOB_UNKNOWN` errors [code-1](#error-codes). ##### Pushing blobs @@ -556,9 +556,9 @@ The `code` field MUST be one of the following: | code-2 | `BLOB_UPLOAD_INVALID` | blob upload invalid | | code-3 | `BLOB_UPLOAD_UNKNOWN` | blob upload unknown to registry | | code-4 | `DIGEST_INVALID` | provided digest did not match uploaded content | -| code-5 | `MANIFEST_BLOB_UNKNOWN` | blob unknown to registry | +| code-5 | `MANIFEST_BLOB_UNKNOWN` | manifest references a blob unknown to registry | | code-6 | `MANIFEST_INVALID` | manifest invalid | -| code-7 | `MANIFEST_UNKNOWN` | manifest unknown | +| code-7 | `MANIFEST_UNKNOWN` | manifest unknown to registry | | code-8 | `NAME_INVALID` | invalid repository name | | code-9 | `NAME_UNKNOWN` | repository name not known to registry | | code-10 | `SIZE_INVALID` | provided length did not match content length |