Éviter les erreurs de volumes nommés Docker : configuration pratique, validation et récupération

Introduction

Les volumes nommés Docker mal configurés sont l'une des principales causes de perte de données et d'indisponibilité de service dans les applications conteneurisées. Les erreurs sont souvent subtiles : un volume attaché au mauvais chemin, une sauvegarde manquante, ou un conteneur qui écrit dans sa couche éphémère au lieu du volume prévu. Lorsque vous vous en apercevez, vos données ont peut-être déjà disparu.

Ce guide passe en revue les erreurs de configuration les plus courantes concernant les volumes nommés Docker et vous montre comment les prévenir et vous en remettre. Vous apprendrez à :

• Distinguer volumes nommés, montages de type bind et volumes anonymes.
• Vérifier que vos données persistent réellement là où vous le pensez.
• Récupérer après une mauvaise configuration sans perdre de données.
• Mettre en place une liste de contrôle opérationnelle sûre pour la production.

Nous nous concentrons sur des commandes pratiques, des scénarios réels et des signaux concrets qui indiquent un problème. Que vous soyez développeur, ingénieur DevOps ou fondateur technique, ce guide vous aidera à éviter des incidents douloureux de perte de données.

Inventaire de la version et de l'environnement

Avant de changer quoi que ce soit, connaissez votre environnement. Exécutez ces commandes en lecture seule pour capturer l'état actuel :

docker version --format '{{.Server.Version}}'
docker compose version

Notez les versions de Docker Engine et de Compose, car le comportement des volumes peut varier d'une version à l'autre. Par exemple, Docker 25 a introduit des changements dans les sous-commandes de volume, et Compose v2 gère les noms différemment de la v1.

Ensuite, listez les conteneurs en cours d'exécution et leurs points de montage :

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
docker inspect $(docker ps -q) --format '{{.Name}} -> {{range .Mounts}}{{.Type}}:{{.Name}}:{{.Destination}}{{end}}'

Un résultat typique ressemble à :

/myapp -> volume:myapp_data:/var/lib/app

Cela vous indique que le conteneur /myapp possède un volume nommé myapp_data monté sur /var/lib/app.

Vérifiez le volume réel sur le disque :

docker volume ls
DRIVER    VOLUME NAME
local     myapp_data

Si vous voyez un volume anonyme (un long nom hexadécimal) au lieu d'un volume nommé, c'est un signe d'avertissement. Les volumes anonymes ne sont pas réutilisés par défaut et peuvent s'accumuler, rendant le nettoyage et la sauvegarde difficiles.

Identifiez votre chemin de données : volume nommé vs montage bind

Un volume nommé est géré par Docker et stocké sous /var/lib/docker/volumes/ sur Linux. Il est portable lors de la reconstruction des conteneurs et peut être sauvegardé avec des commandes Docker. Exemple de snippet Compose :

services:
  app:
    image: myapp:1.0
    volumes:
      - app_data:/var/lib/app
volumes:
  app_data:

Un montage bind mappe directement un répertoire de l'hôte. Il est utile en développement mais moins portable :

volumes:
  - ./data:/var/lib/app

Pour voir où se trouve réellement votre volume, inspectez-le :

docker volume inspect myapp_data
[
  {
    "CreatedAt": "2025-02-01T10:00:00Z",
    "Driver": "local",
    "Labels": {},
    "Mountpoint": "/var/lib/docker/volumes/myapp_data/_data",
    "Name": "myapp_data",
    "Options": {},
    "Scope": "local"
  }
]

Si vous vous attendez à un montage bind mais voyez un volume, ou vice versa, vos données risquent d'aller au mauvais endroit.

Effectuez un test de redémarrage tôt

Arrêtez et recréez un conteneur pour vérifier que les données persistent :

docker stop myapp
docker rm myapp
docker run -d --name myapp -v app_data:/var/lib/app myapp:1.0

Vérifiez ensuite les données :

docker exec myapp ls /var/lib/app

Si le répertoire est vide ou manquant, le conteneur d'origine écrivait dans sa couche inscriptible, pas dans le volume. Détectez cela avant la production.

Chemin de configuration sûr

L'approche la plus sûre consiste à effectuer un petit changement à la fois et à le vérifier. Suivez ce modèle :

1. Sauvegardez les données existantes, même si vous pensez qu'un changement est sans danger.
2. Appliquez le changement d'abord dans un environnement de test.
3. Exécutez des commandes de vérification pour confirmer le résultat.
4. Revenez en arrière immédiatement si la vérification échoue.

Exemple : Ajouter un volume nommé à un service en cours d'exécution

Supposons que vous ayez un conteneur WordPress démarré sans volume, de sorte que tous les fichiers de base de données se trouvent à l'intérieur du conteneur. Vous souhaitez les déplacer dans un volume nommé. Voici une séquence sûre :

Étape 1 : Sauvegardez les données du conteneur

docker exec wordpress_db tar czf - /var/lib/mysql > db-backup.tar.gz

Étape 2 : Créez un volume nommé

docker volume create wordpress_db_data

Étape 3 : Arrêtez le conteneur et copiez les données dans le volume

docker stop wordpress_db
docker run --rm -v wordpress_db_data:/data -v $(pwd):/backup alpine \
  sh -c "cd /data && tar xzf /backup/db-backup.tar.gz --strip-components=2"

Étape 4 : Recréez le conteneur avec le volume attaché

docker run -d --name wordpress_db -v wordpress_db_data:/var/lib/mysql mysql:8

Étape 5 : Vérifiez que les données sont présentes et que le service fonctionne

docker exec wordpress_db ls /var/lib/mysql
docker logs wordpress_db --tail 20

Si les journaux montrent un démarrage propre et que les données sont listées, la migration a réussi. Sinon, vous avez toujours la sauvegarde et pouvez revenir à l'ancien conteneur.

Utilisez Compose pour la reproductibilité

Dans la mesure du possible, définissez les volumes dans un fichier docker-compose.yml. Cela rend la configuration explicite et reproductible :

version: '3.8'
services:
  db:
    image: postgres:16
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

Compose crée automatiquement le volume nommé db_data au premier up et le réutilise lors des exécutions suivantes. Pour appliquer un changement lié au volume, exécutez docker compose up -d après avoir modifié le fichier, puis vérifiez avec docker compose ps et docker compose logs.

Vérification et diagnostic

Après tout changement de configuration, vous devez vérifier que les données persistent et que l'application se comporte comme prévu.

Vérifiez les points de montage et le type de volume

Utilisez docker inspect pour confirmer le type de montage et le nom :

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

Exemple de sortie :

[{"Type":"volume","Name":"app_data","Source":"/var/lib/docker/volumes/app_data/_data","Destination":"/var/lib/app","Driver":"local","Mode":"z","RW":true,"Propagation":""}]

Si Type est volume et Name est celui attendu, le volume nommé est correctement attaché.

Vérifiez que les données sont écrites dans le volume

Écrivez un fichier de test à l'intérieur du conteneur, puis vérifiez-le depuis l'hôte :

docker exec myapp sh -c 'echo "test" > /var/lib/app/test.txt'
ls -l /var/lib/docker/volumes/app_data/_data/test.txt

Si le fichier apparaît sur le chemin de l'hôte, le conteneur écrit dans le volume. Sinon, le conteneur écrit dans sa propre couche.

Exécutez un test de redémarrage et de survie des données

docker restart myapp
docker exec myapp cat /var/lib/app/test.txt

Le contenu de test doit toujours être présent. Ensuite, pour simuler entièrement une recréation du conteneur :

docker stop myapp
docker rm myapp
docker run -d --name myapp -v app_data:/var/lib/app myapp:1.0
docker exec myapp cat /var/lib/app/test.txt

Si le fichier persiste, le volume fait son travail.

Diagnostiquer la « disparition des données après mise à jour »

Un scénario courant : vous mettez à jour votre image d'application, exécutez docker compose up -d, et soudainement les données semblent manquantes. Souvent, le nouveau conteneur utilise un volume ou un point de montage différent.

Vérifiez si l'ancien volume existe toujours :

docker volume ls

Si vous voyez un volume avec un ancien préfixe de projet, Compose peut avoir créé un nouveau volume parce que le nom du projet a changé (par exemple, en raison d'un renommage de répertoire ou du drapeau -p). Pour corriger, vous pouvez soit renommer le volume, soit pointer explicitement le nouveau conteneur vers l'ancien volume :

volumes:
  db_data:
    external: true
    name: oldproject_db_data

Exécutez ensuite docker compose up -d et vérifiez.

Modes de défaillance et récupération

Cette section détaille les erreurs de configuration courantes des volumes nommés, pourquoi elles se produisent et comment les récupérer.

Erreur 1 : Le conteneur écrit dans la couche éphémère au lieu du volume

Pourquoi cela arrive : Le développeur a oublié de monter un volume, ou l'instruction VOLUME dans le Dockerfile a créé un volume anonyme mais l'application écrit vers un chemin différent.

Comment détecter : Les données disparaissent après la recréation du conteneur. De plus, docker inspect montre un montage à un chemin différent de celui attendu.

Comment récupérer :

1. Arrêtez le conteneur en préservant la couche inscriptible :

docker stop myapp

1. Commitez le conteneur dans une image temporaire (cela capture tous les changements du système de fichiers) :

docker commit myapp myapp-temp

1. Créez un volume nommé et copiez les données depuis l'image commitée :

docker volume create app_data
docker run --rm -v app_data:/data myapp-temp sh -c "cp -a /var/lib/app/. /data/"

1. Recréez le conteneur avec le volume correctement monté.

Comment éviter : Définissez toujours les volumes dans Compose ou docker run. Utilisez un test de redémarrage avant de vous fier au conteneur.

Erreur 2 : Utiliser un montage bind sans répertoire hôte persistant

Pourquoi cela arrive : Un développeur utilise un montage bind relatif comme ./data mais le répertoire n'existe pas sur l'hôte de production, donc Docker crée un répertoire vide appartenant à root. L'application échoue alors avec des erreurs de permission ou écrit vers un chemin différent.

Comment détecter : Les journaux d'application montrent des erreurs de permission refusée, ou les changements de données ne sont pas reflétés sur l'hôte.

Comment récupérer :

1. Arrêtez le conteneur.
2. Créez le répertoire hôte avec la propriété correcte.
3. Redémarrez le conteneur et vérifiez que l'application peut écrire.

Comment éviter : Pré-créez le répertoire hôte et définissez les permissions, ou mieux, utilisez un volume nommé pour la production. Si un montage bind est requis, utilisez un chemin absolu et assurez-vous qu'il existe dans votre automatisation de déploiement.

Erreur 3 : Supprimer un volume prématurément

Pourquoi cela arrive : Lors du nettoyage, quelqu'un exécute docker volume prune ou docker volume rm app_data alors que le volume est encore utilisé, ou parce qu'il pense qu'il n'est plus nécessaire.

Comment détecter : Les applications plantent avec des données manquantes, ou les données sont perdues définitivement.

Comment récupérer : Si le volume a été récemment supprimé, vous pourriez être en mesure de le restaurer à partir d'une sauvegarde. Docker ne conserve pas les volumes supprimés à moins que vous n'ayez des instantanés. Si vous avez un instantané du système de fichiers de /var/lib/docker/volumes, vous pouvez restaurer le répertoire. Sinon, restaurez à partir de votre sauvegarde.

Comment éviter : Ne supprimez jamais un volume sans sauvegarde. Utilisez docker volume ls et docker ps -a --filter volume=app_data pour voir quels conteneurs le référencent. Mettez en place un calendrier de sauvegarde.

Erreur 4 : Mauvais nom de volume ou préfixe de projet dans Compose

Pourquoi cela arrive : Vous renommez le répertoire du projet ou changez le champ name dans Compose, ce qui modifie le préfixe du nom du volume. Compose crée alors un nouveau volume, laissant les anciennes données derrière.

Comment détecter : Après docker compose up -d, l'application montre un état vide, et docker volume ls montre deux volumes : un avec l'ancien préfixe et un avec le nouveau.

Comment récupérer : Soit renommez l'ancien volume pour correspondre au nouveau nom attendu, soit définissez external: true avec l'ancien nom. Par exemple, pour renommer :

docker volume create --name newproject_db_data
docker run --rm -v oldproject_db_data:/from -v newproject_db_data:/to alpine cp -a /from/. /to/
docker volume rm oldproject_db_data

Comment éviter : Définissez un nom de projet fixe dans Compose en utilisant name: au niveau supérieur, ou utilisez la variable d'environnement COMPOSE_PROJECT_NAME. Évitez de renommer les répertoires qui contiennent des projets Compose.

Erreur 5 : Ignorer les permissions des volumes

Pourquoi cela arrive : Le conteneur s'exécute en tant qu'utilisateur non root, mais le volume est initialisé avec la propriété root, donc l'application ne peut pas écrire dans le volume.

Comment détecter : Les journaux d'application montrent « Permission denied » lors des tentatives d'écriture.

Comment récupérer : Corrigez les permissions en exécutant un conteneur temporaire en tant que root :

docker run --rm -v app_data:/data alpine chown -R 1000:1000 /data

Redémarrez ensuite votre conteneur d'application.

Comment éviter : Dans votre Dockerfile, définissez l'instruction USER avec le bon UID et assurez-vous que le point de montage du volume a la propriété correspondante. Envisagez d'utiliser un conteneur d'initialisation ou un script d'entrée pour ajuster les permissions au démarrage.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après tout changement impliquant des volumes nommés. Attribuez un responsable et une fréquence de révision à chaque élément.

Liste de contrôle avant changement

Avant d'effectuer un changement, vérifiez :

• [ ] La sauvegarde existe : Vous disposez d'une sauvegarde récente des données du volume. Responsable : Responsable des opérations, vérifié chaque semaine.
• [ ] Le nom et le chemin du volume sont connus : Exécutez docker inspect <conteneur> et confirmez le montage. Responsable : Ingénieur DevOps.
• [ ] Le changement est testé en environnement de test : Vous avez appliqué le changement à un environnement de test et exécuté le test de redémarrage. Responsable : Responsable QA.
• [ ] Le plan de retour en arrière est prêt : Vous avez un script ou des étapes documentées pour annuler le changement. Responsable : Ingénieur d'astreinte.
• [ ] Accès au système de fichiers de l'hôte (si montage bind) : Le répertoire hôte existe et a les permissions correctes. Responsable : Administrateur système.

Vérification après changement

Après le changement, exécutez ces vérifications :

• [ ] Le conteneur fonctionne : docker ps montre le conteneur actif.
• [ ] Le montage est correct : docker inspect montre le type et le nom de volume attendus.
• [ ] Les données sont accessibles : docker exec <conteneur> ls <point de montage> renvoie des fichiers.
• [ ] Santé de l'application : Les journaux ne montrent aucune erreur et le contrôle de santé (s'il existe) réussit.
• [ ] Test d'écriture : Écrivez un fichier d'exemple à l'intérieur du conteneur et confirmez qu'il apparaît sur l'hôte.
• [ ] Test de redémarrage : Redémarrez le conteneur et confirmez que les données persistent.

Ces vérifications doivent être effectuées par l'ingénieur responsable du changement, et revues par un ingénieur senior ou un chef d'équipe avant que le changement soit marqué comme terminé.

Conclusion

Les volumes nommés Docker sont puissants, mais ils exigent une configuration et une vérification délibérées. Les erreurs les plus courantes proviennent de modèles mentaux flous sur le fonctionnement du stockage Docker et de changements précipités sans test.

Pour opérer en toute sécurité :

• Sachez toujours si vos données se trouvent dans un volume nommé, un montage bind ou la couche du conteneur.
• Vérifiez la persistance avec des tests de redémarrage avant de vous fier à un conteneur.
• Sauvegardez les volumes régulièrement et avant d'effectuer des changements.
• Utilisez Compose pour rendre les déclarations de volume explicites et reproductibles.
• Testez les changements en environnement de test et ayez un plan de retour en arrière.

En suivant les étapes pratiques de ce guide, vous pouvez éviter les erreurs de configuration de volume les plus dommageables et récupérer rapidement en cas de problème. N'oubliez pas : le moment de tester vos sauvegardes et procédures de récupération est avant d'en avoir besoin.

Pour votre prochaine étape, choisissez un conteneur en cours d'exécution et exécutez les commandes de vérification de cet article. Confirmez que ses données se trouvent sur un volume nommé et survivent à un redémarrage. Documentez ensuite vos conclusions et mettez en place un calendrier de sauvegarde si vous n'en avez pas déjà un.