You must publish one container image tag that runs on both linux/amd64 and linux/arm64. How do you build and publish it with docker buildx, and what are the trade-offs between emulation and native or cross-compiled builds?

## What a multi-platform image is A registry tag can point at an **image index** (also called a manifest list) rather than a single image manifest. The index lists entries, each with a platform descriptor (os, architecture, optionally variant such as v8) and a digest of that platform's manifest. When a client pulls the tag, it reads the index, selects the entry matching its own platform, and pulls only those layers. So users on Apple Silicon and users on x86 servers use the same tag and get different bytes. buildx is the CLI that orchestrates producing all of those and assembling the index. ``` docker buildx build --platform linux/amd64,linux/arm64 -t repo/app:1.2.3 --push . ``` The result must go somewhere that can hold an index. A registry can (--push); the classic local image store cannot represent multiple platforms under one tag, so --load fails for a multi-platform build. You can also export with --output type=oci,dest=out.tar. Inspect the result with docker buildx imagetools inspect repo/app:1.2.3. ## Three ways to execute the foreign architecture **Emulation with QEMU.** The kernel's binfmt_misc mechanism routes execution of foreign-architecture binaries to a QEMU user-mode emulator. Registering the handlers is usually docker run --privileged --rm tonistiigi/binfmt --install all, which Docker Desktop does for you. Then a single amd64 machine can run arm64 RUN steps. It is by far the easiest to set up and entirely adequate for image assembly work: installing packages, copying files. It is poor for CPU-bound work: compiling a large codebase under emulation can be three to ten times slower, and occasionally a toolchain or a JIT crashes or hangs under emulation, producing failures that reproduce nowhere else. **Native builder nodes.** buildx supports a builder made of multiple nodes with different platforms: docker buildx create --name multi --platform linux/amd64 ... then --append a node with --platform linux/arm64. Each platform's work is dispatched to hardware that runs it natively. This is the fastest general answer and the one that scales, but it means operating builders on both architectures, which most cloud CI now supports with arm64 runners. **Cross-compilation.** For languages with good cross-compilation, pin the build stage to the builder's own architecture and pass the target through: ``` FROM --platform=$BUILDPLATFORM golang:1.23 AS build ARG TARGETOS TARGETARCH RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app . FROM alpine:3.20 COPY --from=build /out/app /app ``` The compile runs natively on amd64 while emitting an arm64 binary; only the tiny final stage is platform-specific. Note the args must be re-declared inside the stage to be usable there. This is the best of both worlds for Go and Rust; it becomes harder with cgo, native extensions, or when the build runs tests that must execute on the target architecture. ## Practical pitfalls **Single-platform base images.** If your FROM resolves to an image with no arm64 entry, the arm64 build fails outright. Check with docker buildx imagetools inspect. This is also the reason digest pinning must target the index digest rather than one platform's manifest, otherwise you have silently made the Dockerfile single-arch. **Downloading architecture-specific binaries.** A RUN that curls a release asset with a hard-coded x86_64 name breaks on arm64. Use $TARGETARCH to select, remembering the naming mismatch: TARGETARCH is amd64/arm64 while many projects publish x86_64/aarch64. **Caching.** Each platform has its own cache lineage; a cache exported from an amd64 build does not accelerate arm64. Plan cache scope per platform. **Testing.** Building for a platform does not prove it works there. Under emulation a smoke test is possible but slow and not fully representative; the credible answer for production is running the test suite on native hardware of each architecture. **Variants.** arm64 has variants (v8 and newer) and arm32 has v6/v7; being sloppy about variant strings leads to images that pull on a Raspberry Pi but crash. Prefer explicit platform strings. ## Choosing If builds are quick or mostly package installation, emulation is fine and costs nothing to adopt. If compilation dominates and your language cross-compiles cleanly, cross-compile. If neither holds, or you need to run tests on target, invest in native builder nodes. Many pipelines mix them: cross-compile the binary, then assemble and smoke test per platform.