中文
devexamples
← Recipes

阅读中文版本

Build Multi-Architecture Images with buildx

Build and push amd64 and arm64 variants in one command so the same tag runs on mixed clusters.

~35 mincontainerdockerops

Task

Produce a multi-arch image manifest with buildx and verify platform support.

When to use this

A deployment fails on arm64 nodes because the image only exists for amd64.

Prerequisites

  • Docker with buildx
  • A builder supporting QEMU
  • Registry push access

Steps

1. Build and push both platforms to one tag.

docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/org/app:1.2.3 --push .

Expected output: A multi-arch manifest is pushed under a single tag.

2. Inspect the manifest for supported platforms.

docker buildx imagetools inspect ghcr.io/org/app:1.2.3

Expected output: The manifest lists both linux/amd64 and linux/arm64.

Troubleshooting

Problem

Build very slow under emulation

Solution

Use native builders or cross-compilation where possible.

Problem

Arm image fails at runtime

Solution

Check base image support and native binaries copied into the image.

Limitations

  • Emulated builds are slow.
  • Base images must support each platform.
  • Adds CI cost.

What this recipe does

Produce a multi-arch image manifest with buildx and verify platform support.

A deployment fails on arm64 nodes because the image only exists for amd64.

Prerequisites

  • Docker with buildx
  • A builder supporting QEMU
  • Registry push access

Procedure

  1. Build and push both platforms to one tag.
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/org/app:1.2.3 --push .

Expected result: A multi-arch manifest is pushed under a single tag.

  1. Inspect the manifest for supported platforms.
docker buildx imagetools inspect ghcr.io/org/app:1.2.3

Expected result: The manifest lists both linux/amd64 and linux/arm64.

How to confirm it worked

Run the commands above and confirm every expected result in order. If a step does not produce the stated output, use the troubleshooting notes before continuing. A passing run shows the manifest lists both platforms and the same tag runs on amd64 and arm64 nodes.

Troubleshooting

Build very slow under emulation — Use native builders or cross-compilation where possible.

Arm image fails at runtime — Check base image support and native binaries copied into the image.

Limitations

  • Emulated builds are slow.
  • Base images must support each platform.
  • Adds CI cost.