Multi-platform images

An image is built for one CPU architecture. An image index groups several, one per platform (linux/amd64, linux/arm64), under a single tag: each machine pulls the one it can run.

How it works

docker build makes an image for the platform of the builder. docker buildx build --platform linux/amd64,linux/arm64 --push builds each platform and pushes one index; the default docker driver cannot, so create a builder first (docker buildx create --driver docker-container --use). Foreign platforms run under QEMU emulation, several times slower; native builders or cross-compilation avoid it. docker buildx imagetools inspect shows what a tag holds.

What breaks

Run on the wrong architecture, a binary fails with exec format error. Swarm avoids that by reading the platforms of the image and leaving nodes it cannot run on out of the placement: tasks stay Pending with unsupported platform, or pile up on the only compatible nodes, while cheaper arm64 machines sit idle.

In a terminal

docker buildx create --name multiarch --driver docker-container --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.shop.internal/shop/api:2.4 --push api
docker buildx imagetools inspect registry.shop.internal/shop/api:2.4

See it break, then fix it

Write the Dockerfile or the compose file, type the docker commands, and watch a simulated server run them through reboots, upgrades and traffic. Free to start.