How can one reference such as alpine:3.20 work on both linux/amd64 and linux/arm64 machines — what does the registry return, and how is the correct variant selected?

## The problem A container image contains compiled binaries for one CPU architecture and one OS. `alpine:3.20` must nevertheless work on an x86-64 CI runner, an Apple-silicon laptop and an arm64 cloud node. Something has to choose. ## The index (manifest list) The registry solves it with one more level of indirection. A tag may point at an **image index** — media type `application/vnd.oci.image.index.v1+json`, or the older Docker `application/vnd.docker.distribution.manifest.list.v2+json`. Its body is essentially: ``` manifests: [ { digest: sha256:aaa..., platform: { os: linux, architecture: amd64 } }, { digest: sha256:bbb..., platform: { os: linux, architecture: arm64, variant: v8 } }, ... ] ``` Each entry is a descriptor pointing at a normal, single-platform image manifest, which in turn points at that platform's config and layers. ## Resolution at pull time 1. The client requests the manifest for the tag, sending `Accept` headers that list both index and manifest media types. 2. The registry returns whatever the tag points at. Older clients that do not advertise index types may get an error or a fallback single manifest. 3. If it is an index, the client compares its runtime platform — os, architecture, and where relevant `variant` (arm/v7, arm64/v8) — with each entry. 4. It fetches only the matching manifest, then only that variant's config and layers. So a multi-arch tag costs nothing extra in bandwidth: you never download the other architectures' layers. ## Digests and indexes The index itself has a digest. When you pin `alpine@sha256:…` from a multi-arch tag, you are usually pinning the *index* digest, and the same pin still resolves correctly on every architecture — the platform selection happens after the digest lookup. That is the reference you normally want. Pinning a per-platform manifest digest instead locks the deployment to one architecture, which is occasionally deliberate and usually a mistake in a mixed fleet. This also explains why the same repo digest can accompany different local image IDs on different machines: the index digest is shared, the resolved config differs. ## Building multi-arch images `docker buildx` is the standard route. `docker buildx build --platform linux/amd64,linux/arm64 -t repo/app:1.0 --push .` builds each platform (natively on multi-node builders, or via QEMU emulation on one host) and pushes an index that ties the results together. `docker buildx imagetools create` can also assemble an index from manifests that were built and pushed separately, which suits pipelines where each architecture builds on its own native runner. Build-tool-driven image building has its own conventions; the registry-side artifact is the same index either way. ## Inspecting `docker buildx imagetools inspect repo/app:1.0` lists the platforms in the index; adding `--raw` prints the index JSON exactly as stored. `docker manifest inspect` does the same for older workflows. If the output shows a single manifest with a `config` and `layers` section rather than a `manifests` array, the tag is single-platform. ## Failure modes worth naming - **`exec format error` on start**: a single-arch image landed on a different architecture. The image is fine; the reference simply had no variant for that platform. - **Silent emulation**: with binfmt_misc/QEMU registered, a foreign-arch image runs, but far slower and sometimes with subtle syscall differences. Teams often discover this as a mysterious CPU regression. - **`--platform` on run versus build**: `docker run --platform` selects from an index (or forces emulation); `docker build --platform` sets what you produce. Confusing the two produces images that are correct locally and broken in the cluster. - **Attestations in the index**: buildx may add provenance/SBOM entries with `platform.architecture: unknown`. Tools that assume every index entry is a runnable image mis-report them.