Sauvegarde et restauration d'un registre Docker : guide pratique avec exemples concrets

Introduction

Exploiter un registre Docker en production implique la responsabilité de l'intégrité et de la disponibilité des images dont dépend votre équipe. Un registre perdu peut interrompre les pipelines CI/CD, bloquer les déploiements et vous contraindre à reconstruire des artefacts qui n'existent peut-être plus ailleurs. La sauvegarde et la restauration ne sont pas des ajouts optionnels ; ce sont des tâches opérationnelles essentielles.

Ce guide détaille la sauvegarde et la restauration d'un registre Docker en utilisant l'image officielle registry:2 et un stockage basé sur le système de fichiers. Vous apprendrez à inspecter votre environnement, à sauvegarder les données en toute sécurité, à vérifier les sauvegardes, à restaurer après une panne et à automatiser le processus. Chaque commande est expliquée avec le résultat attendu et les décisions de récupération, afin que vous puissiez appliquer ces étapes en toute confiance.

Nous nous concentrons sur des procédures pratiques, limitées à une version, qui minimisent les risques. Avant de modifier quoi que ce soit, observez l'état actuel. Utilisez des espaces réservés au lieu de secrets. Après toute modification, vérifiez le résultat. C'est la sécurité opérationnelle en action.

Inventaire de la version et de l'environnement

Commencez par savoir exactement ce que vous avez. L'image officielle du registre Docker est registry:2, et ses données résident dans /var/lib/registry à l'intérieur du conteneur. La plupart des configurations de production l'exécutent avec Docker Compose ou Kubernetes, mais les concepts de base s'appliquent largement.

Tout d'abord, confirmez que le conteneur est en cours d'exécution et notez sa configuration :

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

Le résultat attendu pourrait ressembler à :

NAMES       STATUS         PORTS
registry    Up 3 hours     0.0.0.0:5000->5000/tcp

Ensuite, inspectez le conteneur pour voir ses montages, ses variables d'environnement et son état de santé :

docker inspect registry

Recherchez la section Mounts. Si vous voyez un volume nommé ou un montage de liaison pour /var/lib/registry, vos données sont déjà persistantes. Sinon, votre registre écrit dans le système de fichiers du conteneur et perdra tout lorsque le conteneur sera supprimé.

Consultez les journaux récents pour détecter toute erreur ou tout avertissement :

docker logs registry --tail 100

Si vous utilisez Docker Compose, les commandes équivalentes sont :

docker compose ps
docker compose logs -f registry
docker compose exec registry sh

La dernière commande vous donne un shell à l'intérieur du conteneur pour inspecter directement le système de fichiers. Exécutez df -h /var/lib/registry pour voir l'utilisation du disque et vous assurer que le volume dispose de suffisamment d'espace pour les sauvegardes.

Confirmation de la persistance des données

À ce stade, vous devez confirmer où les données du registre sont stockées. Un volume nommé comme registry_data:/var/lib/registry est géré par Docker et survit à la recréation du conteneur. Un montage de liaison comme ./data:/var/lib/registry correspond directement à un répertoire hôte, plus facile à inspecter et à sauvegarder mais pouvant causer des problèmes de permissions sur différentes machines.

Pour tester la persistance, effectuez un test de redémarrage :

1. Arrêtez le conteneur : docker stop registry
2. Redémarrez-le : docker start registry
3. Récupérez la liste des images du registre : curl -s http://localhost:5000/v2/_catalog

Si la liste affiche toujours vos images, les données ont persisté. Si elle est vide, votre volume n'est pas monté correctement. Corrigez le montage avant de continuer.

Chemin de configuration sécurisé

La façon la plus sûre de sauvegarder un registre Docker est d'éviter d'interférer avec les opérations d'écriture en cours. Pour un registre basé sur le système de fichiers, l'approche recommandée consiste à placer le registre en mode lecture seule avant de copier les données. Cela évite la corruption due à des écritures concurrentes.

Étape 1 : Mettre le registre en mode lecture seule

Vous pouvez activer le mode lecture seule en définissant la variable d'environnement REGISTRY_STORAGE_MAINTENANCE_READONLY sur enabled et en recréant le conteneur. Avec Docker Compose, ajoutez à votre service :

services:
  registry:
    image: registry:2
    environment:
      REGISTRY_STORAGE_MAINTENANCE_READONLY: enabled
    volumes:
      - registry_data:/var/lib/registry

Ensuite, exécutez :

docker compose up -d

Vérifiez que le registre est en lecture seule en tentant de pousser une image. Cela devrait échouer avec une erreur 405. Par exemple :

docker push localhost:5000/test:latest

Le résultat attendu inclut :

The push refers to repository [localhost:5000/test]
...
error: failed to push image: received unexpected HTTP status: 405 Method Not Allowed

Étape 2 : Sauvegarder le répertoire de données

Maintenant que le registre est stable, copiez les données. Si vous utilisez un volume nommé, vous pouvez utiliser un conteneur temporaire pour exporter les données :

docker run --rm -v registry_data:/data -v $(pwd):/backup alpine tar czf /backup/registry-backup-$(date +%Y%m%d%H%M).tar.gz -C /data .

Cette commande crée une archive compressée dans votre répertoire courant avec un horodatage. Si vous utilisez un montage de liaison, vous pouvez simplement compresser le répertoire hôte :

tar czf registry-backup-$(date +%Y%m%d%H%M).tar.gz -C ./data .

Vérifiez la taille de l'archive et listez son contenu pour confirmer qu'elle inclut les données :

ls -lh registry-backup-*.tar.gz
tar tzf registry-backup-*.tar.gz | head

Vous devriez voir des fichiers comme docker/registry/v2/repositories/....

Étape 3 : Remettre le registre en mode lecture-écriture

Une fois la sauvegarde terminée, rétablissez le paramètre de lecture seule et redémarrez le registre :

environment:
  REGISTRY_STORAGE_MAINTENANCE_READONLY: disabled

Ensuite, exécutez à nouveau docker compose up -d. Confirmez le fonctionnement normal en poussant une image de test.

Vérification et diagnostics

Une sauvegarde n'est utile que si elle peut être restaurée. La vérification réduit le risque que votre sauvegarde soit incomplète ou corrompue.

Vérifier l'intégrité de la sauvegarde

Un contrôle rapide consiste à comparer le nombre de fichiers et leur taille entre l'original et la sauvegarde. Pendant que le registre est en lecture seule, exécutez :

find /var/lib/registry -type f | wc -l

(Si vous utilisez un volume nommé, vous devrez peut-être exécuter la commande dans un conteneur avec ce volume monté.) Comparez ensuite avec la sauvegarde :

tar tzf registry-backup-*.tar.gz | wc -l

Les nombres doivent correspondre exactement. Une différence suggère que des fichiers ont changé pendant la sauvegarde ou que l'archive est incomplète.

Lister les dépôts après restauration

Après avoir restauré sur un registre de test distinct, interrogez le catalogue :

curl -s http://localhost:5000/v2/_catalog

Résultat attendu :

{"repositories":["myapp","nginx","redis"]}

Comparez avec le catalogue du registre d'origine. Si un dépôt est manquant, la sauvegarde a peut-être été prise depuis le mauvais répertoire ou a ignoré des fichiers cachés.

Diagnostiquer les problèmes courants

Si le registre ne démarre pas après la restauration, consultez les journaux :

docker logs registry

Les erreurs courantes incluent les refus de permission (corrigez la propriété : chown -R 1000:1000 /chemin/vers/les/donnees sur l'hôte, car le conteneur du registre s'exécute avec l'UID 1000) et le stockage corrompu (indiqué par level=error msg="error resolving image"). Dans ce cas, restaurez à partir d'une sauvegarde antérieure.

Modes de défaillance et récupération

Les registres échouent de manière prévisible. Connaître ces modes vous aide à réagir rapidement et avec précision.

Mode de défaillance 1 : Conteneur supprimé accidentellement

Si vous avez un montage de volume, les données survivent. Recréez simplement le conteneur avec le même volume :

docker run -d -p 5000:5000 --name registry -v registry_data:/var/lib/registry registry:2

Le registre servira les mêmes images. Si vous n'aviez pas de volume, vous devez restaurer à partir d'une sauvegarde.

Mode de défaillance 2 : Panne de disque de l'hôte

Si le disque de l'hôte contenant les données du registre tombe en panne, vous devez restaurer la sauvegarde sur un nouveau disque sur un hôte nouveau ou réparé. Après avoir provisionné l'hôte :

1. Recréez la structure de répertoires et définissez les permissions.
2. Extrayez la sauvegarde : tar xzf registry-backup-*.tar.gz -C /nouveau/chemin/donnees
3. Montez ce répertoire dans un nouveau conteneur de registre et démarrez-le.

Mode de défaillance 3 : Stockage corrompu

La corruption du stockage peut survenir en raison d'une coupure de courant brutale ou d'erreurs de disque. Les symptômes incluent des erreurs 500 lors des tirages et des messages de journal comme filesystem: file has vanished. Pour récupérer, arrêtez le registre, remplacez le répertoire de données par la dernière sauvegarde et redémarrez. Si la corruption se reproduit, examinez immédiatement la santé du disque.

Mode de défaillance 4 : Sauvegarde incomplète

Si une sauvegarde a été prise alors que le registre était accessible en écriture, certains blobs peuvent manquer. Vous pouvez le détecter en comparant la taille de la sauvegarde avec celle des données en direct. La restauration peut échouer partiellement ; dans ce cas, utilisez une sauvegarde plus ancienne et repoussez les images ajoutées après cette sauvegarde.

Exercice de récupération

Effectuez un exercice de récupération trimestriel. Simulez une panne en déplaçant le répertoire de données en direct, restaurez à partir de la sauvegarde et vérifiez que docker pull localhost:5000/myapp:latest fonctionne. Documentez les étapes exactes et le temps requis. Cela garantit que votre équipe peut exécuter la récupération sous pression.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour maintenir une stratégie de sauvegarde robuste. Attribuez un seul responsable et révisez la liste mensuellement.

Chaque étape doit avoir un responsable clair, pas une équipe. Si Marcus est indisponible, Priya est son remplaçant, mais la responsabilité reste avec le responsable désigné.

Pièges courants et comment les éviter

Piège 1 : Supposer que le stockage par défaut est persistant

De nombreux utilisateurs débutants exécutent docker run -d -p 5000:5000 registry:2 sans volume. Le registre stocke les données sur le système de fichiers éphémère du conteneur. Lorsque le conteneur est supprimé, toutes les images sont perdues.

Comment l'éviter : Définissez toujours un volume dans votre docker run ou votre fichier compose. Vérifiez avec docker inspect que le montage est présent.

Piège 2 : Prendre des sauvegardes alors que le registre est accessible en écriture

Sauvegarder un système de fichiers en direct peut entraîner un état incohérent : un manifeste d'image est enregistré mais ses blobs ne le sont pas, ou vice versa. Cela conduit à des échecs de restauration.

Comment l'éviter : Activez le mode lecture seule avant la sauvegarde, comme décrit ci-dessus. Si vous ne pouvez pas vous permettre de temps d'arrêt, utilisez des instantanés de système de fichiers (par exemple, LVM, ZFS) pour des sauvegardes atomiques, puis copiez à partir de l'instantané.

Piège 3 : Ignorer les permissions lors de la restauration

Le conteneur du registre s'exécute avec l'UID 1000. Si vous restaurez des fichiers sur l'hôte et qu'ils appartiennent à root, le registre ne peut pas les lire, ce qui entraîne des erreurs de permission.

Comment l'éviter : Après l'extraction, exécutez chown -R 1000:1000 /chemin/vers/donnees/registre avant de démarrer le conteneur.

Piège 4 : Ne pas tester les restaurations

Une sauvegarde qui n'a jamais été restaurée est un espoir, pas une sauvegarde. Les archives corrompues, les fichiers manquants ou les configurations modifiées peuvent n'apparaître que lors d'une urgence réelle.

Comment l'éviter : Automatisez un test de restauration vers un registre de préproduction selon un calendrier. Comparez les catalogues et extrayez un ensemble d'images représentatives.

Piège 5 : Sauvegarder uniquement le répertoire de données, en oubliant la configuration

Si vous personnalisez la configuration du registre (par exemple, authentification, backends de stockage), ces paramètres ne se trouvent pas dans le répertoire de données. Les perdre signifie que votre registre restauré peut se comporter différemment.

Comment l'éviter : Stockez votre config.yml et vos fichiers compose dans un contrôle de version. Incluez-les dans l'archive de sauvegarde ou assurez-vous qu'ils sont récupérables depuis Git.

Piège 6 : Se fier à une seule copie de sauvegarde

Si la sauvegarde réside sur le même disque que le registre, une panne de disque détruit les deux. Si elle n'est que sur un seul lecteur externe, ce lecteur peut tomber en panne.

Comment l'éviter : Suivez la règle 3-2-1 : trois copies, deux supports différents, une hors site. Utilisez le stockage d'objets cloud pour les copies hors site.

Conclusion

La sauvegarde et la restauration d'un registre Docker sont une discipline essentielle qui protège votre chaîne d'approvisionnement logicielle. En comprenant votre environnement, en mettant en œuvre des sauvegardes en lecture seule, en vérifiant l'intégrité et en répétant la récupération, vous pouvez prévenir la perte de données et minimiser les temps d'arrêt.

Commencez par une action à faible risque : inspectez votre configuration actuelle du registre. Les données sont-elles sur un volume persistant ? Sinon, corrigez cela aujourd'hui. Ensuite, implémentez le script de sauvegarde de ce guide, testez une restauration et mettez en place une surveillance. Ces étapes vous font passer de la panique réactive à la résilience proactive.

Un flux de travail fiable rend les défaillances visibles, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Attribuez des responsables clairs, révisez la liste de contrôle mensuellement et gardez votre équipe préparée pour le jour où vous devrez utiliser cette sauvegarde.