In an OCI registry, how are blobs, manifests and tags stored and addressed, and which of the three can change after a push?
answer
- three kinds of object per repository
- a name computed from the bytes
- /v2/<name>/blobs/<digest>
- pointer, not content
basics
~20 sAn OCI registry addresses blobs and manifests by digest, a hash of their exact bytes, so neither can change under its name. A tag is a human-readable pointer to one manifest digest, and it is the one name a later push can move.
solid answer
~40 sInside a repository (the `<name>` in `/v2/<name>/...`) a registry holds three things. **Blobs** (layers, config documents, any file) are fetched at `/v2/<name>/blobs/<digest>`, where the digest, such as `sha256:...`, is the hash of the bytes. **Manifests** are JSON documents at `/v2/<name>/manifests/<tag-or-digest>`: an image manifest lists a config blob and layer blobs, and an image index lists manifests, for example one per platform. The registry must store a manifest in the exact bytes it received, so its digest is stable as well. **Tags** are human-readable pointers to a manifest digest; one manifest may carry zero, one or many tags. Pushing a different manifest under an existing tag moves the tag and leaves the old manifest pullable by digest, unless the registry has a tag-immutability setting that refuses it.
code
http · 11 linesGET /v2/team/api/manifests/1.4.2
Accept: application/vnd.oci.image.index.v1+json, application/vnd.oci.image.manifest.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.oci.image.manifest.v1+json
Docker-Content-Digest: sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
GET /v2/team/api/blobs/sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0
HTTP/1.1 200 OK
Docker-Content-Digest: sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0go deeper
Recall the three objects, blob, manifest and tag, and that only the tag is a movable name. Say what a digest is computed from.
Explain why the manifest must be stored byte for byte, and how the image manifest and image index refer to blobs and other manifests through descriptors.
Separate the three deletes, tag, manifest and blob, and say which one actually frees storage and when. Show how moving a tag leaves the old manifest reachable by digest.
Frame digest addressing as the property that makes deduplication, integrity checking and reproducible deployment the same design decision, and what a team gives up when it relies on tags.
## The three objects in a repository The OCI distribution specification defines a **registry** as a service answering a small HTTP API, and a **repository** as the scope for API calls on a collection of content: manifests, blobs and tags. Every path in the API starts with `/v2/<name>/`, where `<name>` is the repository namespace, for example `team/api`. Inside that repository, three kinds of thing matter: | Object | What it is | Addressed by | Endpoint | Can its content change? | |---|---|---|---|---| | **Blob** | Opaque bytes: a layer tarball, a config JSON, any file | Digest only | `/v2/<name>/blobs/<digest>` | No: new bytes are a new digest | | **Manifest** | A JSON document listing other content by descriptor | Digest or tag | `/v2/<name>/manifests/<tag-or-digest>` | No: the registry keeps the exact bytes | | **Tag** | A human-readable name for one manifest | Its own name | Used in place of a digest on the manifests endpoint | Yes: it can be re-pointed | ## Digests: names computed from content A **digest** has the form `algorithm:encoded`, for example `sha256:5b0bcabd...`. The image spec registers `sha256`, `sha512` and `blake3`, and implementations must support SHA-256 verification. Because the name is computed from the bytes: - the same bytes always get the same digest, which is why a registry can keep one stored copy of a layer that many images share; - a client that fetched by digest can hash what it received and prove the content is what it asked for; - the registry **must store a manifest in the exact byte representation the client sent**. Re-indenting the JSON would change the hash and break every reference to the old digest. Successful pull and existence-check responses carry a `Docker-Content-Digest` header with the digest of what was returned, a name kept from the API's origins in the Docker registry protocol. ## Manifests tie blobs together A manifest refers to other content through **descriptors**, each with a `mediaType`, a `digest` and a `size`. Two manifest kinds matter on the registry side: - an **image manifest** (`application/vnd.oci.image.manifest.v1+json`) names one config blob and an ordered list of layer blobs; - an **image index** (`application/vnd.oci.image.index.v1+json`) lists other manifests, typically one per platform, so one name can serve several architectures. Picking the right entry is the client's job; the registry just stores and serves the index. Because a manifest names its blobs by digest and is itself named by digest, the whole object forms a hash tree: one manifest digest pins every byte below it. ## Tags: the only movable name A **tag** is, in the spec's words, a custom, human-readable pointer to a manifest. Tags must match `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}`, so at most 128 characters, and `GET /v2/<name>/tags/list` returns them in lexical or ASCII order, paginated with `n`, `last` and a `Link` header. - A manifest digest may have **zero, one or many** tags. - A `PUT /v2/<name>/manifests/<tag>` with a different manifest **moves** the tag. The previous manifest is not modified; it stays in the repository and is still pullable by digest, now without that tag. - Refusing to move a tag is a **registry setting** (tag immutability), not a property of tags in the spec. ## Push order and what a delete removes A push runs in the reverse order of a pull: 1. Upload each blob (monolithic or chunked), usually after a `HEAD` on `/v2/<name>/blobs/<digest>` shows it is missing. 2. `PUT` the manifest. A registry may reject a manifest that references blobs it does not have, with `MANIFEST_BLOB_UNKNOWN`. 3. Name it: pushing the manifest by tag creates or moves that tag. Deletes come in three distinct phases, and a registry may disable any of them: 1. `DELETE /v2/<name>/manifests/<tag>` removes only the tag; the manifest stays. 2. `DELETE /v2/<name>/manifests/<digest>` removes the manifest, and every tag pointing at it then returns `404`. 3. `DELETE /v2/<name>/blobs/<digest>` removes a blob from the repository. Disk space comes back only when the registry's garbage collection removes bytes nothing references any more. ## What to take from it - Content in an OCI registry is immutable by construction; only the tag-to-digest mapping moves. - "Which image is `1.4.2`?" has a time-dependent answer; "which image is `sha256:...`?" never does. - Storage deduplication, integrity checks and pinning all fall out of the same design: names derived from content.
- When a tag is moved to a new manifest, what happens to the manifest it used to point at?Nothing happens to its content. It stays in the repository and can still be pulled by digest; it simply no longer carries that tag (it may still carry others). Whether it is ever removed depends on the registry's deletion and garbage-collection setup, not on the push that moved the tag.
- Why must the registry keep a manifest's exact bytes instead of re-serialising the JSON?The manifest's digest is the hash of its bytes. Re-serialising, even to semantically identical JSON with different whitespace or key order, would produce a different digest, so every reference pinned to the original digest, including an image index entry, would stop matching. The distribution spec therefore requires the exact byte representation the client pushed.
- Can two repositories in the same registry share one stored copy of a blob?Yes. The API scopes each blob to a repository, but storage is content-addressed, so a registry can keep one copy and reference it from both. A client can even link an existing blob into another repository with a cross-repository mount instead of uploading it again.
Blobs and manifests are like books shelved under a fingerprint of their own text, so changed text is simply a different book. A tag is a 'book of the month' sign that staff can move to another book without altering either book.
- A tag is a second stored copy of the image under another name.
- Pushing to an existing tag rewrites the manifest the tag pointed at.
- The registry assigns digests like database IDs, independent of content.
- Deleting a tag immediately frees the disk space its layers used.
- Each manifest can carry only one tag at a time.
- A registry may reformat manifest JSON as long as the meaning is unchanged.