Gérer vos images conteneurs avec Crane

Crane vous permet de copier, inspecter et optimiser vos images de conteneurs sans avoir besoin du démon Docker. Développé par Google dans le cadre du projet go-containerregistry, cet outil en ligne de commande communique directement avec les registries via l’API OCI. Vous pouvez l’utiliser pour copier une image entre Docker Hub et votre registry privée en une seule commande, inspecter les layers d’une image, ou aplatir une image multi-layers pour réduire sa taille. Particulièrement utile en CI/CD où Docker n’est pas toujours disponible, Crane s’installe en quelques secondes et fonctionne sur Linux, macOS et Windows.

Ce que vous allez apprendre

• Installer Crane sur Linux ou macOS avec asdf ou Homebrew
• Inspecter les images d’une registry (manifest, config, layers)
• Copier des images entre registries sans Docker
• Optimiser les images en aplatissant les layers
• Automatiser la gestion des tags et versions en CI/CD

Pourquoi Crane plutôt que Docker ?

Crane est un outil développé par Google qui permet de manipuler les images de conteneurs sans avoir besoin du démon Docker. C’est particulièrement utile dans les environnements CI/CD où Docker n’est pas toujours disponible, ou quand vous voulez simplement inspecter ou copier des images rapidement.

Cas d’usage typiques :

Besoin	Avec Docker	Avec Crane
Copier une image entre registries	docker pull + docker tag + docker push	crane copy source dest
Voir les layers d’une image	docker history (limité)	crane manifest (détaillé)
Obtenir le digest SHA256	docker inspect	crane digest
Exporter une image en tar	docker save	crane export
Aplatir les layers	Impossible nativement	crane flatten

Glissez pour voir

Sans démon Docker

Crane communique directement avec les registries via l’API OCI. Vous pouvez l’utiliser sur un serveur sans Docker installé, dans un conteneur sans privilèges, ou dans une GitHub Action avec le simple binaire.

Installation de Crane

Plusieurs méthodes d’installation sont disponibles selon votre système d’exploitation et vos préférences. Choisissez celle qui correspond le mieux à votre environnement de travail.

Linux (asdf)

asdf-vm est un gestionnaire de versions polyvalent. C’est ma méthode recommandée car elle permet de fixer une version précise par projet grâce au fichier .tool-versions.

asdf plugin add crane
asdf install crane 0.20.7
asdf set --home crane 0.20.7

L’avantage d’asdf est de pouvoir utiliser différentes versions de Crane selon les projets, ce qui est utile quand vous travaillez sur des codebases avec des contraintes de compatibilité différentes.

macOS (Homebrew)

Si vous utilisez Homebrew, l’installation se fait en une seule commande. Homebrew gère automatiquement les mises à jour quand vous exécutez brew upgrade.

brew install crane

Arch Linux

Sur Arch Linux, Crane est disponible dans les dépôts officiels. L’installation via pacman garantit l’intégration avec le système de paquets et les mises à jour automatiques.

pacman -S crane

Binaire (releases)

Cette méthode fonctionne sur tous les systèmes Linux et permet de choisir une version précise. Les binaires sont disponibles pour plusieurs architectures : x86_64, arm64, armv6, i386, s390x et riscv64.

# Récupérer la dernière version automatiquement
VERSION=$(curl -s "https://api.github.com/repos/google/go-containerregistry/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)

# Ou fixer une version spécifique
VERSION=v0.20.7

# Télécharger et extraire (adapter ARCH si nécessaire : arm64, armv6...)
curl -sL "https://github.com/google/go-containerregistry/releases/download/${VERSION}/go-containerregistry_Linux_x86_64.tar.gz" -o crane.tar.gz
tar -xzf crane.tar.gz crane
sudo mv crane /usr/local/bin/
rm crane.tar.gz

Go install

Si vous avez Go installé (version 1.21+), vous pouvez compiler Crane depuis les sources. Cette méthode installe toujours la dernière version du code.

go install github.com/google/go-containerregistry/cmd/crane@latest

Le binaire sera installé dans $GOPATH/bin (généralement ~/go/bin). Assurez-vous que ce répertoire est dans votre PATH.

Image Docker

Vous pouvez utiliser Crane directement via son image Docker officielle, ce qui est pratique pour les pipelines CI/CD ou pour tester sans installation locale.

# Utilisation basique
docker run --rm gcr.io/go-containerregistry/crane ls ubuntu

# Version avec shell (pour debug)
docker run --rm -it --entrypoint "/busybox/sh" gcr.io/go-containerregistry/crane:debug

L’image :debug inclut un shell BusyBox, utile pour le débogage. Les images taggées sont disponibles sur gcr.io/go-containerregistry/crane:[version].

Vérification de l’installation :

crane version
# Résultat attendu : 0.20.7

Mise en place d’un lab de test

Pour les exemples qui suivent, je vais utiliser une registry locale. Cela permet de tester sans risque et sans créer de compte sur Docker Hub.

1. Démarrer une registry locale

   docker run -d -p 5000:5000 --name registry registry:2.8

   La registry sera accessible sur localhost:5000.

2. Créer un Dockerfile de test

   FROM alpine:3.21
   RUN apk --no-cache add nginx
   RUN mkdir -p /var/www/html
   COPY index.html /var/www/html/
   WORKDIR /var/www/html
   EXPOSE 80

3. Créer le fichier index.html

   <!DOCTYPE html>
   <html>
   <body><h1>Test Crane</h1></body>
   </html>

4. Construire et pousser l’image

   docker build . -t localhost:5000/monserveurweb:0.1
   docker push localhost:5000/monserveurweb:0.1

Gestionnaire de paquets Alpine

Si vous ne maîtrisez pas apk, consultez mon guide sur apk pour comprendre son fonctionnement.

Commandes essentielles de Crane

Crane propose une vingtaine de commandes pour interagir avec les registries. Dans cette section, nous allons voir les plus utilisées au quotidien. Toutes ces commandes communiquent directement avec la registry via HTTP/HTTPS, sans passer par le démon Docker.

Lister les images d’une registry

La commande catalog interroge l’API de la registry pour récupérer la liste de toutes les images (appelées “repositories” dans la terminologie OCI). C’est le point de départ pour explorer le contenu d’une registry.

crane catalog localhost:5000
# monserveurweb

Sur une registry publique comme Docker Hub, cette commande peut retourner des milliers de résultats. Utilisez-la plutôt sur vos registries privées.

Lister les tags d’une image

Une fois que vous connaissez le nom d’une image, ls affiche tous les tags disponibles. Un tag est un pointeur vers une version spécifique de l’image.

crane ls localhost:5000/monserveurweb
# 0.1

Cette commande est utile pour vérifier quelles versions sont disponibles avant de copier ou de déployer une image.

Inspecter le manifest d’une image

Le manifest contient les métadonnées de l’image : ses layers, leur taille, leur digest SHA256. C’est l’équivalent d’une “table des matières” de l’image.

crane manifest localhost:5000/monserveurweb:0.1 | jq

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "size": 1476,
    "digest": "sha256:28865db66a2e..."
  },
  "layers": [
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 2829647,
      "digest": "sha256:f7dab3ab2d6e..."
    },
    {
      "mediaType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
      "size": 617439,
      "digest": "sha256:607cfc754b09..."
    }
  ]
}

Utiliser jq pour formater

jq est indispensable pour lire les sorties JSON. Installez-le avec apt install jq ou brew install jq.

Obtenir la configuration complète

La commande config affiche la configuration complète de l’image : historique des layers, variables d’environnement, commande par défaut, labels…

crane config localhost:5000/monserveurweb:0.1 | jq

{
  "architecture": "amd64",
  "os": "linux",
  "config": {
    "Cmd": ["/bin/sh"],
    "Env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
    "WorkingDir": "/var/www/html",
    "ExposedPorts": { "80/tcp": {} }
  },
  "history": [
    { "created_by": "/bin/sh -c #(nop) ADD file:..." },
    { "created_by": "RUN /bin/sh -c apk --no-cache add nginx" },
    { "created_by": "COPY index.html /var/www/html/" }
  ]
}

Récupérer le digest SHA256

Le digest est l’identifiant unique et immuable d’une image. Contrairement au tag qui peut être modifié, le digest garantit que vous utilisez exactement la même image.

crane digest localhost:5000/monserveurweb:0.1
# sha256:beb9fd8064525aa1787d60cfd6eba89c4580125f1e32a42e0ab006912cf48038

Copier des images entre registries

C’est la fonctionnalité phare de Crane. En une seule commande, vous copiez une image d’une registry à une autre, y compris les images multi-architectures. Contrairement à la méthode traditionnelle (docker pull + docker tag + docker push), Crane ne télécharge pas l’image sur votre machine : il orchestre un transfert direct entre les deux registries.

crane copy alpine:3.21 localhost:5000/alpine:3.21 --platform linux/amd64
# 2026/01/23 09:13:02 Copying from alpine:3.21 to localhost:5000/alpine:3.21
# 2026/01/23 09:13:03 existing blob: sha256:39477eca89b9...
# 2026/01/23 09:13:03 existing blob: sha256:f637881d1138...
# 2026/01/23 09:13:03 localhost:5000/alpine:3.21: digest: sha256:41c81533... size: 1022

Cette commande copie l’image alpine:3.21 depuis Docker Hub vers votre registry locale. L’option --platform limite la copie à une architecture spécifique. Sans cette option, toutes les architectures sont copiées.

Ce que Crane fait en coulisses :

1. Récupère le manifest de l’image source (la “table des matières”)
2. Pour chaque layer, vérifie s’il existe déjà dans la destination
3. Copie uniquement les layers manquants (économie de bande passante)
4. Pousse le manifest final pour rendre l’image disponible

Vérification :

crane catalog localhost:5000
# alpine
# nginx

crane ls localhost:5000/alpine
# 3.21

Images multi-architectures

Quand vous copiez une image comme alpine:3.21, Crane copie toutes les architectures (amd64, arm64, etc.). C’est le comportement attendu pour maintenir la compatibilité.

Optimiser les images avec flatten

Une image Docker est composée de plusieurs layers (couches), chacune représentant une modification du système de fichiers. Par exemple, l’image nginx:1.27.3-alpine contient 8 layers : l’image de base Alpine, l’installation de nginx, les fichiers de configuration, etc.

La commande flatten fusionne tous ces layers en un seul. L’image résultante contient exactement les mêmes fichiers, mais dans une structure simplifiée.

# Copier nginx vers la registry locale
crane copy nginx:1.27.3-alpine localhost:5000/nginx:1.27.3-alpine --platform linux/amd64

# Aplatir l'image
crane flatten localhost:5000/nginx:1.27.3-alpine \
  -t localhost:5000/nginx:1.27.3-alpine-flat

L’option -t (ou --tag) spécifie le nom et le tag de l’image aplatie. Ici, nous créons une nouvelle image plutôt que de modifier l’originale.

Comparaison avant/après :

# Avant : 8 layers
crane manifest localhost:5000/nginx:1.27.3-alpine | jq '.layers | length'
# 8

# Après : 1 seul layer
crane manifest localhost:5000/nginx:1.27.3-alpine-flat | jq '.layers | length'
# 1

Vérification de la taille :

docker pull localhost:5000/nginx:1.27.3-alpine
docker pull localhost:5000/nginx:1.27.3-alpine-flat
docker images | grep nginx
# localhost:5000/nginx   1.27.3-alpine        20.5MB
# localhost:5000/nginx   1.27.3-alpine-flat   20.2MB

Quand utiliser flatten

flatten est utile pour :

• Réduire le nombre de layers avant déploiement en production
• Masquer l’historique de construction (sécurité)
• Simplifier le débogage

Ne pas utiliser si vous avez besoin du cache Docker entre builds.

Gérer les tags

Les tags sont des pointeurs vers des versions spécifiques d’une image. Un même digest (identifiant unique basé sur le contenu) peut avoir plusieurs tags. Par exemple, une image peut être taguée 1.0.0, 1.0 et latest simultanément.

Ajouter un tag à une image existante

La commande tag crée un nouveau pointeur vers une image existante. C’est une opération légère qui ne duplique pas les données : les deux tags pointent vers le même contenu.

crane tag localhost:5000/alpine:3.21 latest

Cette commande ajoute le tag latest à l’image qui porte déjà le tag 3.21. Les deux tags coexistent et pointent vers la même version.

Vérification :

crane ls localhost:5000/alpine
# 3.21
# latest

Valider une image

La commande validate vérifie que l’image est conforme aux spécifications OCI (Open Container Initiative). Elle contrôle que le manifest est bien formé et que tous les layers référencés existent.

crane validate --remote localhost:5000/monserveurweb:0.1
# PASS: localhost:5000/monserveurweb:0.1

Utilisez cette commande après une copie ou une modification pour vous assurer que l’image est utilisable.

S’authentifier à une registry

Les registries privées (Docker Hub pour les images privées, GCR, ECR, ACR, Harbor, GitLab Registry…) nécessitent une authentification avant de pouvoir lire ou écrire des images.

Crane stocke les credentials dans le même fichier que Docker (~/.docker/config.json), ce qui permet de réutiliser les authentifications existantes.

crane auth login registry.example.com -u username -p "password"
# logged in via /home/user/.docker/config.json

Sur les providers cloud, vous pouvez utiliser des tokens temporaires. Par exemple, pour GCR avec gcloud :

crane auth login gcr.io -u oauth2accesstoken -p "$(gcloud auth print-access-token)"

Ne jamais mettre le mot de passe en clair

En CI/CD, utilisez des variables d’environnement ou des secrets :

crane auth login registry.example.com -u "$REGISTRY_USER" -p "$REGISTRY_PASSWORD"

Commandes avancées

Ces commandes sont moins utilisées au quotidien mais peuvent s’avérer très utiles dans des cas spécifiques : audit de sécurité, débogage, migration d’images, ou automatisation avancée.

Modifier les labels d’une image

Les labels sont des métadonnées attachées à une image (version, mainteneur, licence, etc.). La commande mutate permet de les modifier sans reconstruire l’image, ce qui est utile pour ajouter des informations après coup.

crane mutate localhost:5000/alpine:3.21 \
  --label "maintainer=team@example.com" \
  --label "version=3.21" \
  -t localhost:5000/alpine:3.21-labeled

Vérification des labels ajoutés :

crane config localhost:5000/alpine:3.21-labeled | jq '.config.Labels'
# {
#   "maintainer": "team@example.com",
#   "version": "3.21"
# }

L’option -t (ou --tag) crée une nouvelle référence plutôt que de modifier l’originale.

Modifier la plateforme d’une image

Depuis la version 0.19.2, mutate permet de modifier la plateforme d’une image avec l’option --set-platform. C’est utile quand une image a été buildée avec une plateforme incorrecte ou manquante.

crane mutate localhost:5000/myapp:1.0 \
  --set-platform linux/amd64 \
  -t localhost:5000/myapp:1.0-amd64

Exporter une image en tar

La commande export télécharge tous les layers d’une image et les assemble dans une archive tar. C’est utile pour l’archivage, le transfert vers un environnement déconnecté (air-gapped), ou l’analyse du contenu.

crane export localhost:5000/monserveurweb:0.1 monserveurweb.tar

L’archive contient le système de fichiers complet de l’image. Vous pouvez l’explorer avec tar -tf monserveurweb.tar ou l’extraire pour inspection.

Récupérer un layer spécifique

Pour du débogage approfondi, vous pouvez extraire un layer particulier. Chaque layer correspond à une instruction du Dockerfile (RUN, COPY, ADD). Cela permet de voir exactement ce que chaque étape a ajouté ou modifié.

# Récupérer les digests des layers
crane manifest localhost:5000/monserveurweb:0.1 | jq '.layers[].digest'

# Extraire un layer spécifique (remplacer le digest)
crane blob localhost:5000/monserveurweb:0.1@sha256:607cfc754b09... > layer.tar.gz

# Explorer le contenu du layer
tar -tzf layer.tar.gz | head -20

Rebase sur une nouvelle image de base

rebase permet de reconstruire une image avec une nouvelle image de base, sans Dockerfile :

crane rebase localhost:5000/monserveurweb:0.1 \
  --old_base alpine:3.20 \
  --new_base alpine:3.21 \
  --tag localhost:5000/monserveurweb:rebased

Limitations de rebase

rebase fonctionne uniquement si les layers de l’ancienne base sont présents exactement dans l’image. Si l’image a été modifiée ou reconstruite, le rebase échouera.

Intégration CI/CD

Crane est particulièrement adapté aux pipelines CI/CD pour plusieurs raisons :

• Pas besoin de Docker : fonctionne sans démon, sans privilèges root
• Installation rapide : un seul binaire statique de ~15 Mo
• Efficace : copie directe entre registries, pas de stockage intermédiaire
• Scriptable : commandes simples, sorties prévisibles, codes retour standards

Les exemples ci-dessous montrent comment intégrer Crane dans vos workflows pour copier automatiquement les images validées vers un registry de production.

Exemple GitHub Actions

name: Copy image to production registry

on:
  push:
    tags:
      - 'v*'

jobs:
  copy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Crane
        run: |
          VERSION=0.20.7
          curl -sL "https://github.com/google/go-containerregistry/releases/download/v${VERSION}/go-containerregistry_Linux_x86_64.tar.gz" | tar xzf - crane
          sudo mv crane /usr/local/bin/

      - name: Login to registries
        run: |
          crane auth login ghcr.io -u ${{ github.actor }} -p ${{ secrets.GITHUB_TOKEN }}
          crane auth login registry.example.com -u ${{ secrets.PROD_USER }} -p ${{ secrets.PROD_PASSWORD }}

      - name: Copy image
        run: |
          crane copy ghcr.io/${{ github.repository }}:${{ github.ref_name }} \
            registry.example.com/myapp:${{ github.ref_name }}

Exemple GitLab CI

copy-to-prod:
  image: gcr.io/go-containerregistry/crane:v0.20.7
  script:
    - crane auth login $CI_REGISTRY -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD
    - crane auth login $PROD_REGISTRY -u $PROD_USER -p $PROD_PASSWORD
    - crane copy $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG $PROD_REGISTRY/myapp:$CI_COMMIT_TAG

Dépannage

Problèmes courants et solutions

Symptôme	Cause probable	Solution
unauthorized	Token expiré ou invalide	crane auth login à nouveau
manifest unknown	Tag inexistant	Vérifier avec crane ls
UNSUPPORTED sur delete	Registry ne supporte pas la suppression	Normal pour registry locale par défaut
connection refused	Registry non accessible	Vérifier l’URL et le réseau
certificate signed by unknown authority	Certificat auto-signé	Ajouter --insecure (dev uniquement)

Glissez pour voir

Commandes de diagnostic

# Vérifier la connectivité à une registry
crane auth login registry.example.com -u test -p test

# Lister les images disponibles
crane catalog registry.example.com

# Vérifier qu'un tag existe
crane digest registry.example.com/myimage:mytag

# Voir les détails d'une erreur
crane manifest registry.example.com/myimage:mytag 2>&1

Bonnes pratiques

Sécurité

• Ne jamais utiliser --insecure en production
• Stocker les credentials dans des secrets CI/CD, jamais dans le code
• Utiliser les digests plutôt que les tags pour les déploiements critiques

Performance

• Préférer crane copy à docker pull/push pour les transferts entre registries
• Utiliser flatten avant de pousser des images finales en production
• Paralléliser les copies dans vos pipelines si vous avez plusieurs images

Organisation

• Versionner les images avec des tags sémantiques (1.2.3, pas latest)
• Documenter les digests des images déployées en production
• Nettoyer régulièrement les anciennes images de vos registries

À retenir

1. Crane fonctionne sans Docker : idéal pour les environnements CI/CD restreints
2. crane copy est plus efficace que pull/tag/push : il ne copie que les layers manquants
3. Le manifest contient toutes les métadonnées d’une image (layers, taille, digest)
4. flatten optimise les images en fusionnant les layers, mais supprime le cache
5. Les digests sont immuables : préférez-les aux tags pour la reproductibilité
6. Authentification : utilisez toujours des variables d’environnement pour les secrets
7. Projet Google : Crane fait partie de go-containerregistry, maintenu activement

Prochaines étapes

Images de conteneurs Comprendre la structure et le fonctionnement des images OCI

Docker Le moteur de conteneurs le plus utilisé

Skopeo Autre outil de manipulation d'images, complémentaire à Crane

Plus d’infos

• go-containerregistry sur GitHub — Le projet qui contient Crane
• Documentation Crane — Référence des commandes
• Releases Crane — Télécharger les binaires

Questions fréquentes

Quelle est la différence entre Crane et Skopeo ?

Comment installer Crane sur Linux ?

Comment copier une image entre deux registries avec Crane ?

Comment aplatir les layers d'une image Docker ?

Comment voir les layers d'une image sans Docker ?

Crane nécessite-t-il Docker pour fonctionner ?

Comment s'authentifier à une registry privée avec Crane ?

Comment modifier les labels d'une image existante ?

Comment utiliser Crane dans une GitHub Action ?

Comment obtenir le digest SHA256 d'une image ?

×

📖 Voir la documentation →