Multi-Architecture Container Images

External

• https://cloud.google.com/kubernetes-engine/docs/how-to/build-multi-arch-for-arm
• https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/
• https://cloud.google.com/kubernetes-engine/docs/tutorials/migrate-x86-to-multi-arch-arm

Internal

• Docker Concepts
• arch
• Executable Format

Overview

A container image is represented by a manifest, which is JSON-encoded content representing the image's layers, the corresponding size, the hash of the image, etc. For more details, see:

Docker Concepts | Image

This format allows putting multiple container images, each supporting a different architecture, behind the same tag.

This is done with a manifest that contains a list of manifests, so the container engine can pick the one that it matches its runtime. This type of manifest is called a manifest list, and contains a list of different images, one for each architecture.

{
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:5...5",
      "size": 4804,
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:4...5",
      "size": 4803,
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

Inspect the Manifest

podman inspect <image-id>

How to Tell the Architecture from Inside the Container

Execute arch. It will return:

• "aarch64" for ARM 64
• "x86_64" for x86

Building Multi-Architecture Images

The process consists in building and pushing the images for each architecture, then combining them with podman buildx.

podman buildx build --push --platform linux/arm64,linux/amd64 --tag docker.my.org/example/multiarch-example:1.0.0