Push, Pull & the Registry API

## What an image is, in registry terms Three kinds of object live in a repository: - **Blobs** — opaque content-addressed byte streams: each filesystem layer (a compressed tar) and the image **config** JSON (architecture, env, entrypoint, layer `diff_id` list, history). Every blob is named `sha256:<hex>` computed over its exact bytes. - **Manifest** — a small JSON document listing the config blob and the ordered layer blobs by digest and size, with a media type. - **Tag** — a mutable pointer in the repository's namespace that resolves to a manifest. For multi-platform images there is an extra level: an **index** (OCI image index / Docker manifest list) whose entries are per-platform manifests. Pushing one means pushing each platform manifest and its blobs, then the index. ## The wire sequence **Step 0 — authorization.** The first API call gets a `401` with a bearer challenge; the client obtains a token for scope `repository:<name>:pull,push`. Push needs both actions because the existence checks are reads. **Step 1 — existence checks.** For every blob the image references: ``` HEAD /v2/team/app/blobs/sha256:ab12... ``` `200 OK` (with `Docker-Content-Digest` and `Content-Length`) means present — skip. `404` means upload. This single step is why a rebuild that changes only the top layer pushes almost nothing: all base layers already exist in the repository. **Step 2 — upload sessions.** For each missing blob: ``` POST /v2/team/app/blobs/uploads/ → 202 Accepted, Location: /v2/team/app/blobs/uploads/<uuid> ``` Then either: - **Monolithic**: `PUT <location>?digest=sha256:ab12...` with the whole body, or - **Chunked**: repeated `PATCH <location>` with `Content-Range`, finished by `PUT <location>?digest=sha256:ab12...` with an empty body. The registry hashes what it received and compares with the claimed digest. A mismatch is rejected — a client cannot store content under a digest that does not describe it, which is the property the whole trust model rests on. Success is `201 Created` with the canonical blob location. Uploads for different blobs run in parallel (a handful at a time by default), and an interrupted session can be resumed or simply retried. **Step 3 — cross-repository blob mount.** When the same registry already stores a blob in another repository the client may read: ``` POST /v2/team/app/blobs/uploads/?mount=sha256:ab12...&from=team/base ``` `201 Created` means the blob was linked into this repository with zero bytes on the wire. If the registry declines (no permission on the source, or unsupported), it returns `202` with a normal upload session and the client falls back to uploading. This is what makes copying or re-tagging an image between repositories on one registry nearly free. **Step 4 — the manifest.** ``` PUT /v2/team/app/manifests/1.2 Content-Type: application/vnd.oci.image.manifest.v1+json ``` The registry validates that every digest referenced in the manifest exists in this repository, stores the manifest under its own digest, and points the tag at it. The response carries `Docker-Content-Digest` — the image's digest, which is how you get the `name@sha256:...` reference that pins content. For a multi-platform push, each platform manifest is PUT first (usually by digest), then the index referencing them. ## Why order matters The manifest is the only object that makes an image *usable*: a tag pointing at a manifest is what a pull resolves. If it were written first, there would be a window in which the tag existed but its blobs did not, and any concurrent pull would fail with missing blobs. Blob-first, manifest-last makes publication effectively atomic from a reader's point of view: before the PUT the tag has its old value (or none), after it the whole image is complete. Registries enforce this by rejecting manifests whose referenced blobs are absent. The same reasoning explains why an interrupted push leaves no broken image — just orphaned blobs, which the registry's garbage collection later reclaims because nothing references them. ## Things that surprise people - **Existence checks are per repository, not per registry.** The same layer stored under `team/base` is not visible to `team/app`'s HEAD check, even on one server, hence the mount API. - **Push is a write of existing bytes, not a build.** The layers were already produced locally; push never re-compresses in the classic flow, so digests stay stable. - **`403` at the first upload with a successful login** means the token lacked the `push` action for the scope — authentication succeeded, authorization did not. - **Blob downloads on the pull side frequently redirect** to object storage with a signed URL; the push side generally goes to the registry directly. - **The pull is the mirror image**: GET the manifest (with `Accept` headers listing acceptable media types), pick the platform entry if it is an index, GET the config, then GET each missing layer in parallel and unpack it.