Docker image tag vs digest

Both come after the image name and both look like a version, which is why they get treated as one thing. alpine:3.21 and alpine@sha256:… are not two spellings of the same reference. One is a label; the other is a fingerprint.

A tag is a pointer the publisher controls. Docker's documentation says plainly that tags are mutable: alpine:3.21 might mean 3.21.1 today and 3.21.4 three months from now, because the publisher moved the tag when they shipped a patch. For a base image that is often what you want — the tag follows the fixes.

A digest is computed from the image's content. A different image has a different digest, so a digest cannot be moved to point somewhere else; it only ever names the image it was computed from.

So the choice is between two failure modes rather than between right and wrong. A tag can change underneath you. A digest cannot change even when you need it to — pin one and updates, security fixes included, arrive only when somebody changes the digest on purpose.

An image reference is a repository plus a tag (:3.21), a digest (@sha256: and 64 hex characters), or both. A tag is resolved at the moment of the pull: the Kubernetes documentation describes the runtime contacting the registry, resolving the image tag or name to a digest, and downloading any layers not already cached. Every pull by tag is really a pull by whatever digest the tag pointed to at that moment.

Docker shows that resolution if you look. docker pull ubuntu:24.04 prints a Digest: sha256:… line near the end of its output, and docker images --digests lists the digest beside each tag. Docker's documentation calls the digest a content-addressable identifier, predictable as long as the input used to generate the image is unchanged, and accepts it in place of a tag in pull, create, run, rmi and a Dockerfile's FROM.

Kubernetes adds the part that turns a moved tag into an incident. With imagePullPolicy omitted, a tag other than :latest defaults to IfNotPresent, which pulls only if the image is not already on the node; :latest or no tag defaults to Always, and a digest to IfNotPresent. A node that already has myapp:1.4 keeps what it pulled, and a new node pulls whatever myapp:1.4 means today. The documentation states the outcome: if the registry changes what a tag represents, you might end up with a mix of Pods running the old and new code. A digest cannot resolve to anything else, so that mix cannot happen.

Writing both — alpine:3.21@sha256:… — is the form Docker's own documentation uses, and for a name with tag and digest the Kubernetes documentation says only the digest is used for pulling. So in Kubernetes the tag beside a digest chooses nothing. It is a label for whoever reads the manifest, and keeping it accurate after an update is your job.

A team tags releases myapp:<version>, and for a small hotfix re-pushes the same tag rather than bumping the version.

The Deployment uses that tag with the default pull policy, IfNotPresent. Nodes that already ran the release keep their cached image. A node added to the cluster that afternoon pulls the re-pushed one.

Requests now succeed or fail depending on which pod they land on. Every manifest and every kubectl get says the same version, so the first hours go into the application rather than the image.

The opposite mistake looks just as calm. A base image pinned by digest and never updated keeps every vulnerability it had on the day it was pinned. Docker's documentation names this trade-off — pinning opts you out of automated security fixes — and pairs pinning with an updater, suggesting GitHub Dependabot's docker ecosystem, so the pin moves by reviewed pull request instead of never.