Multi-arch et manifests : une image pour amd64 et arm64

Ce guide vous apprend à construire une seule image qui fonctionne sur plusieurs architectures (amd64, arm64, arm/v7). Avec le même podman pull, l’image appropriée est téléchargée automatiquement.

À la fin, vous saurez :

• Créer un manifest list (index multi-arch)
• Construire avec émulation (simple mais lent)
• Construire avec podman farm (natif et rapide)
• Pousser vers un registry avec un seul tag

Scénario fil rouge

Nous construisons une API Go qui doit tourner sur des serveurs amd64 en production et des Raspberry Pi arm64 pour l’edge computing. Un seul tag myapp:1.0 pour les deux.

Droit au but

Concepts : manifest list Comprendre comment fonctionne le multi-arch.

Build avec émulation Solution simple, sans machine distante.

Build avec farm Solution native, builds distribués.

Workflow manifest create, add, inspect, push.

Le besoin : une image pour plusieurs architectures

Le problème

Vous avez une image qui fonctionne sur votre machine de développement (probablement amd64). Mais :

• Vos serveurs ARM en production ne peuvent pas l’exécuter
• Vos Raspberry Pi ne peuvent pas l’exécuter
• Vos Mac M1/M2 (arm64) ne peuvent pas l’exécuter nativement

Erreur typique :

podman run myapp:1.0
# exec format error

La solution : manifest list

Un manifest list (ou “fat manifest”) est un index qui pointe vers plusieurs images, une par architecture :

Quand vous exécutez podman pull myapp:1.0, Podman :

1. Télécharge le manifest list
2. Identifie l’architecture de votre machine
3. Télécharge l’image correspondante

Résultat : le même tag fonctionne partout.

Qu’est-ce qu’un manifest list ?

Structure

Un manifest list est un fichier JSON stocké dans le registry :

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:abc123...",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:def456...",
      "platform": {
        "architecture": "arm64",
        "os": "linux"
      }
    }
  ]
}

Architectures courantes

Les architectures les plus fréquentes sont amd64 (serveurs, cloud) et arm64 (Raspberry Pi, Mac M1/M2, AWS Graviton). Les autres sont rares mais utiles pour des cas spécifiques (mainframes IBM, vieux matériel).

Architecture	Machines	Exemples
linux/amd64	x86_64, Intel/AMD	Serveurs, cloud, laptops Linux/Windows
linux/arm64	ARM 64-bit	Raspberry Pi 4+, Mac M1/M2, AWS Graviton
linux/arm/v7	ARM 32-bit	Raspberry Pi 2/3 (mode 32-bit)
linux/arm/v6	ARM vieux	Raspberry Pi Zero
linux/386	x86 32-bit	Vieux serveurs
linux/s390x	IBM Z	Mainframes
linux/ppc64le	IBM Power	Power servers

Glissez pour voir

Vérifier l’architecture d’une image

# Voir les architectures disponibles
podman manifest inspect docker.io/library/nginx:alpine

# OU avec skopeo (plus lisible)
skopeo inspect --raw docker://docker.io/library/nginx:alpine | jq

Stratégie 1 : émulation (QEMU)

L’émulation permet de construire une image arm64 sur une machine amd64 (et vice versa). C’est la solution la plus simple, mais la plus lente.

Comment ça fonctionne

Configuration

Fedora / RHEL

# Installer qemu-user-static
sudo dnf install qemu-user-static

# Vérifier
ls /usr/bin/qemu-*-static

Ubuntu / Debian

# Installer qemu-user-static et binfmt-support
sudo apt install qemu-user-static binfmt-support

# Enregistrer les handlers
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

macOS (Podman Machine)

# L'émulation est déjà incluse dans Podman Machine
podman machine init
podman machine start

# Vérifier
podman info | grep -A 5 host

Construire avec —platform

# Build pour arm64 (émulé sur machine amd64)
podman build --platform linux/arm64 -t myapp:arm64 .

# Build pour amd64 (natif sur machine amd64)
podman build --platform linux/amd64 -t myapp:amd64 .

Performances

L’émulation a un coût : QEMU traduit chaque instruction CPU en temps réel. Pour un npm install ou une compilation Go, le ralentissement est significatif. Privilégiez l’émulation pour les tests rapides et podman farm pour les builds de production.

Architecture cible	Sur machine amd64	Temps relatif
linux/amd64	Natif	1×
linux/arm64	Émulé	5-10×
linux/arm/v7	Émulé	5-10×

Glissez pour voir

Lenteur de l'émulation

L’émulation est 5 à 10× plus lente que le build natif. Pour les gros projets (compilation Go, npm install), ça peut prendre plusieurs minutes.

Stratégie 2 : podman farm (builds natifs)

podman farm distribue les builds sur des machines distantes de chaque architecture. Les builds sont natifs, donc rapides.

Architecture

Prérequis

Pour chaque machine distante :

1. Podman installé
2. SSH accessible depuis la machine locale
3. Podman socket activé :

# Sur chaque machine distante
systemctl --user enable --now podman.socket

Configurer la farm

1. Ajouter les connexions Podman

   # Machine amd64
   podman system connection add amd64 ssh://user@amd64-server.local/run/user/1000/podman/podman.sock
   
   # Machine arm64
   podman system connection add arm64 ssh://user@arm64-server.local/run/user/1000/podman/podman.sock
   
   # Vérifier
   podman system connection list

2. Créer la farm

   podman farm create my-farm amd64 arm64
   
   # Vérifier
   podman farm list

3. Tester

   podman farm list

   Résultat

   Name       Connections
   my-farm    amd64, arm64

Construire avec la farm

podman farm build \
  --farm my-farm \
  --platforms linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:1.0 \
  .

Ce qui se passe :

1. Le Containerfile est envoyé aux machines distantes
2. Chaque machine build pour son architecture (natif)
3. Les images sont poussées vers le registry
4. Un manifest list est créé avec les deux images

Options de podman farm build

Les options principales contrôlent la farm utilisée, les architectures cibles, et si le build doit aussi s’exécuter localement.

Option	Description	Exemple
--farm	Nom de la farm	--farm my-farm
--platforms	Architectures cibles	linux/amd64,linux/arm64
-t, --tag	Tag de l’image	-t registry/app:1.0
--local	Build aussi sur la machine locale	--local

Glissez pour voir

CI/CD avec farm

En CI/CD, utilisez des runners de différentes architectures et podman farm pour automatiser les builds multi-arch.

Workflow complet : manifest list

Si vous avez déjà des images construites (par émulation ou farm), vous pouvez créer manuellement un manifest list.

Commande manifest

Les sous-commandes suivent un workflow séquentiel : créer d’abord le manifest vide, puis ajouter les images une par une, puis pousser le tout vers un registry.

Sous-commande	Action
manifest create	Créer un nouveau manifest list
manifest add	Ajouter une image au manifest
manifest inspect	Voir le contenu du manifest
manifest push	Pousser le manifest vers un registry
manifest rm	Supprimer un manifest local

Glissez pour voir

Workflow manuel

1. Construire les images pour chaque architecture

   # Sur machine amd64
   podman build --platform linux/amd64 -t myapp:amd64 .
   
   # Sur machine arm64 (ou émulé)
   podman build --platform linux/arm64 -t myapp:arm64 .

2. Créer le manifest list

   podman manifest create myapp:1.0

3. Ajouter les images

   # Pour des images locales, préfixer avec containers-storage:
   podman manifest add myapp:1.0 containers-storage:localhost/myapp:amd64
   podman manifest add myapp:1.0 containers-storage:localhost/myapp:arm64

4. Vérifier

   podman manifest inspect myapp:1.0

   Résultat (simplifié)

   {
     "manifests": [
       {
         "platform": {"architecture": "amd64", "os": "linux"},
         "digest": "sha256:abc123..."
       },
       {
         "platform": {"architecture": "arm64", "os": "linux"},
         "digest": "sha256:def456..."
       }
     ]
   }

5. Pousser vers le registry

   podman manifest push myapp:1.0 registry.example.com/myapp:1.0

Vérifier le résultat

Après le push, vérifiez que le manifest list est bien multi-arch :

# Inspecter depuis le registry
podman manifest inspect registry.example.com/myapp:1.0

# Ou avec skopeo
skopeo inspect --raw docker://registry.example.com/myapp:1.0 | jq '.manifests[].platform'

Résultat

{"architecture": "amd64", "os": "linux"}
{"architecture": "arm64", "os": "linux"}

Tester sur différentes architectures

# Sur machine amd64
podman pull registry.example.com/myapp:1.0
podman inspect myapp:1.0 --format '{{.Architecture}}'
# amd64

# Sur machine arm64
podman pull registry.example.com/myapp:1.0
podman inspect myapp:1.0 --format '{{.Architecture}}'
# arm64

Lab : construire une image multi-arch

Objectif : construire une API Go pour amd64 et arm64.

Code de l’application

main.go

package main

import (
    "fmt"
    "net/http"
    "runtime"
)

func main() {
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "Hello from %s/%s\n", runtime.GOOS, runtime.GOARCH)
    })
    http.ListenAndServe(":8080", nil)
}

Containerfile

# Build stage
FROM docker.io/library/golang:1.22-alpine AS builder

WORKDIR /app
COPY main.go .

# Build statique pour l'architecture cible
RUN CGO_ENABLED=0 go build -o /app/server main.go

# Runtime stage
FROM scratch
COPY --from=builder /app/server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Option A : avec émulation

1. Construire les deux architectures

   podman build --platform linux/amd64 -t myapi:amd64 .
   podman build --platform linux/arm64 -t myapi:arm64 .

2. Créer le manifest

   podman manifest create myapi:1.0
   podman manifest add myapi:1.0 containers-storage:localhost/myapi:amd64
   podman manifest add myapi:1.0 containers-storage:localhost/myapi:arm64

3. Vérifier

   podman manifest inspect myapi:1.0

4. Pousser

   podman manifest push myapi:1.0 registry.example.com/myapi:1.0

Option B : avec farm

# Prérequis : farm configurée avec connexions amd64 et arm64

podman farm build \
  --farm my-farm \
  --platforms linux/amd64,linux/arm64 \
  -t registry.example.com/myapi:1.0 \
  .

Vérification finale

# Inspecter le manifest list
podman manifest inspect registry.example.com/myapi:1.0

# Tester sur votre machine
podman run --rm registry.example.com/myapi:1.0
# Hello from linux/<votre-arch>

# Forcer une architecture différente (émulé)
podman run --rm --platform linux/arm64 registry.example.com/myapi:1.0
# Hello from linux/arm64

Dépannage

Erreurs courantes

La plupart des erreurs viennent de trois sources : l’absence de QEMU pour l’émulation, une image manquante dans le manifest, ou un registry qui ne supporte pas les manifest lists OCI.

Erreur	Cause	Solution
exec format error	Architecture incompatible	Vérifier --platform ou installer qemu
no suitable image	Manifest sans cette arch	Ajouter l’image pour cette arch
failed to push manifest	Registry ne supporte pas OCI index	Utiliser Docker Hub, GitHub, etc.
Farm build timeout	Machine distante inaccessible	Vérifier SSH et podman socket

Glissez pour voir

Commandes de diagnostic

# Architecture de la machine locale
podman info --format '{{.Host.Arch}}'

# Vérifier l'émulation disponible
ls /proc/sys/fs/binfmt_misc/

# Voir les architectures d'un manifest
podman manifest inspect myapp:1.0 | jq '.manifests[].platform'

# Vérifier les connexions de la farm
podman system connection list
podman farm list

L’émulation ne fonctionne pas

# Vérifier que qemu-user-static est installé
ls /usr/bin/qemu-*-static

# Réenregistrer les handlers (Linux)
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Test rapide
podman run --rm --platform linux/arm64 alpine:3.21 uname -m
# aarch64

Bonnes pratiques

Quand utiliser émulation vs farm

Le choix dépend de votre contexte : l’émulation est gratuite mais lente, farm est rapide mais nécessite des machines de chaque architecture. Pour la plupart des projets open source, l’émulation suffit.

Situation	Recommandation
Dev local, tests rapides	Émulation
CI/CD rapide	Farm
Projet open source	Émulation (pas de machines dédiées)
Production à grande échelle	Farm

Glissez pour voir

Optimisations pour le multi-arch

1. Containerfile compatible : éviter les dépendances architecture-spécifiques

   # ✅ Bon : dépendances universelles
   FROM alpine:3.21
   RUN apk add --no-cache ca-certificates
   
   # ❌ Mauvais : binaire compilé pour une seule arch
   COPY mybinary /app/mybinary

2. Multi-stage avec cross-compilation (Go, Rust) :

   FROM golang:1.22 AS builder
   ARG TARGETARCH   # Variable automatique : arm64 ou amd64
   RUN GOARCH=${TARGETARCH} go build -o /app

3. Tester sur toutes les architectures avant de pousser

Tags et versioning

# Manifest list avec tag sémantique
podman manifest push myapi:1.0 registry/myapi:1.0.0
podman manifest push myapi:1.0 registry/myapi:1.0
podman manifest push myapi:1.0 registry/myapi:1
podman manifest push myapi:1.0 registry/myapi:latest

À retenir

1. Manifest list = index pointant vers plusieurs images (une par arch)
2. Émulation (QEMU) : simple, lente, pas de machine distante
3. Farm : builds natifs distribués, rapide, nécessite des machines
4. Workflow : manifest create → add → inspect → push
5. Vérification : manifest inspect pour voir les architectures
6. Test : --platform pour forcer une architecture (émulée)

Prochaines étapes

Construire des images Optimisez vos Containerfiles pour le multi-arch.

Skopeo Copiez et inspectez vos images multi-arch entre registries.

Quadlet (systemd) Déployez vos conteneurs comme services systemd.

Supply chain sécurisée SBOM, signatures, et attestations pour vos images.

×

📖 Voir la documentation →