Pushing a rebuilt version of an 800 MB image often transfers only a few megabytes, and copying that image to a second repository on the same registry can transfer nothing at all. What mechanisms make that possible?

## Content addressing is the foundation A registry stores **blobs** keyed by `sha256:<hex>` of their exact bytes. A layer blob is a compressed tar of the filesystem changes that layer introduces. Because the name is derived from the content, two questions become trivial: "do you already have this?" is a lookup, and "is what you sent me what you claimed?" is a hash comparison. Everything below follows from that. Note the distinction between two digests you will hear about: the **blob digest** names the compressed bytes as stored in the registry, while the **diff_id** in the image config names the *uncompressed* tar. Registry deduplication works on the blob digest. ## Mechanism 1 — skip what already exists Before transferring anything, the push loop issues `HEAD /v2/<name>/blobs/<digest>` for each blob. A `200` means present and the client moves on; a `404` triggers an upload session. For a typical service image: - OS base layers: unchanged across every build → skipped - runtime/JDK layer: unchanged for months → skipped - dependency layer: changes when the lockfile changes → usually skipped - application layer: changes every build → uploaded (a few MB) Hence "800 MB image, 4 MB push". The corollary is a build-time discipline: layers whose content changes on every build should sit at the top, and anything you copy in should be split so that volatile files do not invalidate stable ones. Copying the whole source tree before installing dependencies changes the dependency layer's bytes on every commit, and the push (and everyone else's pull) pays for it. The pull side benefits identically: the client fetches only blobs its local store lacks, so two images sharing a base download it once per host. ## Mechanism 2 — cross-repository blob mount A subtlety trips people up: **existence is checked per repository**. A registry stores each blob once in its backend, but each repository maintains its own set of references to blobs — this is what makes per-repository access control and garbage collection tractable. So `HEAD /v2/team/app/blobs/<digest>` returns 404 even when `team/base` in the same registry holds that exact blob. Without a remedy, copying an image from one repository to another would mean downloading and re-uploading everything through the client. The Registry API provides: ``` POST /v2/team/app/blobs/uploads/?mount=sha256:ab12...&from=team/base ``` - `201 Created` — the blob is now referenced by `team/app`; **no bytes were transferred**. - `202 Accepted` with a `Location` — the registry declined to mount (unsupported, or the caller lacks read access to the source) and handed back a normal upload session; the client uploads as usual. Authorization for a mount needs a token whose scope covers both repositories: `push` on the destination and `pull` on the source. That is why an identity restricted to one namespace silently loses the optimization and falls back to full uploads — a real cause of "why does promoting an image take twenty minutes now". Tools that copy images server-side (registry-to-registry copy utilities, promotion pipelines) lean on this heavily, as does re-tagging an image into a release namespace. ## When deduplication fails to kick in - **Different bytes, same files.** Recompressing a layer, or rebuilding it from scratch with a different tar ordering or timestamps, changes the digest. The content may be logically identical; the registry sees a new blob. Build caching and deterministic layer production preserve digests. - **A different registry.** Mounts work within one registry only. Moving between registries transfers every blob the destination lacks. - **A cache-busting instruction early in the build.** An instruction whose output changes each build invalidates every layer beneath it. - **Squashing or flattening images.** Collapsing everything into one layer produces a single huge blob that changes entirely on every rebuild — you trade a small transfer for a full one, and destroy sharing across images. - **Cross-registry replication with re-signing or re-compression** in the pipeline, which again alters bytes. ## Storage versus transfer Be precise about what is saved. Deduplication in the registry backend means the bytes are stored once regardless of how many repositories reference them; garbage collection removes a blob only once no manifest anywhere references it. Transfer savings come from the existence checks and mounts. On the client side, the local image store also shares layers between images, so pulling a second image built on the same base costs only its unique layers on disk and on the wire.