Multi-Arch Image Build with Buildx Design Prompt
Design a buildx multi-arch (amd64/arm64) image pipeline with the right builder, cross-compilation strategy, cache export, and a single multi-platform manifest pushed to a registry.
- Target user
- Platform and CI/CD engineers
- Difficulty
- Advanced
- Tools
- Claude, ChatGPT
The prompt
You are a senior build engineer who ships multi-architecture images with Docker buildx and BuildKit. I will provide: - The target platforms I need (e.g. linux/amd64, linux/arm64, linux/arm/v7) - My current Dockerfile and the language/toolchain - My CI runner architecture and whether QEMU/emulation or native ARM runners are available - My registry and where the cache should live Your job: 1. **Choose the build strategy** — decide between QEMU emulation (simple, slow) and native multi-node builders or cross-compilation (fast, more setup); recommend the best fit for the toolchain and justify it. 2. **Make the Dockerfile arch-aware** — use `--platform`, `TARGETPLATFORM`/`BUILDPLATFORM`/`TARGETARCH` build args, and cross-compile where the language supports it (e.g. Go `GOARCH`) instead of emulating the whole build. 3. **Set up the builder** — the `docker buildx create`/`use` commands, QEMU registration if needed, and the `--platform` list. 4. **Wire cache** — registry or gha cache export/import so each arch reuses layers across CI runs. 5. **Build the manifest** — produce a single multi-platform image with `--push` so `docker pull` auto-selects the arch; explain why `--load` cannot hold a multi-arch image locally. 6. **Catch arch pitfalls** — base images missing an arch, native modules, and time/cost of emulated builds. Output as: (a) chosen strategy with rationale, (b) the arch-aware Dockerfile, (c) the full buildx command sequence, (d) the CI job snippet, (e) verification (`docker buildx imagetools inspect <ref>`).
Related prompts
-
Docker Build Failure Diagnosis Prompt
Diagnose a failing `docker build` from the error output and Dockerfile, pinpoint the breaking instruction (cache, COPY path, network, platform, dependency), and give a tested fix.
-
Multi-Stage Dockerfile Size & Build-Cache Optimization Prompt
Refactor a bloated Dockerfile into a lean multi-stage build that maximizes layer cache hits, shrinks the final image, and speeds up CI rebuilds without breaking the runtime.