Multi-Arch Images with buildx

driftwood/web has to run on the engineers' arm64 laptops and on amd64 — or Graviton arm64 — production hosts, and one image name should serve the right binary to each without anyone choosing a tag. docker buildx build --platform linux/amd64,linux/arm64 --push builds one image per architecture and publishes them under a single tag as a manifest list: the image index from Chapter 2 topic 08, now produced rather than just read. A host pulling driftwood/web:1.4.0 gets the manifest matching its own architecture automatically.

That single command hides three things worth pulling apart: what the manifest list does on the consumer side, what buildx and its builders do on the producer side, and why --push is not optional. Get those straight and multi-arch stops being the thing that surprises you when production hosts reject the image an arm64 laptop built.

One Tag, Many Architectures

A multi-arch build produces a manifest list under driftwood/web:1.4.0 that maps linux/amd64 and linux/arm64 each to their own per-arch image. This is the consumer side of Chapter 2's manifest list: the daemon on each host reads the list, finds the entry for its own platform, and pulls only that manifest and its layers. The arm64 laptop never downloads the amd64 image and vice versa, yet both used the same name.

buildx and BuildKit Builders

docker buildx drives BuildKit and manages builder instances. The catch is that the default builder targets only the host's architecture — on an amd64 machine it can build amd64 and nothing else. Multi-arch needs a builder backed by either emulation or multiple native nodes, which you create once with docker buildx create and then reuse.

$ docker buildx create --name multi --driver docker-container --use
$ docker buildx inspect --bootstrap          # confirms which platforms it can target

$ docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t registry.driftwood.example/driftwood/web:1.4.0 \
    --push .
# builds one image per arch, assembles the manifest list, writes it to the registry

The docker-container driver is what makes multiple platforms possible — the default docker driver cannot. After the build, there is no per-arch image sitting in docker images to push afterward; buildx wrote the whole index to the registry as part of the build.

QEMU Emulation vs Native Builders

The simplest path registers QEMU so one machine can build foreign architectures in emulation — correct, but slow. For compile-heavy stages, an emulated foreign-arch build can run many times slower than native, sometimes turning a one-minute build into many minutes. The faster path attaches native arm64 and amd64 build nodes so each architecture builds on real hardware. Use emulation for the occasional local cross-build; back CI with native nodes when build time is on the critical path.

Build-and-Push as One Step

--push is required for a multi-arch build because the classic local image store has no representation for a manifest list. buildx assembles the per-arch images and the index and writes them straight to the registry — there is no intermediate docker images entry you could docker push separately. Leave --push off and the build either errors or, with --load, loads exactly one architecture, defeating the point. (The newer containerd image store — default on fresh Docker Engine 29.0+ installs — can hold a multi-platform index locally, so there --load keeps the whole thing; --push stays the portable choice that works on either store.)

This is the mental adjustment from single-arch builds. With one architecture you build, see it locally, then push. With multi-arch the build is the push: the registry is the only place a manifest list can exist, so producing one and publishing it are the same step.

Why arm64 Matters

Apple Silicon laptops are arm64, and AWS Graviton and other arm64 server fleets cut cost per core meaningfully. Shipping only amd64 forces emulation on every dev machine — slow, and occasionally subtly wrong in ways that waste an afternoon — and locks out arm64 production entirely. Building both architectures is the price of running everywhere Driftwood actually runs, and with buildx it is one flag, not a second pipeline.