Comprendre OCI : tag, digest, manifest, multi-arch et artefacts

Vous avez remarqué que docker pull nginx:1.25 ne télécharge pas toujours les mêmes layers ? Deux causes principales :

1. Plateforme différente (AMD64 vs ARM64) → layers différentes (images multi-arch)
2. Tag mutable → l'image a été rebuild/republishée

Pour comprendre ces comportements, il faut connaître le standard OCI (Open Container Initiative). Ce guide vous explique les concepts clés : tags, digests, manifests, multi-arch et artefacts.

Ce que vous allez apprendre

• OCI : le standard ouvert qui définit le format des images et registries
• Tag vs Digest : pourquoi un tag peut changer, pas un digest
• Manifest : le fichier JSON qui décrit une image
• Multi-arch : comment une seule référence sert plusieurs architectures
• Artefacts OCI : stocker des Helm charts, SBOM, signatures dans un registry

Qu'est-ce que l'OCI ?

L'Open Container Initiative (OCI) est une organisation qui définit les standards ouverts pour les conteneurs :

Spécification	Ce qu'elle définit
OCI Image	Format des images (layers, config, manifest)
OCI Runtime	Comment exécuter un conteneur (runc)
OCI Distribution	API des registries (push, pull, list)

Glissez pour voir

OCI 1.1, début 2024

La version 1.1 des specs OCI Image et Distribution (annonce mars 2024) introduit le champ subject et la Referrers API pour associer signatures, SBOM et attestations aux images. Le support varie selon les registries et clients, voir la section "Artefacts OCI" pour les détails.

Pourquoi c'est important ? Grâce à l'OCI, une image buildée avec Docker fonctionne avec Podman, containerd, CRI-O. Un registry comme Harbor, Quay ou GHCR parle le même langage que Docker Hub.

Anatomie d'une image OCI

Une image OCI est composée de 3 types d'objets, tous identifiés par leur digest (hash SHA256). C'est un système content-addressable : le contenu détermine l'identifiant, pas l'inverse.

Dans le schéma, suivez les flèches depuis le tag : il pointe vers le manifest, qui référence à son tour la config et chaque layer par leur digest.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Objet	Contenu	Identifiant
Manifest	Référence vers config + layers	sha256:xxx...
Config	Métadonnées (env, cmd, user, ports)	sha256:yyy...
Layers	Fichiers de chaque couche (tar.gz)	sha256:zzz...

Glissez pour voir

Le digest d'une image = le hash SHA256 de son manifest. Si le manifest change (même légèrement), le digest change.

Tag → index ou manifest ?

Un tag peut pointer vers :

• un manifest (image mono-architecture)
• un index (manifest list, pour multi-arch)

Un digest (@sha256:...) identifie précisément l'objet : soit l'index complet, soit un manifest d'une architecture spécifique. En multi-arch, pinnez le digest de l'index pour garder le choix d'architecture, ou le digest du manifest spécifique pour figer une architecture.

Content-addressable vs location-addressable

Contrairement aux URLs classiques (location-addressable), OCI utilise un adressage par contenu :

Approche	Exemple	Caractéristique
Location-addressable	https://example.com/image.tar	Même URL, contenu peut changer
Content-addressable	sha256:abc123...	Même hash = même contenu garanti

Glissez pour voir

Avantages du content-addressable :

• Déduplication : layers identiques partagés entre images
• Vérification : intégrité vérifiable par recalcul du hash
• Immutabilité : un digest référence toujours le même contenu

Tag vs Digest : la différence fondamentale

Le tag : un alias mutable

Un tag est un nom lisible qui pointe vers un manifest. Le même tag peut pointer vers des manifests différents au fil du temps.

# Aujourd'hui
nginx:1.25 → sha256:abc123...

# Demain (après un rebuild)
nginx:1.25 → sha256:def456...  # Différent !

C'est comme un signet : il pointe vers une page, mais vous pouvez le déplacer.

Le digest : une empreinte immutable

Un digest est le hash SHA256 du manifest. Il identifie une version exacte de l'image, de manière permanente.

# Toujours la même image, pour toujours
nginx@sha256:6926dd802f40e5e7257fded83e0d8030039642e4e10c4a98a6478e9c6fe06153

C'est comme une empreinte digitale : elle ne change jamais pour une personne donnée.

Quand utiliser quoi ?

Contexte	Utiliser	Exemple
Développement local	Tag	nginx:1.25
CI/CD (publication)	Tag versionné + capturer digest	mon-app:1.2.3 → sha256:abc...
Production (deploy)	Digest	mon-app@sha256:abc...
Audit / compliance	Digest	Traçabilité exacte
Dockerfile FROM	Tag ou digest selon criticité	FROM alpine:3.19 ou FROM alpine@sha256:...

Glissez pour voir

Règle d'or : en production, pinnez par digest, pas par tag. Un tag versionné comme v1.2.3 n'est pas pour autant immuable : il peut être republié, sauf si le registry l'interdit par une politique.

Obtenir le digest d'un tag

# Avec crane (recommandé : interroge directement le registry)
crane digest nginx:1.25

# Avec skopeo
skopeo inspect docker://nginx:1.25 | jq -r '.Digest'

# Avec Docker (attention : .RepoDigests peut être vide ou multiple)
docker inspect --format='{{index .RepoDigests 0}}' nginx:1.25

Note : docker inspect affiche le digest de l'image locale. Pour interroger le registry sans puller, utilisez crane ou skopeo.

Promotion par digest en CI/CD

Le workflow recommandé pour garantir la traçabilité :

# 1. Build et push avec un tag
docker buildx build --tag ghcr.io/mon-org/mon-app:v1.2.3 --push .

# 2. Capturer le digest depuis le registry
DIGEST=$(crane digest ghcr.io/mon-org/mon-app:v1.2.3)
echo "Built: ghcr.io/mon-org/mon-app@${DIGEST}" >> release-metadata.txt

# 3. Déployer par digest (immuable)
kubectl set image deployment/mon-app \
  app=ghcr.io/mon-org/mon-app@${DIGEST}

Ce pattern sépare publication (tag pour les humains) et déploiement (digest pour la reproductibilité).

Le manifest : le cœur de l'image

Le manifest est un fichier JSON qui décrit une image. Il contient :

• Le digest de la config (métadonnées)
• La liste des layers avec leurs digests et tailles
• Le media type (format)

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.oci.image.config.v1+json",
    "digest": "sha256:aaa...",
    "size": 1234
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:bbb...",
      "size": 5678
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:ccc...",
      "size": 9012
    }
  ]
}

Media types : Docker vs OCI

Les registries supportent deux formats de manifests. En pratique, la plupart des outils gèrent les deux de manière transparente.

Format	Media type manifest	Usage
Docker v2	application/vnd.docker.distribution.manifest.v2+json	Legacy, Docker Hub historique
OCI	application/vnd.oci.image.manifest.v1+json	Standard actuel, recommandé

Glissez pour voir

Vérifier le format d'une image

# Voir le media type du manifest
crane manifest nginx:1.25 | jq -r '.mediaType'
# application/vnd.oci.image.index.v1+json (multi-arch OCI)

skopeo inspect --raw docker://nginx:1.25 | jq -r '.mediaType'

Voir le manifest d'une image :

# Avec crane
crane manifest nginx:1.25 | jq .

# Avec skopeo
skopeo inspect --raw docker://nginx:1.25 | jq .

Multi-arch : une référence, plusieurs architectures

Comment docker pull nginx télécharge-t-il la bonne version pour votre CPU (AMD64 ou ARM64) ? Grâce au manifest list (ou OCI image index).

Le principe

Un manifest list est un manifest spécial qui contient des références vers plusieurs manifests, un par architecture.

Le schéma suit un docker pull : le client lit la manifest list, retient le manifest de sa plateforme (les autres restent en pointillés), puis télécharge les layers correspondants.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Quand vous faites docker pull nginx:1.25 :

1. Docker télécharge le manifest list
2. Il identifie votre architecture (ex: linux/amd64)
3. Il télécharge le manifest spécifique à votre architecture
4. Il télécharge les layers correspondants

Construire des images multi-arch avec Buildx

# Créer un builder multi-plateforme
docker buildx create --name multi-arch --driver docker-container --use

# Builder et pusher pour AMD64 + ARM64
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag mon-registry/mon-app:v1.0 \
  --push .

# Vérifier les architectures disponibles
docker manifest inspect mon-registry/mon-app:v1.0

Performance sur Apple Silicon

Builder pour linux/amd64 sur un Mac ARM64 utilise l'émulation QEMU, ce qui est 5 à 10x plus lent. Pour la CI, préférez des runners natifs par architecture ou le build croisé avec des images de base multi-arch.

Voir les architectures disponibles

# Avec docker manifest
docker manifest inspect nginx:1.25

# Avec crane
crane manifest nginx:1.25 | jq '.manifests[] | {platform, digest}'

# Résultat
{
  "platform": { "architecture": "amd64", "os": "linux" },
  "digest": "sha256:amd123..."
}
{
  "platform": { "architecture": "arm64", "os": "linux" },
  "digest": "sha256:arm123..."
}

Digest multi-arch vs mono-arch

Le digest d'un tag multi-arch (sha256:multi123...) est différent du digest de chaque architecture (sha256:amd123...). En CI/CD, faites attention à quel digest vous pinnez.

Artefacts OCI : au-delà des images

Les registries OCI peuvent stocker d'autres types d'artefacts que des images de conteneurs :

Artefact	Cas d'usage	Outil
Helm charts	Packages Kubernetes	helm push
SBOM	Liste des composants logiciels	ORAS, Syft
Signatures	Attestation d'origine	Cosign, Notation
Policies	Règles OPA/Rego	Conftest
WASM modules	WebAssembly	ORAS

Glissez pour voir

OCI 1.1 et la Referrers API

Depuis mars 2024, les specs OCI 1.1 permettent d'associer des artefacts à une image via le champ subject. Cela résout un problème majeur : comment savoir quels SBOM, signatures et attestations sont liés à une image ?

Dans le schéma, chaque artefact (signature, SBOM, attestation, rapport de vulnérabilités) pointe vers l'image par son champ subject, et la Referrers API les liste tous à partir du digest de l'image.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Fonctionnement :

1. L'artefact (signature, SBOM...) contient un champ subject avec le digest de l'image cible
2. Le registry indexe automatiquement cette relation
3. L'API GET /v2/<name>/referrers/<digest> retourne tous les artefacts liés

# Lister les artefacts liés à une image (avec ORAS)
oras discover ghcr.io/mon-org/mon-app:v1.0

# Résultat typique
ghcr.io/mon-org/mon-app@sha256:abc123
├── application/vnd.dev.cosign.simplesigning.v1+json (signature)
├── application/spdx+json (SBOM)
└── application/vnd.in-toto+json (attestation SLSA)

Support des registries (OCI 1.1 Referrers)

La Referrers API est implémentée de manière variable selon les registries et versions :

• Docker Hub : support artefacts OCI (doc)
• Harbor : support Distribution spec 1.1 depuis la version 2.9 (release notes)
• GHCR, ECR, ACR, Artifact Registry : support progressif

Certains clients (cosign, oras) ont des niveaux de support variables selon les commandes. Testez sur votre stack avant de vous appuyer sur la Referrers API en production.

ORAS : OCI Registry As Storage

ORAS (OCI Registry As Storage) est un outil et une spécification pour pousser/puller n'importe quel fichier vers un registry OCI.

# Pousser un fichier quelconque
oras push ghcr.io/mon-org/configs:v1 config.yaml:application/yaml

# Puller le fichier
oras pull ghcr.io/mon-org/configs:v1

# Pousser un SBOM généré par Syft, lié à une image (OCI 1.1)
syft nginx:1.25 -o spdx-json > sbom.json
oras push ghcr.io/mon-org/sboms:nginx-1.25 \
  --artifact-type application/spdx+json \
  --subject ghcr.io/mon-org/nginx@sha256:abc... \
  sbom.json:application/spdx+json

Compatibilité --subject

L'option --subject nécessite :

• ORAS v1.1+ (support OCI 1.1)
• Un registry compatible Referrers API

Sans support côté registry, l'artefact sera pushé mais la relation ne sera pas indexée. Testez avec oras discover pour vérifier.

Pourquoi c'est utile ?

• Un seul système pour stocker images, configs, SBOM, signatures
• Même authentification que pour les images
• Même réplication entre registries
• Associer un SBOM ou une signature à une image via son digest

Outils CLI pour manipuler des images OCI

Outil	Forces	Installation
crane	Léger, rapide, API Go réutilisable	go install github.com/google/go-containerregistry/cmd/crane@latest
skopeo	Copie entre registries, air-gap	Package système (apt, dnf)
regctl	Nettoyage de tags, garbage collection	go install github.com/regclient/regclient/cmd/regctl@latest
oras	Artefacts génériques, Referrers API	go install oras.land/oras/cmd/oras@latest

Glissez pour voir

# Copier une image entre registries (sans Docker daemon)
skopeo copy docker://nginx:1.25 docker://mon-registry/nginx:1.25

# Supprimer un tag (attention : irréversible)
crane delete mon-registry/mon-app:old-tag

# Explorer les layers d'une image
crane export nginx:1.25 - | tar -tvf - | head -20

Chaque outil du tableau a son guide : ORAS pour manipuler des artefacts OCI, Skopeo pour inspecter et copier des images sans daemon, et Crane, la CLI de Google pour manipuler des images OCI. La stratégie de tags, le cache, le multi-arch et la promotion d'une image d'un environnement à l'autre sont traités dans CI/CD d'images. Maintenant que le format OCI est clair, la supply chain des images (SBOM, scan, signature) en tire les bases DevSecOps pour des images de confiance.

À retenir

1. OCI = standard ouvert pour images et registries (interopérabilité Docker/Podman/containerd)
2. Tag = alias mutable vers un manifest (peut changer) → développement
3. Digest = hash SHA256 immutable du manifest → production, audit
4. Content-addressable = l'identifiant est le hash du contenu → déduplication, vérification
5. Manifest = JSON qui liste config + layers avec leurs digests
6. Manifest list = index multi-arch qui pointe vers un manifest par architecture
7. OCI 1.1 (mars 2024) = Referrers API pour lier signatures, SBOM, attestations aux images
8. ORAS = stocker n'importe quel artefact (SBOM, signatures, configs) dans un registry OCI
9. Outils : crane (léger), skopeo (copie), regctl (nettoyage), oras (artefacts)

Testez vos connaissances

Vérifions que vous avez assimilé les concepts OCI essentiels : tags vs digests, manifests, multi-arch et artefacts.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

7 questions

5 min.

80% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →