A tag is a name that points at an image. A is a hash of the image's manifest. Tags can be moved. Digests cannot.
| Tag | Digest | |
|---|---|---|
| Looks like | status-page:1.0.0, latest | sha256:6b4c4afb…7dac |
| Chosen by | Whoever pushes | Computed from the content |
| Can point at another image later | Yes, on the next push | No |
| Use it for | Humans, release names | Deployments that must not change |
Pushing to the same tag twice
push #1 (1.0.0 build) push #2 (1.1.0 build)
latest ──► sha256:6b4c… latest ──► sha256:0a54…
sha256:6b4c… (no tag, still stored)Here is that sequence on a local registry. Both builds are pushed as latest:
$ docker push localhost:5000/status-page:latest
latest: digest: sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dac size: 1665
$ docker push localhost:5000/status-page:latest
latest: digest: sha256:0a54ae410ff21f73dcac283b991695aa8a24225468b29323e9d569a221353297 size: 1665Anyone who pulls latest now gets 1.1.0. A server that pulled latest yesterday still runs 1.0.0. The same tag, two different images.
Reading digests
docker images --digests
docker inspect -f '{{index .RepoDigests 0}}' localhost:5000/status-page:latestREPOSITORY TAG DIGEST IMAGE ID CREATED SIZE
localhost:5000/status-page latest sha256:0a54ae410ff21f73dcac283b991695aa8a24225468b29323e9d569a221353297 e92d7afa3bdf 7 seconds ago 139MB
<none> <none> sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dac f7c0d1be242a 17 seconds ago 139MBThe <none> row is the 1.0.0 build. Its tag moved to the new image, so it became .
| Value | What it identifies | Where it comes from |
|---|---|---|
| IMAGE ID | The image config, on this machine | docker images |
| Digest | The manifest, in a registry | docker push, docker pull, --digests |
The same image always produces the same digest. A different build produces a different one.
Pull and run by digest
Append @ and the digest to the repository name. No tag is needed.
docker pull localhost:5000/status-page@sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dacDigest: sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dac
Status: Downloaded newer image for localhost:5000/status-page@sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dacdocker run and Compose image: accept the same form. A digest reference is the only way to be sure that every server runs identical bytes.
Give the old image a stable tag
A digest is hard to read. Tag the image with its version and push that tag, so the release has a name that nobody re-pushes:
docker tag localhost:5000/status-page@sha256:6b4c4afb1f830937811e6b244d931d02449cbba4aca40c6a5492536093fc7dac localhost:5000/status-page:1.0.0
docker push localhost:5000/status-page:1.0.0The push reports the same digest, sha256:6b4c…7dac, because the image is the same.