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

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 us to put multiple container images, each supporting a different architecture, behind the same tag.

We can do that with a manifest that contains a list of manifest, 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"
      }
    }
  ]
}

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