At 11 p.m. on a release night, two Pods of the same service gave different answers to the same request. Both were running api:latest. Someone had re-pushed latest in the afternoon, and one node had pulled the new image while the other was still using its cached copy. We spent an hour proving the code was fine before anyone looked at the image. Names are part of your deployment, so make them precise.
ghcr.io/skylane/notes-api:1.4.0@sha256:3f1c9e…\n└──┬──┘ └──┬──┘ └───┬───┘ └─┬─┘ └─────┬─────┘\nregistry namespace repo tag digestghcr.io), Amazon ECR, Google Artifact Registry and so on.notes-api:latest isn’t special. latest is just the tag Docker uses when you don’t specify one. It doesn’t mean “newest”, and nothing updates it unless someone pushes it.
For each build that might be deployed, push two tags for the same image:
\n1.4.0.sha-9f2c1ab.When someone reports a bug in “1.4.0”, the SHA tag takes you straight to the code. And the rule that prevents the release-night incident: never push different content under a tag that’s already deployed. If you fix something, that’s 1.4.1. Many registries can enforce this; Amazon ECR, for example, has a tag immutability setting that rejects a push to an existing tag.
Build once, promote many times. The image that passes staging should be the exact image that reaches production, identified by the same digest. Don’t rebuild from the same commit for production “to be safe”: a rebuild can pull a newer base image or a different transitive dependency, and then production runs something no one tested. Promotion is a change to which digest each environment’s manifest points at, not a new build.
\nKeep the registry tidy too. Retention rules that delete untagged images and old SHA tags after a few months keep storage costs down, but exclude anything a manifest still references, or your next rollback will fail on a missing image.
\necho \"$GHCR_TOKEN\" | docker login ghcr.io -u amara-skylane --password-stdin\n\nGIT_SHA=$(git rev-parse --short HEAD)\ndocker buildx build \\\n --platform linux/amd64,linux/arm64 \\\n -t ghcr.io/skylane/notes-api:1.4.0 \\\n -t ghcr.io/skylane/notes-api:sha-$GIT_SHA \\\n --push .\n\ndocker buildx imagetools inspect ghcr.io/skylane/notes-api:1.4.0--password-stdin keeps the token out of your shell history. In CI, use the platform’s short-lived token rather than a personal one. The last command prints the image’s digest and the platforms it contains.
Your laptop may be arm64 (Apple Silicon) while the cluster’s nodes are amd64, or the reverse. An image built for one CPU architecture fails on the other with the terse exec format error. A multi-platform build fixes that: --platform linux/amd64,linux/arm64 builds both variants and pushes an image index, a small list that maps each platform to its own manifest. When a node pulls notes-api:1.4.0, the runtime picks the manifest for its own architecture.
Building for a foreign architecture runs under emulation, which can be slow for heavy npm ci steps. CI runners with native arm64 and amd64 machines are faster when builds grow. To keep multi-platform images locally, Docker needs the containerd image store, which is the default on new Docker Desktop installs; check that it’s turned on in older setups.
A digest guarantees every node runs identical bytes, whatever happens to the tag later. You can deploy with both, and the digest wins:
\nimage: ghcr.io/skylane/notes-api:1.4.0@sha256:3f1c9e…The tag stays in the reference for humans; the runtime pulls by digest. Do the same for base images in your Dockerfile, so a rebuild next month doesn’t silently pick up a different node:24-slim:
FROM node:24-slim@sha256:<digest-from-imagetools-inspect> AS buildPinning trades automatic patches for predictability, so pair it with a bot such as Dependabot or Renovate that opens a pull request when a new base digest is published. You get updates, reviewed and tested, instead of surprises.
\n\nYour image is now named, versioned and published. Before anyone deploys it, you should know what’s inside it, which is the next lesson.
\n","toc":[{"id":"sec-1","text":"Anatomy of an image reference","level":2},{"id":"sec-2","text":"A tagging scheme that holds up","level":2},{"id":"sec-3","text":"Publish to a registry","level":2},{"id":"sec-4","text":"Multi-platform images","level":2},{"id":"sec-5","text":"Pin by digest","level":2}],"takeaways":["An image reference isregistry/namespace/repository:tag@digest; the tag is a movable label, the digest is the content’s fingerprint.","latest is only the default tag name, not the newest build; deploy explicit versions such as 1.4.0 or a Git SHA.","Never push different content under a tag that’s already deployed; enable tag immutability where your registry supports it.","Pinning by digest (@sha256:…) guarantees every node runs the same bytes, for your app and for base images.","Build multi-platform images with docker buildx build --platform linux/amd64,linux/arm64 when developers and servers use different CPUs."],"further":[{"title":"docker image tag","url":"https://docs.docker.com/reference/cli/docker/image/tag/"},{"title":"Multi-platform builds","url":"https://docs.docker.com/build/building/multi-platform/"},{"title":"Images in Kubernetes","url":"https://kubernetes.io/docs/concepts/containers/images/"}],"quiz":[{"q":"Two Pods of the same Deployment, both using notes-api:latest, behave differently. What’s the most likely explanation?
latest always resolves to the newest image on every container start.","why":"It resolves to whatever the tag points to when the node pulls. A node with a cached copy may never pull again."},{"text":"The tag was re-pushed with new content, and the two nodes pulled it at different times.","why":"Correct. Tags are mutable, so the same name meant different bytes on different nodes. Use versioned tags or digests."},{"text":"One of the Pods is running a corrupted image.","why":"Registries verify layers by digest, so corruption fails the pull instead of running quietly."}],"answer":2},{"q":"What does a digest such as sha256:3f1c… identify?
A developer builds notes-api on an Apple Silicon laptop and pushes it. On the amd64 cluster the Pod logs exec format error. What’s the fix?
EXPOSE for the cluster’s architecture.","why":"EXPOSE documents ports; it can’t change the CPU architecture of the binaries."},{"text":"Switch the base image to Alpine.","why":"Alpine images also come per architecture. The image built on the laptop is still arm64."},{"text":"Set imagePullPolicy to Always on the Deployment.","why":"Pulling again fetches the same arm64-only image."},{"text":"Build with docker buildx build --platform linux/amd64,linux/arm64 (ideally in CI) so the image index contains both.","why":"Correct. The laptop built only arm64. A multi-platform build pushes one tag whose index points at a manifest per architecture."}],"answer":3},{"q":"Which tagging scheme gives the best traceability for notes-api releases?
","options":[{"text":"A semantic version plus a Git SHA tag, for example1.4.0 and sha-9f2c1ab, pushed for the same build.","why":"Correct. The version is what people talk about; the SHA tells you exactly which commit to read when something breaks."},{"text":"Only latest, re-pushed on every merge to main.","why":"You lose any way to tell which build is running, or to roll back to a specific one by name."},{"text":"The build date, such as 2026-10-05.","why":"Two builds on one day collide, and a date doesn’t point to the code that produced it."},{"text":"The developer’s name, such as amara-test.","why":"Fine for a throwaway experiment, useless for knowing what runs in production."}],"answer":0}],"exercise":{"kind":"order","items":["build","test","push","digest","manifest","apply","verify"],"title":"Ship release 1.4.0","prompt":"Put the release steps for notes-api 1.4.0 in order, from source code to a verified deployment that every node runs byte-for-byte.
\n","hints":["You can’t test an image that doesn’t exist, and you can’t read a digest the registry hasn’t seen.","The manifest should reference the digest, so the digest has to be known before you edit it.","Verification comes last, after the cluster has the new spec."],"explanation":"Build the image, test it, push it with its version and SHA tags, read the digest the registry assigned, write that digest into the Deployment manifest, apply it, then verify the rollout. Testing before pushing keeps broken builds out of the registry, and deploying by digest means what you tested is exactly what runs.
\n","checkLabels":{},"itemText":{"build":"docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/skylane/notes-api:1.4.0 -t ghcr.io/skylane/notes-api:sha-9f2c1ab .","test":"Run the test suite and a scan against the built image","push":"Push both tags to ghcr.io","digest":"docker buildx imagetools inspect ghcr.io/skylane/notes-api:1.4.0 to read the digest","manifest":"Set image: ghcr.io/skylane/notes-api:1.4.0@sha256:… in the Deployment manifest","apply":"kubectl apply -f k8s/","verify":"kubectl rollout status deployment/notes-api"}},"words":750,"readMinutes":4}