Fonctionnement d’un registre de conteneurs : pousser/tirer directement des images

• Le registre de conteneurs semble simple en apparence, mais pour déboguer des problèmes comme des tags erronés, des incompatibilités de plateforme, des couches manquantes ou des suppressions qui échouent réellement, il est indispensable d’en comprendre le fonctionnement interne
• Le cœur du registre est un stockage de blobs adressé par le contenu (content-addressable), où toutes les couches, les fichiers de configuration et les artefacts sont stockés en utilisant leur digest comme adresse
• Le push d’une image suit l’ordre téléversement des blobs puis assemblage via un manifest, tandis que le pull fonctionne dans l’ordre inverse : on récupère d’abord le manifest, puis on télécharge les blobs séquentiellement
• La suppression d’image ne se résume pas à retirer un tag : cela ne suffit pas à l’éliminer complètement, et il faut d’abord vérifier les couches partagées par d’autres manifests avant de supprimer directement les blobs
• Les images multiplateformes sont implémentées en conservant les endpoints API existants tels quels, en n’ajoutant qu’un niveau d’indirection supplémentaire appelé image index (manifest list)

---

Vue d’ensemble de l’API Registry

• La plupart des registres de conteneurs modernes implémentent l’OCI Distribution Specification, qui définit un protocole API standardisant la distribution de contenu
• L’API Registry est en pratique concise et facile à comprendre, et peut être manipulée directement avec curl

Téléversement et téléchargement de blobs

• Un registre est fondamentalement un stockage de blobs adressé par le contenu, où l’on hache un fichier en local avant de l’envoyer en utilisant son digest comme adresse
• La méthode de téléversement la plus simple est le Monolithic PUT, une structure en deux étapes où l’on initialise une session avec POST, puis où l’on envoie le blob avec PUT
  • Pour les gros fichiers, l’upload par chunks en POST + PATCH + PUT est plus efficace, mais pour de petits blobs, le Monolithic PUT suffit
• En cas de succès, le registre renvoie une réponse HTTP/2 201 Created avec un en-tête Location pointant vers l’emplacement du nouveau blob
• Pour le téléchargement, dès lors que l’on connaît le digest, un simple GET /v2/<repo>/blobs/<digest> suffit

Push d’image

• Procédure de push d’image : (1) téléverser chaque blob de couche rootfs → (2) téléverser le blob de configuration d’image → (3) pousser le fichier manifest, qui regroupe tous les digests dans un document JSON unique
• Le manifest est téléversé via l’endpoint PUT /v2/<repo>/manifests/<tag>, et c’est à ce moment-là que le tag est créé
• Les clients réels (par ex. docker push) téléversent les blobs en parallèle, mais un traitement séquentiel suffit pour comprendre le principe
• Exemple de structure d’un répertoire d’image : config.json, layer-1.tar.gz, layer-2.tar.gz, manifest.json

Consultation de la liste des tags

• L’endpoint GET /v2/<repo>/tags/list permet de récupérer la liste complète des tags d’un dépôt donné
• Cette fonctionnalité n’est pas exposée dans la CLI docker et n’est accessible qu’avec curl ou des outils comme crane et regctl
  • crane et regctl ne font qu’encapsuler le même endpoint via la commande ls

Pull d’image

• La procédure de pull est l’inverse du push : (1) récupérer le manifest avec GET /v2/<repo>/manifests/<tag> → (2) télécharger tous les blobs à partir des digests indiqués dans le manifest
• Les manifests modernes servent aussi de stockage générique référençant des blobs arbitraires au-delà des couches rootfs et de la configuration d’image, comme des charts Helm, SBOM, attestations de provenance, poids de LLM, etc.

Suppression d’image

• La suppression d’une image n’est pas triviale : retirer un tag (untag) ne supprime pas le manifest lui-même
• Procédure de suppression complète :
  • (1) retirer le tag avec DELETE /v2/<repo>/manifests/<tag>
  • (2) récupérer le manifest via son digest pour identifier tous les blobs qu’il référence
  • (3) supprimer de façon sélective uniquement les blobs qui ne sont pas partagés par d’autres manifests
  • (4) supprimer le blob du manifest avec DELETE /v2/<repo>/blobs/<manifest-digest>
• Comme le registre repose sur un stockage adressé par le contenu, plusieurs images peuvent partager la même couche rootfs ; lors d’une suppression, cela peut donc affecter toutes les images qui référencent cette couche
• En alternative, on peut retirer tous les tags puis s’en remettre au garbage collection du registre, mais sur les registres publics, cette fonctionnalité n’est pas toujours activée

Images multiplateformes

• Les images multiplateformes sont implémentées sans modification de la structure de l’API Registry : aucun endpoint n’est ajouté ni modifié, l’API existante est réutilisée telle quelle
• Méthode de composition :
  • pousser d’abord chaque variante mono-plateforme (amd64, arm64, etc.) avec son propre manifest sur la base d’un digest
  • pousser ensuite un manifest de niveau supérieur appelé image index (manifest list) avec le tag
• Lors d’un appel à GET /v2/<repo>/manifests/<tag>, le registre renvoie soit un manifest mono-plateforme, soit un image index, et l’appelant doit les distinguer via le content type du document reçu
• En pratique, la prise en charge du multiplateforme n’ajoute à la structure existante qu’un seul niveau d’indirection et une seule étape d’upload/download d’un document index

Protection de l’API Registry

• L’OCI Distribution Spec ne définit pas strictement le mode d’authentification, mais la plupart des registres réels utilisent l’authentification HTTP Basic
• Pour éviter la transmission des identifiants en clair, le service doit impérativement fonctionner sur HTTPS