Gérez vos images conteneurs avec Skopeo

Skopeo vous permet d’inspecter, copier et supprimer des images conteneurs directement sur les registres, sans les télécharger ni démarrer de daemon. En 10 minutes, vous saurez transférer une image entre Docker Hub et un registre privé, créer un miroir local, et préparer des images pour un environnement air-gap.

Ce que vous allez apprendre

• Inspecter une image distante : consulter métadonnées, tags et digest sans télécharger
• Copier entre registres : transférer images entre Docker Hub, Quay.io, Harbor
• Synchroniser un miroir : répliquer plusieurs images avec un fichier YAML
• Gérer l’air-gap : exporter et importer des images pour environnements déconnectés

Pourquoi Skopeo plutôt que Docker ?

Contrairement à Docker ou Podman, Skopeo ne nécessite aucun daemon. Il transfère les images directement de registre à registre, sans passage par votre machine locale. Idéal pour les pipelines CI/CD et les scripts d’automatisation.

Ce que Skopeo sait faire

Skopeo couvre quatre cas d’usage principaux pour la gestion des images conteneurs :

Fonctionnalité	Commande	Cas d’usage
Inspection	skopeo inspect	Vérifier les métadonnées, l’architecture, les couches avant téléchargement
Copie	skopeo copy	Transférer une image entre registres ou vers un fichier local
Synchronisation	skopeo sync	Répliquer plusieurs images/tags vers un miroir privé
Suppression	skopeo delete	Supprimer une image d’un registre distant

Glissez pour voir

Transports supportés

Skopeo supporte plusieurs formats de source/destination (appelés “transports”) :

Transport	Format	Description
docker://	docker://registry/image:tag	Registre Docker (Docker Hub, Quay.io, Harbor, etc.)
dir:	dir:/chemin/local	Répertoire local avec les couches et le manifest
docker-archive:	docker-archive:/chemin/image.tar	Archive au format docker save
oci:	oci:/chemin:tag	Répertoire au format OCI
oci-archive:	oci-archive:/chemin/image.tar	Archive au format OCI
containers-storage:	containers-storage:image:tag	Stockage local Podman/Buildah

Glissez pour voir

Installation de Skopeo

Debian/Ubuntu

sudo apt update && sudo apt install -y skopeo

Note

Sur Ubuntu 22.04+, la version disponible via apt est souvent en retard sur la dernière release. Si vous avez besoin des dernières fonctionnalités (comme --retry-delay), consultez la section compilation depuis les sources.

RHEL/Fedora

sudo dnf install -y skopeo

macOS

brew install skopeo

Windows (WSL)

Sous WSL avec Ubuntu :

sudo apt update && sudo apt install -y skopeo

Vérification de l’installation :

skopeo --version

Résultat attendu (la version peut varier) :

skopeo version 1.21.0
commit: 8bd9c541f0513a3f688bdae54c5f0ec4e581f420

Version minimale recommandée

Ce guide utilise des fonctionnalités disponibles à partir de la version 1.17.0. Les options --retry-delay (v1.18.0) et --image-parallel-copies (v1.16.0) sont facultatives mais utiles pour les gros transferts.

Inspecter une image distante

La commande skopeo inspect permet de consulter les métadonnées d’une image sans la télécharger. Pratique pour vérifier l’architecture, la date de création ou les variables d’environnement avant de déployer.

Afficher les métadonnées complètes

skopeo inspect docker://docker.io/library/nginx:1.27.3

Extrait du résultat :

{
    "Name": "docker.io/library/nginx",
    "Digest": "sha256:bc2f6a7c8ddbccf55bdb19659ce3b0a92ca6559e86d42677a5a02ef6bda2fcef",
    "RepoTags": ["1", "1-alpine", "1.27", "1.27.3", "..."],
    "Architecture": "amd64",
    "Os": "linux",
    "Created": "2024-11-26T18:42:08Z",
    "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "NGINX_VERSION=1.27.3",
        "NJS_VERSION=0.8.7"
    ]
}

Les informations clés retournées :

• Digest : empreinte SHA256 unique de l’image (garantit l’intégrité)
• RepoTags : tous les tags disponibles pour cette image
• Architecture/Os : plateforme cible (amd64, arm64, linux, windows)
• Created : date de build de l’image
• Env : variables d’environnement définies dans l’image

Extraire une information spécifique avec jq

Pour n’afficher que certains champs, combinez avec jq :

skopeo inspect docker://docker.io/library/nginx:1.27.3 | jq '{Name, Digest, Architecture, Os, Created}'

Résultat :

{
  "Name": "docker.io/library/nginx",
  "Digest": "sha256:bc2f6a7c8ddbccf55bdb19659ce3b0a92ca6559e86d42677a5a02ef6bda2fcef",
  "Architecture": "amd64",
  "Os": "linux",
  "Created": "2024-11-26T18:42:08Z"
}

Lister les tags disponibles

Pour connaître toutes les versions publiées d’une image :

skopeo list-tags docker://docker.io/library/nginx

Filtrer les tags avec jq (ici, les versions 1.27.x) :

skopeo list-tags docker://docker.io/library/nginx | jq '.Tags | map(select(startswith("1.27"))) | .[:10]'

Résultat :

[
  "1.27",
  "1.27-alpine",
  "1.27-alpine-otel",
  "1.27-alpine-perl",
  "1.27-alpine-slim",
  "1.27-alpine3.19",
  "1.27-alpine3.19-otel",
  "1.27-alpine3.19-perl",
  "1.27-alpine3.19-slim",
  "1.27-alpine3.20"
]

Inspection avec authentification

Si le registre nécessite une authentification :

skopeo inspect --creds utilisateur:mot_de_passe docker://registry.example.com/mon-image:1.0.0

Ou avec un fichier d’authentification (format Docker) :

skopeo inspect --authfile ~/.docker/config.json docker://registry.example.com/mon-image:1.0.0

Copier des images entre registres

La commande skopeo copy transfère une image d’une source vers une destination. Le transfert s’effectue directement entre les registres — votre machine ne stocke pas l’image.

Copie de base entre deux registres

skopeo copy docker://docker.io/library/alpine:3.20.6 docker://registry.example.com/alpine:3.20.6

L’image alpine:3.20.6 est copiée de Docker Hub vers votre registre privé.

Toujours pinner les versions

Évitez d’utiliser le tag latest dans vos pipelines. Préférez une version précise comme 3.20.6 pour garantir la reproductibilité.

Copie avec authentification

Quand source et/ou destination nécessitent des credentials :

skopeo copy \
  --src-creds utilisateur_source:mdp_source \
  --dest-creds utilisateur_dest:mdp_dest \
  docker://quay.io/mon-org/mon-app:2.1.0 \
  docker://registry.example.com/mon-app:2.1.0

Copier vers un répertoire local

Pour extraire les couches et le manifest dans un dossier :

skopeo copy docker://docker.io/library/alpine:3.20.6 dir:/tmp/alpine-3.20.6

Contenu du répertoire créé :

/tmp/alpine-3.20.6/
├── 0a9a5dfd008f...  # Couche (layer) compressée
├── ff221270b9fb...  # Configuration de l'image
├── manifest.json    # Manifest décrivant l'image
└── version          # Version du format

Copier vers une archive Docker

Pour créer un fichier .tar compatible avec docker load :

skopeo copy docker://docker.io/library/alpine:3.20.6 docker-archive:/tmp/alpine-3.20.6.tar

Copier vers une archive OCI

Format OCI, compatible avec podman load et les runtimes OCI :

skopeo copy docker://docker.io/library/alpine:3.20.6 oci-archive:/tmp/alpine-3.20.6-oci.tar

Convertir entre formats Docker et OCI

De Docker vers OCI :

skopeo copy docker://docker.io/library/nginx:1.27.3 oci:nginx-oci:1.27.3

De OCI vers archive Docker :

skopeo copy oci:nginx-oci:1.27.3 docker-archive:nginx.tar

Options utiles pour la copie

Option	Description
--all	Copie toutes les architectures d’une image multi-arch
--preserve-digests	Conserve les digests d’origine (utile pour les signatures)
--retry-times 3	Nombre de tentatives en cas d’échec réseau
--retry-delay 5s	Délai entre les tentatives (v1.18.0+)
--digestfile /tmp/digest.txt	Écrit le digest de l’image copiée dans un fichier

Glissez pour voir

Exemple avec options de fiabilité :

skopeo copy \
  --retry-times 3 \
  --retry-delay 5s \
  --digestfile /tmp/nginx-digest.txt \
  docker://docker.io/library/nginx:1.27.3 \
  docker://registry.example.com/nginx:1.27.3

Environnements air-gap (déconnectés)

Dans les environnements isolés d’Internet, Skopeo permet d’exporter puis d’importer des images sans connexion réseau.

Workflow complet air-gap

1. Sur une machine connectée : exportez l’image vers une archive

   skopeo copy docker://docker.io/library/nginx:1.27.3 docker-archive:/media/usb/nginx-1.27.3.tar

2. Transférez l’archive vers l’environnement air-gap (clé USB, disque, etc.)

3. Sur la machine air-gap : importez l’image vers le registre privé

   skopeo copy docker-archive:/media/usb/nginx-1.27.3.tar docker://registre-interne.local/nginx:1.27.3

Images multi-architecture

Pour copier toutes les architectures (amd64, arm64, etc.), ajoutez l’option --all :

skopeo copy --all docker://docker.io/library/nginx:1.27.3 docker-archive:/media/usb/nginx-1.27.3-multiarch.tar

Synchroniser plusieurs images

La commande skopeo sync réplique plusieurs images ou tags en une seule opération. Idéal pour maintenir un miroir privé à jour.

Synchronisation d’un dépôt complet

Synchroniser tous les tags d’une image :

skopeo sync --src docker --dest docker docker.io/library/alpine registry.example.com

Cette commande copie tous les tags de alpine vers votre registre.

Synchronisation sélective avec fichier YAML

Pour un contrôle fin, définissez les images dans un fichier YAML :

sync.yaml

# Registre source : docker.io
docker.io:
  images:
    # Toutes les versions d'alpine >= 3.19
    alpine:
      - "3.19"
      - "3.20"
      - "3.20.6"
    # Versions spécifiques de nginx
    nginx:
      - "1.27.3"
      - "1.27.3-alpine"
  tls-verify: true

# Registre source : quay.io
quay.io:
  images:
    prometheus/prometheus:
      - "v2.54.1"
      - "v2.55.0"
  tls-verify: true

Exécution :

skopeo sync --src yaml --dest docker sync.yaml registry.example.com/mirror/

Options de synchronisation utiles

Option	Description
--dry-run	Simule la synchronisation sans copier
--keep-going	Continue même si une image échoue
--scoped	Préfixe les images avec leur chemin source
--all	Synchronise toutes les architectures

Glissez pour voir

Exemple avec dry-run pour vérifier avant d’exécuter :

skopeo sync --src yaml --dest docker --dry-run sync.yaml registry.example.com/mirror/

Créer un miroir local (répertoire)

Pour stocker les images localement avant de les transférer :

skopeo sync --src docker --dest dir docker.io/library/alpine /backup/images/

Puis pousser le miroir local vers un registre :

skopeo sync --src dir --dest docker /backup/images/ registry.example.com

Supprimer une image distante

La commande skopeo delete supprime une image directement sur le registre :

skopeo delete docker://registry.example.com/mon-app:1.0.0-obsolete

Action irréversible

La suppression est définitive. Assurez-vous que l’image n’est plus utilisée avant de la supprimer. Certains registres (comme Docker Hub) ne permettent pas la suppression via l’API.

Avec authentification :

skopeo delete --creds admin:secret docker://registry.example.com/test-image:dev

Comparer deux images

Pour vérifier si deux images sont identiques (même contenu), comparez leurs digests :

# Digest de l'image sur Docker Hub
skopeo inspect docker://docker.io/library/nginx:1.27.3 | jq -r '.Digest'

# Digest de l'image sur votre registre
skopeo inspect docker://registry.example.com/nginx:1.27.3 | jq -r '.Digest'

Si les deux digests sont identiques, les images sont strictement équivalentes (même contenu binaire).

Dépannage

Erreur “unauthorized: authentication required”

Le registre nécessite une authentification. Solutions :

# Option 1 : credentials en ligne de commande
skopeo inspect --creds utilisateur:mot_de_passe docker://registry.example.com/image:tag

# Option 2 : fichier d'authentification
skopeo login registry.example.com
skopeo inspect docker://registry.example.com/image:tag

Erreur “certificate signed by unknown authority”

Le certificat TLS du registre n’est pas reconnu. Solutions :

# Option 1 : désactiver la vérification TLS (non recommandé en production)
skopeo inspect --tls-verify=false docker://registry.example.com/image:tag

# Option 2 : spécifier le répertoire des certificats
skopeo inspect --cert-dir /etc/docker/certs.d/registry.example.com docker://registry.example.com/image:tag

Erreur “manifest unknown” ou “not found”

L’image ou le tag n’existe pas. Vérifiez :

1. Le nom exact de l’image et du tag
2. Que vous avez les permissions de lecture
3. Listez les tags disponibles : skopeo list-tags docker://registry/image

Timeout sur gros transferts

Pour les images volumineuses, augmentez les tentatives :

skopeo copy --retry-times 5 --retry-delay 10s docker://source/image:tag docker://dest/image:tag

À retenir

• Skopeo fonctionne sans daemon : contrairement à Docker, il ne nécessite aucun service en arrière-plan
• Transfert direct : les images passent de registre à registre sans stockage intermédiaire
• Pinner les versions : utilisez toujours des tags précis (ex: 1.27.3) plutôt que latest
• Plusieurs formats : Skopeo convertit entre Docker, OCI, archives et répertoires
• Air-gap ready : export/import via archives pour les environnements déconnectés

Prochaines étapes

Construire des images avec Buildah Créez des images conteneurs sans daemon Docker

Analyser les couches avec Dive Visualisez et optimisez la taille de vos images

Scanner les vulnérabilités avec Trivy Détectez les failles de sécurité dans vos images

Configurer Harbor Déployez votre propre registre d'images privé

Plus d’infos

• Documentation officielle Skopeo
• Changelog des versions
• Guide de migration d’images

FAQ — Questions fréquentes

Qu'est-ce que Skopeo et pourquoi l'utiliser ?

Quelle est la différence entre Skopeo et Docker pour copier des images ?

Comment inspecter une image distante sans la télécharger ?

Comment copier une image vers un environnement air-gap ?

Comment synchroniser un miroir privé avec skopeo sync ?

Comment résoudre les erreurs d'authentification avec Skopeo ?

Comment résoudre les erreurs de certificat TLS avec Skopeo ?

Quels sont les transports supportés par Skopeo ?

Comment comparer deux images pour vérifier qu'elles sont identiques ?

Comment supprimer une image d'un registre distant avec Skopeo ?

×

📖 Voir la documentation →