Tags versus digests

Why can the same name fetch two different things a week apart?

You deploy myapp:1.4.2 on Monday. On Friday, a new machine joins the fleet, pulls myapp:1.4.2, and runs something different — different binary, different behaviour, same name. Nobody edited a config file. The version number did not move.

The instinct is that something went wrong. It did not: the system behaved exactly as designed. So the question worth asking is what a tag was ever promising, and why we so readily heard a promise it never made.

Ask what a registry has to store. It has to store image content, and it has to let people ask for it by some name. Those are two different jobs, and it is worth noticing they could be done by the same identifier or by two.

Take the content first. An image is a manifest listing its layers and its configuration. Give a registry the ability to name that manifest by the hash of its own bytes — sha256: followed by sixty-four hex characters — and something strong follows. That name cannot be reassigned, because changing the content changes the hash. It is not a pointer to the content; it is the content, compressed to a fingerprint. Ask for a digest and either you get exactly those bytes or you get an error, and the client can verify which by hashing what arrived.

Now the second job. Nobody can remember sha256:9b2c.... Humans need a name they can type and reason about, and more than that, they need a name that can move — 1.4 should be able to mean the newest patch in that line, and latest should be able to mean the newest release. A name that moves is precisely a name that is not the content.

So a tag is a mutable pointer: an entry in the registry mapping a human-readable label, within a repository, to one manifest digest. Pushing the same tag again rewrites the entry. That is not a loophole; it is the entire purpose of having a second kind of name.

Follow this through your Monday-to-Friday puzzle and it dissolves. Somebody rebuilt and re-pushed 1.4.2 — perhaps a patched base image, perhaps a rerun of a failed pipeline. The digest changed. The tag now points somewhere else. Monday's machine still runs the old image because it already has those bytes locally; Friday's machine resolves the tag afresh and gets the new ones. Two machines, one name, two images, and no error anywhere.

Which suggests the rule. Use a tag where you want a choice made later — browsing, documenting, telling a human which line to follow. Use a digest where you want a fact fixed now — what a running deployment consists of, what an audit refers to, what a security scan's result is attached to. The reference form myapp@sha256:9b2c... pins it, and the two can be combined as myapp:1.4.2@sha256:9b2c..., which reads as "the thing that was 1.4.2, and here is exactly which thing that was".

One complication worth being accurate about. For a multi-architecture image, the digest a tag points at is usually not an image manifest at all but an index — a manifest list naming one per-platform manifest for each architecture. So myapp@sha256:... is fully deterministic and still resolves to different bytes on an arm64 host than on an amd64 one. That is not tag mutability sneaking back in; it is the index doing its job, and the reference remains reproducible in the sense that matters, since the index itself cannot change.

And latest? It is not special to the registry in any way. It is an ordinary tag with an ordinary name, distinguished only by being the default the client appends when you supply none. Everything unfortunate about it follows from that default, not from any registry behaviour.

Three refinements.

First, the misconception this corrects: version tags are read as immutable because they look like version numbers, and semantic versioning trains us to treat 1.4.2 as a fixed artifact. Nothing in the registry enforces that. It is a convention among the people pushing, and conventions are broken by rebuilds, by mirrors, and by pipelines that retry.

Second, "pin your digests" is not the whole answer either, because a pinned digest never picks up a security fix. The workable arrangement is not to choose one but to separate the roles: let a tool resolve tags to digests deliberately at a chosen moment, record the resolved digest, and deploy that — so updates happen when someone decided they should, rather than whenever a machine happened to pull.

Third, digests give you identity, not trust. A digest proves you received the bytes you asked for; it says nothing about who produced them or whether they are safe. That is a separate mechanism — signing, attestation, provenance — and it is worth keeping the two apart, because "we pin digests" is often offered as a security claim when it is really an integrity and reproducibility claim.

• Image signing and provenance attestations, and what they add on top of a digest.
• Admission controllers that require digest references in a cluster.
• Manifest lists in detail, and how a client selects the right platform entry.

Every term the collection defines is gathered in the glossary.