## 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.

```bash
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 :

```bash
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 :

```bash
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 :

```bash
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é.

```bash
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.

```yaml
# 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 :

```yaml
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.

```bash
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.

## 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 :

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

Une configuration minimale ressemble à ceci :

```yaml
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 :

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

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

```yaml
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 :

```yaml
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 :

```yaml
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 :

```bash
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 :

```bash
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 :

```yaml
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 :

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

Exemple de sortie :

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

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

```bash
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.

```bash
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` :

```bash
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** :

```bash
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 :

```bash
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é :

```bash
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** :

```bash
docker logs registry | grep -i permission
```

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

```bash
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 :

```bash
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.

```bash
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 :

```bash
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.

## 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 :
  ```bash
  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.