Course contentsShow
← Cloud and Infrastructure
Lesson 996 of 2,98919. Container FundamentalsFree lesson

Multi-Architecture Images

Creating and using manifest lists to support multiple CPU architectures (amd64, arm64) from a single image reference.

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

  1. Build separate images for each architecture (amd64, arm64, etc.)
  2. Push each image to the registry with architecture-specific digests
  3. Create a manifest list that points to all variants under one tag
  4. 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.