Multi-Architecture Images
What you'll learn: How to create and use manifest lists that let a single image tag work seamlessly across different CPU architectures like amd64 and arm64.
The Problem: Different Hardware, Different Images
When you build a container image on an x86_64 machine (amd64), that image won't run natively on an ARM-based server (like AWS Graviton or Apple M-series chips). Traditionally, you'd need separate tags like myapp:1.0-amd64 and myapp:1.0-arm64, forcing users to pick the right one manually.
What Is a Multi-Architecture Image?
A multi-architecture image uses a special construct called a manifest list (or "fat manifest"). When you reference a single tag like myapp:1.0, the registry returns a list of available architectures. The container runtime automatically selects and pulls the correct variant for your machine's CPU.
Think of it like a phone charger with multiple plug adapters—one product reference, but the right plug "snaps in" depending on where you are.
How It Works
- Build separate images for each architecture (amd64, arm64, etc.)
- Push each image to the registry with architecture-specific digests
- Create a manifest list that points to all variants under one tag
- Push the manifest list to the registry
Now when someone runs docker pull myapp:1.0 on their ARM laptop or amd64 server, the registry serves the appropriate image automatically—no manual selection needed.
Why This Matters
Multi-architecture images enable true portability. Developers, CI/CD pipelines, and orchestrators can use the same image reference everywhere, and the platform handles the rest. This is critical as ARM adoption grows in cloud environments and edge devices.
Key Takeaway:
Manifest lists let you publish one image tag that automatically serves the correct architecture-specific variant, making container images truly portable across diverse hardware.