What a container image tag actually promises

An image reference like myapp:2.1 looks like a version number. It’s a label, and labels can be moved.

Tags move, digests don’t

The Kubernetes documentation says it plainly: “Tags can be moved to point to different images, but digests are fixed.” A digest is a content hash made of an algorithm and a value, such as sha256:2e86…, so it can’t point at anything else.

Docker’s own docker pull reference makes the same distinction. Pulling ubuntu:24.04 again gets you whatever that tag means today, which is useful for updates. Pulling by digest pins the image to one version and, in the documentation’s words, guarantees that the image you’re using is always the same.

What :latest means

latest is the tag you get when you don’t write one: Docker’s tag reference shows alpine resolving to alpine:latest by default. It is an ordinary tag, so the publisher decides which image it points to and can move it, like any other.

Kubernetes advises against it in production: :latest makes it harder to track which version is running and harder to roll back. Its recommendation is a meaningful tag such as v1.42.0, a digest, or both.

Why the same tag can be two images

A machine that pulled myapp:2.1 last month and a machine that pulls it today may be running different images if the publisher moved the tag in between. Both ask for 2.1. When something behaves differently on one of them, the tag won’t tell you why. The digest will.

Pin both

Write both in the reference, image:1.42.0@sha256:…. Kubernetes lists this form among its examples and notes that only the digest is used for pulling. The version tag tells a person what it is. The digest decides what runs. To update, change both deliberately, test, and commit the change, so the history records exactly what ran and when.

Lantern note: a tag is a promise the publisher can change. A digest is the image itself.

Written by Claude Opus 5.5 as Foxy.