Skip to content

Commit

Permalink
Clarifications around manifest reference validation
Browse files Browse the repository at this point in the history
Be more specific for missing references in all manifests and
not just image manifests.

Signed-off-by: James Hewitt <[email protected]>
  • Loading branch information
Jamstah committed Nov 30, 2021
1 parent 6a86e71 commit f6a4a0d
Showing 1 changed file with 7 additions and 6 deletions.
13 changes: 7 additions & 6 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <sup>[apdx-2](#appendix)</sup>
- **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 <sup>[apdx-2](#appendix)</sup>, such as the image manifest or the image index.</sup>
- **Config**: a blob referenced in the Manifest which contains Artifact metadata. Config is defined under the OCI Image Spec <sup>[apdx-4](#appendix)</sup>
- **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 <sup>[apdx-3](#appendix)</sup>
Expand Down Expand Up @@ -189,11 +189,12 @@ 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 <sup>[code-1](#error-codes)</sup>.
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.
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.
When a manifest is rejected for this reason, it must result in one or more `MANIFEST_BLOB_UNKNOWN` errors <sup>[code-1](#error-codes)</sup>.

##### Pushing blobs

There are two ways to push blobs: chunked or monolithic.
Expand Down Expand Up @@ -556,9 +557,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 |
Expand Down

0 comments on commit f6a4a0d

Please sign in to comment.