E-NO
DevOps 10 min de lecture

Commandes du registre Docker : guide pratique d'exploitation

calendar_today Publié : 2026-11-21
update Dernière mise à jour : 2026-11-21
analytics Efficacité SEO : 100%
Illustration du guide technique pour « Commandes du registre Docker : guide pratique d'exploitation ».

Introduction

Exploiter un registre de conteneurs ne se limite pas à installer un logiciel : il s'agit de garantir une distribution d'images fiable, observable et récupérable. Ce guide passe en revue les commandes du registre Docker que vous utiliserez au quotidien : de la vérification de l'environnement et du tirage d'images à l'inspection des manifestes, au nettoyage des étiquettes et au dépannage des échecs.

Le public visé comprend les développeurs, les consultants DevOps et les équipes techniques de startups qui exploitent un registre privé ou doivent interagir efficacement avec Docker Hub. Chaque section suit un schéma pratique : une observation en lecture seule, une modification justifiée, puis une commande ou un signal qui vérifie le résultat.

La sécurité opérationnelle est le principe fondamental. Avant de modifier quoi que ce soit, capturez l'état actuel. Utilisez des espaces réservés au lieu de secrets réels dans les exemples. Limitez les modifications à un élément précis et sachez comment récupérer si l'état attendu n'est pas atteint. Les commandes ci-dessous utilisent un registre local sur localhost:5000 comme exemple principal, mais les modèles s'appliquent à tout déploiement Docker Registry v2.

Inventaire des versions et de l'environnement

Avant d'exécuter une commande de registre, confirmez ce qui est en cours d'exécution et comment c'est configuré. Cela évite des erreurs comme pousser vers le mauvais registre ou déboguer un conteneur qui n'est même pas dans l'état attendu.

Commencez par les versions du client et du démon Docker. L'API du registre a évolué et certaines commandes se comportent différemment selon les versions.

docker version

La sortie attendue comprend une section Client et une section Server. Notez la API version pour les deux ; une inadéquation entre le client et le démon peut provoquer des erreurs inattendues. Pour la compatibilité spécifique au registre, vérifiez la version du registre si vous le contrôlez :

curl -s http://localhost:5000/v2/ | jq .

Un registre sain renvoie un objet JSON vide {}. Si vous voyez une erreur de connexion refusée, le registre ne tourne pas ou n'écoute pas sur ce port.

Observation des conteneurs en cours d'exécution et des piles Compose

Utilisez docker ps avec un format de tableau pour voir les noms des conteneurs, leur statut et les ports publiés d'un coup d'œil :

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Exemple de sortie :

NAMES               STATUS              PORTS
registry            Up 10 minutes       0.0.0.0:5000->5000/tcp

Si le conteneur du registre est absent, inspectez tous les conteneurs, y compris les arrêtés, avec docker ps -a. Pour les déploiements basés sur Compose, utilisez docker compose ps pour voir l'état des services définis dans docker-compose.yml.

Les journaux sont essentiels pour diagnostiquer les échecs de démarrage ou les erreurs d'exécution. Limitez la sortie aux lignes les plus récentes pour éviter le bruit :

docker logs registry --tail 100

Recherchez des lignes telles que level=info msg="listening on [::]:5000" pour confirmer que le registre a démarré correctement. Les problèmes courants incluent une configuration de stockage manquante ou des erreurs de permission sur le répertoire de données.

Lorsqu'une configuration plus approfondie est nécessaire, docker inspect révèle les montages, les réseaux, les variables d'environnement et l'état de santé.

docker inspect registry --format '{{json .Mounts}}'

Cela produit un tableau JSON des points de montage. Vérifiez que le conteneur dispose d'un volume persistant pour les données du registre. Par exemple, une configuration saine peut montrer un montage bind de /var/lib/registry sur l'hôte vers /var/lib/registry dans le conteneur.

Stockage et persistance des données

Avant de modifier ou de recréer le conteneur du registre, identifiez où les blobs d'images sont stockés. Un volume nommé est géré par Docker et survit à la recréation du conteneur.

# fragment docker-compose.yml
services:
  registry:
    image: registry:2
    volumes:
      - registry_data:/var/lib/registry
volumes:
  registry_data:

Un montage bind mappe directement un répertoire hôte :

volumes:
  - /srv/registry:/var/lib/registry

Les montages bind sont utiles pour le développement local ou lorsque vous avez besoin d'un accès direct aux fichiers, mais ils peuvent causer des problèmes de permission si l'UID du conteneur ne peut pas écrire dans le chemin hôte. Les volumes nommés sont généralement plus sûrs pour la production.

Un test de redémarrage valide la persistance : arrêtez le conteneur, recréez-le et confirmez que les images sont toujours disponibles.

docker stop registry
docker start registry
# Ou pour Compose :
docker compose stop registry
docker compose up -d registry
curl -s http://localhost:5000/v2/_catalog

Le point de terminaison catalog liste les dépôts. S'il renvoie des dépôts après le redémarrage, les données ont été correctement persistées. S'il est vide, le registre écrivait probablement dans le système de fichiers éphémère du conteneur.

Question rapide 1 sur 2

Selon les passages, quelle est la relation entre un registre et un dépôt ?

Le passage 4 distingue explicitement les deux : un registre est un emplacement centralisé qui stocke et gère des images de conteneurs, tandis qu'un dépôt est une collection d'images liées au sein d'un registre (comme un dossier).

Chemin de configuration sûr

La configuration du registre est contrôlée par un fichier YAML, souvent monté dans le conteneur à /etc/docker/registry/config.yml. Les modifications doivent être délibérées, versionnées et réversibles.

Affichage de la configuration actuelle

Ne modifiez jamais un fichier de configuration à l'aveugle. D'abord, confirmez le fichier utilisé et son contenu actuel. Si le registre tourne dans un conteneur, vous pouvez extraire la configuration sans rien modifier :

docker exec registry cat /etc/docker/registry/config.yml

Une configuration minimale ressemble à ceci :

version: 0.1
log:
  fields:
    service: registry
storage:
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: :5000

Notez la section storage : elle définit où les blobs sont stockés. La modifier sans migrer les données fera apparaître le registre comme vide.

Effectuer une modification ciblée

Supposons que vous souhaitiez activer l'API de suppression afin de pouvoir supprimer des étiquettes. Par défaut, le registre n'autorise pas les suppressions à moins que la suppression de stockage ne soit explicitement activée. La modification est double : ajouter delete: enabled: true sous storage et redémarrer le registre.

Avant d'effectuer la modification, sauvegardez le fichier de configuration actuel :

cp config.yml config.yml.bak.$(date +%Y%m%d)

Ensuite, éditez le fichier en ajoutant les lignes pertinentes :

storage:
  delete:
    enabled: true
  filesystem:
    rootdirectory: /var/lib/registry

Redémarrez le registre et vérifiez le nouveau comportement en tentant une suppression via l'API (couvert plus loin dans « Modes de défaillance et récupération »). Si la modification cause des problèmes, revenez à la sauvegarde et redémarrez à nouveau.

Pour les déploiements Compose, stockez la configuration dans le répertoire du projet et montez-la comme fichier :

services:
  registry:
    image: registry:2
    volumes:
      - ./config.yml:/etc/docker/registry/config.yml:ro

L'utilisation de :ro (lecture seule) empêche les écritures accidentelles depuis l'intérieur du conteneur.

Variables d'environnement et secrets

Certaines fonctionnalités du registre, comme le stockage S3 ou l'authentification, nécessitent des informations d'identification. Évitez de mettre des secrets directement dans le fichier de configuration. Utilisez plutôt des variables d'environnement ou des secrets Docker.

Par exemple, si vous utilisez le stockage S3, le fichier de configuration peut référencer des variables d'environnement :

storage:
  s3:
    accesskey: ${S3_ACCESS_KEY}
    secretkey: ${S3_SECRET_KEY}
    region: us-east-1
    bucket: my-registry

Puis passez les variables au moment de l'exécution :

docker run -d -p 5000:5000 \
  -e S3_ACCESS_KEY=... \
  -e S3_SECRET_KEY=... \
  -v /path/to/config.yml:/etc/docker/registry/config.yml \
  registry:2

Ne commitez jamais de vraies clés dans le contrôle de version. Utilisez un gestionnaire de secrets ou un fichier d'environnement exclu de git.

Vérification et diagnostics

Après toute modification ou pendant les opérations régulières, vérifiez la santé et la fonctionnalité du registre avec des commandes en lecture seule.

Point de terminaison de santé

L'API du registre v2 n'a pas de point de terminaison de santé dédié, mais vous pouvez vérifier le point de terminaison racine :

curl -s http://localhost:5000/v2/ | jq .

Attendu : {}. Si vous voulez un contrôle de santé plus robuste, activez le point de terminaison de santé en ajoutant à la configuration :

http:
  addr: :5000
  debug:
    addr: :5001

Ensuite, vous pouvez interroger http://localhost:5001/debug/health qui renvoie {} si sain.

Liste des dépôts et des étiquettes

Pour voir tous les dépôts du registre :

curl -s http://localhost:5000/v2/_catalog | jq .

Exemple de sortie :

{
  "repositories": [
    "myapp",
    "myapp-web",
    "backend"
  ]
}

Pour lister les étiquettes d'un dépôt spécifique :

curl -s http://localhost:5000/v2/myapp/tags/list | jq .

Cela renvoie un objet JSON avec un tableau tags, par exemple ["latest", "1.0", "1.1"].

Inspection des manifestes

Avant de tirer ou de pousser, vous pouvez inspecter le manifeste d'une image pour comprendre ses couches et sa configuration.

curl -s -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/myapp/manifests/latest | jq .

La réponse comprend schemaVersion, mediaType, config et layers. C'est utile pour auditer le contenu des images, vérifier les références basées sur les condensés et déboguer les erreurs « manifest unknown ».

Pour obtenir le condensé d'un manifeste, utilisez l'en-tête Docker-Content-Digest :

curl -sI -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  http://localhost:5000/v2/myapp/manifests/latest | grep Docker-Content-Digest

Exemple de sortie :

Docker-Content-Digest: sha256:1234abcd...

Ce condensé identifie de manière unique le manifeste et peut être utilisé pour des tirages immuables.

Diagnostics du client Docker

Lorsque vous travaillez avec un registre distant, la CLI docker fournit plusieurs commandes pour le dépannage :

  • docker search myapp - rechercher sur Docker Hub (utile pour vérifier l'accès réseau et la connectivité du registre).
  • docker pull localhost:5000/myapp:latest - tirer avec sortie verbeuse pour voir les téléchargements de couches et les erreurs potentielles.
  • docker push localhost:5000/myapp:1.1 - pousser et observer la progression de l'envoi.

Pour les problèmes de tirage/poussée, définissez DOCKER_CONTENT_TRUST=0 si vous rencontrez des erreurs de vérification de signature dans un environnement de développement (ne désactivez jamais la confiance en production).

Modes de défaillance et récupération

Même avec une planification minutieuse, des échecs surviennent. Reconnaître les modèles de défaillance courants et savoir comment récupérer est essentiel.

Manifeste inconnu

Symptôme : docker pull échoue avec manifest unknown ou HTTP 404 de l'API du registre.

Cause : L'étiquette n'existe plus, n'a jamais été poussée, ou le nom du dépôt est mal orthographié. Cela peut aussi se produire si le stockage du registre a été effacé ou modifié.

Diagnostic :

curl -s http://localhost:5000/v2/myapp/tags/list

Si l'étiquette est absente, elle a été supprimée ou jamais poussée. Vérifiez localement avec docker images si l'image existe.

Récupération : Poussez à nouveau l'image si elle existe localement :

docker tag myapp:latest localhost:5000/myapp:latest
docker push localhost:5000/myapp:latest

Si le manifeste est dans le registre mais que docker pull échoue toujours, essayez de tirer par condensé :

docker pull localhost:5000/myapp@sha256:1234abcd...

Si cela fonctionne, l'étiquette peut être corrompue ou pointer vers un manifeste manquant. Supprimez l'étiquette et repoussez.

Permission de stockage refusée

Symptôme : Le conteneur du registre démarre mais le journal montre permission denied lors de l'écriture dans /var/lib/registry.

Cause : Le répertoire hôte d'un montage bind est possédé par un UID différent de celui du processus du registre (qui s'exécute par défaut avec l'UID 1000).

Diagnostic :

docker logs registry | grep -i permission

Vérifiez la propriété du répertoire hôte :

ls -ld /srv/registry

S'il appartient à root et que le registre s'exécute en non-root, les écritures échoueront.

Récupération : Changez la propriété du répertoire hôte pour correspondre à l'UID du conteneur, ou exécutez le conteneur avec un utilisateur correspondant. Pour une solution rapide en développement :

chown -R 1000:1000 /srv/registry

Mieux : définissez un volume nommé qui gère automatiquement les permissions.

La suppression échoue avec 405 Method Not Allowed

Symptôme : Tenter de supprimer une étiquette via l'API renvoie HTTP 405 ou une erreur apparaît dans les journaux.

Cause : L'API de suppression est désactivée par défaut. La configuration n'a pas storage.delete.enabled: true.

Diagnostic : Vérifiez la section delete dans la configuration.

docker exec registry cat /etc/docker/registry/config.yml | grep -A2 delete

Récupération : Activez la suppression comme décrit dans « Chemin de configuration sûr », redémarrez le registre et réessayez. Notez que la suppression d'un manifeste ne supprime que la référence de l'étiquette ; les blobs peuvent rester jusqu'à ce que le garbage collection soit exécuté.

Garbage collection

Après la suppression d'étiquettes, les blobs deviennent orphelins et consomment de l'espace disque. Pour récupérer de l'espace, exécutez le garbage collection :

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml --dry-run

Remplacez --dry-run par aucun drapeau pour réellement supprimer les blobs. Exécutez-le pendant que le registre est en mode lecture seule ou arrêté pour éviter la corruption.

Question rapide 2 sur 2

Lequel des éléments suivants n'est PAS répertorié parmi les registres de conteneurs disponibles dans les passages ?

Le passage 2 répertorie Docker Hub, ECR, ACR, GCR, Harbor, JFrog Artifactory et GitLab Container Registry. Quay.io n'est pas mentionné.

Liste de vérification opérationnelle

Utilisez cette liste de vérification lors de la maintenance de routine, de la réponse aux incidents ou avant d'effectuer des modifications.

Avant toute modification

  • [ ] Enregistrez la version et la configuration actuelles du registre : docker exec registry cat /etc/docker/registry/config.yml > config.backup
  • [ ] Vérifiez que le registre est sain : curl -s http://localhost:5000/v2/
  • [ ] Listez les dépôts et les étiquettes pour avoir une base de référence : curl -s http://localhost:5000/v2/_catalog
  • [ ] Assurez-vous d'avoir un plan de retour en arrière : configuration sauvegardée, étiquettes d'images connues comme bonnes ou un instantané.

Pendant la modification

  • [ ] Effectuez une modification à la fois (par exemple, modifier la configuration, mettre à jour une variable d'environnement ou recréer un conteneur).
  • [ ] Si vous modifiez la configuration, utilisez le contrôle de version ou conservez une sauvegarde horodatée.
  • [ ] Redémarrez le registre et surveillez les journaux pour les erreurs : docker logs registry --tail 100 -f
  • [ ] Testez la modification avec une commande en lecture seule d'abord.

Après la modification

  • [ ] Vérifiez la santé : curl -s http://localhost:5000/v2/
  • [ ] Tirez et poussez une image de test pour confirmer la fonctionnalité complète :
  docker pull hello-world
  docker tag hello-world localhost:5000/test:1
  docker push localhost:5000/test:1
  docker rmi localhost:5000/test:1
  docker pull localhost:5000/test:1
  • [ ] Si le test réussit, supprimez l'image et l'étiquette de test.
  • [ ] Mettez à jour la documentation ou le runbook avec le nouvel état.

Attribuez un propriétaire responsable unique pour les opérations du registre, comme le responsable DevOps. Révisez la configuration et les paramètres de sécurité du registre mensuellement, ou après tout changement majeur d'infrastructure.

Pièges courants

Plusieurs erreurs reviennent dans les opérations de registre. Les connaître permet de gagner du temps et d'éviter la perte de données.

Utiliser l'étiquette latest en production

Pourquoi cela arrive : Commodité. Les développeurs poussent latest et les scripts de déploiement le tirent toujours.

Risque : Builds non déterministes, incapacité à revenir en arrière et ambiguïté sur ce qui est en cours d'exécution.

Évitement : Étiquetez toujours les images avec des versions explicites (1.0.0, SHA de commit ou date). Utilisez des étiquettes immuables lorsque c'est possible. Appliquez via des politiques CI/CD.

Ignorer les limitations du backend de stockage

Pourquoi cela arrive : Le stockage par système de fichiers par défaut est simple et fonctionne localement, donc les équipes supposent qu'il passe à l'échelle.

Risque : Dégradation des performances, manque de redondance et point de défaillance unique.

Évitement : Évaluez le stockage objet (S3, GCS, Azure Blob) pour la production. Testez le débit et la latence avec des tailles d'images réalistes. Surveillez l'utilisation du disque sur l'hôte du registre.

Exposer le registre sans authentification

Pourquoi cela arrive : Configuration rapide pour le développement, puis oubliée.

Risque : N'importe qui peut pousser des images malveillantes ou tirer du code propriétaire.

Évitement : Activez toujours l'authentification (basic auth, token auth) et TLS. Utilisez un proxy inverse comme Nginx avec des certificats clients pour les environnements sensibles. Auditez régulièrement l'accès.

Négliger le garbage collection

Pourquoi cela arrive : Les suppressions semblent fonctionner, donc personne ne pense aux blobs restants.

Risque : Le disque se remplit, le registre devient lent et les sauvegardes grossissent inutilement.

Évitement : Planifiez régulièrement le garbage collection après les suppressions d'étiquettes. Surveillez l'utilisation du disque et définissez des alertes. Utilisez --dry-run d'abord pour estimer l'espace récupérable.

Modifier la configuration sans contrôle de version

Pourquoi cela arrive : Le fichier de configuration est dans un conteneur ou sur un serveur sans git.

Risque : Pas d'historique, difficile de revenir en arrière et modifications non révisables.

Évitement : Conservez la configuration dans un dépôt, déployez via l'automatisation et utilisez docker config ou montez depuis l'hôte avec des permissions appropriées. Documentez chaque modification manuelle.

Conclusion

Maîtriser les commandes du registre Docker vous fait passer de la lutte contre les incendies à une exploitation proactive. La clé est de traiter le registre comme un composant d'infrastructure critique : observer avant de modifier, limiter le rayon d'impact, vérifier les résultats et documenter les chemins de récupération.

Comme prochaine étape, choisissez une vérification à faible risque de ce guide - comme lister les dépôts et vérifier les condensés des manifestes - et exécutez-la contre votre registre. Enregistrez l'état actuel, comparez avec les attentes, et si quelque chose ne va pas, utilisez les modèles de diagnostic pour enquêter.

Rappelez-vous que le registre fait partie d'un écosystème plus large comprenant Docker Hub, l'étiquetage des images et les pipelines CI/CD. Un flux de travail fiable rend les échecs visibles, protège les valeurs sensibles et définit la récupération avant qu'un incident ne force une décision.

Recherches connexes

Score de qualité de l’article

Utilité pour le lecteur 100%
  • check_circle Guide prêt à lire
  • check_circle Exemples pratiques inclus
  • check_circle URL d’article optimisée pour le SEO