Multi-Arch Image

A multi-arch image is not a single binary but an OCI Image Index (or Docker Manifest List) containing pointers to platform-specific manifests. When a runtime pulls the image, it inspects this index, matches its own os and architecture fields (e.g., linux/amd64, linux/arm64), and fetches only the appropriate manifest and its layers. This avoids downloading irrelevant binaries, reducing bandwidth and storage overhead. The index is a thin JSON object that acts as a dispatcher, ensuring a single :latest tag resolves correctly whether pulled on an AWS Graviton instance or an x86 workstation.

Each architecture variant stores its compiled binaries in distinct filesystem layers identified by unique content-addressable digests. Key characteristics include:

• Shared base layers: Common files (scripts, static assets) can be deduplicated across architectures using identical layer digests.
• Architecture-specific binaries: Compiled Go binaries, C libraries, or JVM runtimes differ per platform and are stored in separate blobs.
• Efficient storage: Registries like Harbor deduplicate identical blobs globally, so shared layers consume storage only once.
• Pull efficiency: The container runtime only downloads the layers for its matched platform, not the entire multi-arch set.

Creating a multi-arch image requires a build process that compiles or cross-compiles the application for each target platform, then assembles the results into a single index. Tools like Docker Buildx and Podman support this natively. The typical workflow:

• Step 1: Build individual platform images (e.g., myapp:linux-amd64, myapp:linux-arm64).
• Step 2: Push each platform image to the registry.
• Step 3: Use docker manifest create or buildx imagetools create to generate the manifest list referencing all platform digests.
• Step 4: Push the manifest list under a unified tag (e.g., myapp:latest). This process ensures the final tag is a polymorphic entry point, not a single-architecture image.

Container runtimes like containerd and CRI-O implement the OCI distribution spec to resolve multi-arch images at pull time. The resolution logic follows a strict precedence:

1. Match exact os/architecture/variant from the runtime's platform.
2. If no exact match, look for compatible variants (e.g., arm/v7 on arm/v8 hardware).
3. If no compatible match, the pull fails with a manifest-not-found error. This deterministic resolution prevents silent failures where an amd64 binary would be emulated on arm64, ensuring operators are aware of missing platform support immediately.

Signing multi-arch images with tools like Cosign requires signing the manifest list itself, not individual platform manifests. The signature attests to the integrity of the entire index, including all its platform references. Key considerations:

• Single signature: One signature covers all architectures, simplifying verification policies.
• Admission control: Kubernetes Admission Controllers verify the manifest list signature before allowing any platform-specific manifest to be pulled.
• SBOM attachment: An SBOM can be attached as an OCI artifact referencing the index, providing a unified software inventory for all architectures.
• Tamper detection: If any platform manifest is altered, the index digest changes, invalidating the signature.

Registries store multi-arch images as a graph of linked objects. The manifest list references platform manifests, which reference layer blobs. Garbage Collection (GC) policies must account for this linkage:

• Orphaned manifests: If a manifest list is deleted, its referenced platform manifests become untagged but may still be referenced by other indexes.
• Blob sharing: Layers shared between architectures are not deleted until all referencing manifests are removed.
• Retention policies: Tag-based retention rules on the manifest list tag automatically protect all underlying platform-specific artifacts.
• Quota management: A single multi-arch tag can consume significantly more storage than a single-arch image due to multiple sets of architecture-specific layers.