Dépannage réseau en production avec Docker Compose : guide pratique

Introduction

Docker Compose simplifie le déploiement d'applications multi-conteneurs en définissant services, réseaux et volumes dans un seul fichier YAML. Cependant, lors du passage du développement à la production, des problèmes de réseau apparaissent souvent : les conteneurs ne peuvent pas communiquer entre eux, la résolution DNS échoue, les ports ne sont pas exposés correctement ou le trafic externe est bloqué par les pare-feu. Ces problèmes peuvent provoquer des interruptions de service et ralentir la réponse aux incidents.

Ce guide fournit des méthodes pratiques, étape par étape, pour diagnostiquer et résoudre les problèmes de réseau Docker Compose dans les environnements de production. Vous apprendrez à inspecter votre environnement Docker, à vérifier le DNS et la connectivité, à contrôler les règles de pare-feu et à appliquer des modifications de configuration en toute sécurité avec des options de retour arrière. Chaque section comprend des commandes concrètes et les sorties attendues pour que vous puissiez suivre et adapter à votre configuration.

À la fin de ce guide, vous disposerez d'un flux de travail de dépannage reproductible qui réduit les temps d'arrêt et renforce la confiance dans vos déploiements Docker Compose.

Inventaire des versions et de l'environnement

Avant de dépanner, recueillez des informations précises sur vos versions de Docker et Compose, la topologie du réseau et les conteneurs en cours d'exécution. Cette base de référence permet d'identifier les bogues spécifiques à une version et garantit l'application de correctifs compatibles.

Vérifiez les versions de Docker et Docker Compose

Exécutez les commandes suivantes pour voir les versions installées :

docker --version
docker compose version

Exemple de sortie :

Docker version 24.0.7, build afdd53b
Docker Compose version v2.21.0

Remarque : Docker Compose v2 est un plugin. Si vous utilisez l'ancien docker-compose autonome, la commande est docker-compose --version. Connaître la version exacte est crucial car le comportement réseau (en particulier le DNS) a changé entre les versions majeures.

Listez les conteneurs et les réseaux en cours d'exécution

Inspectez l'état actuel de votre déploiement :

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

Exemple :

NAMES  IMAGE        STATUS         PORTS
web    nginx:alpine Up 2 hours     0.0.0.0:80->80/tcp
app    myapp:latest Up 2 hours     8000/tcp
db     postgres:15  Up 2 hours     5432/tcp

NETWORK ID     NAME            DRIVER  SCOPE
abc123def456   bridge          bridge  local
ghi789jkl012   myapp_default   bridge  local

Le réseau myapp_default est généralement créé par Docker Compose pour votre projet. Notez quels conteneurs sont attachés à quels réseaux à l'aide de docker network inspect.

Vérifiez le fichier Docker Compose et l'environnement

Examinez votre docker-compose.yml ou docker-compose.yaml pour les définitions de réseaux et les dépendances de services. Vérifiez également les substitutions de variables d'environnement qui peuvent affecter les ports ou les paramètres réseau.

Extrait d'exemple :

services:
  app:
    build: .
    ports:
      - "${APP_PORT:-8000}:8000"
    environment:
      DB_HOST: db
    depends_on:
      - db
  db:
    image: postgres:15
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend
networks:
  backend:
    driver: bridge

Assurez-vous que la version du fichier Compose est compatible avec votre moteur Docker. Docker Compose v2 ignore la clé version, elle est donc facultative.

Prérequis pour le dépannage

• Accès shell à l'hôte Docker avec des autorisations suffisantes (généralement sudo ou appartenance au groupe docker).
• Compréhension de base des commandes réseau Linux (ip, ss, ping, curl, dig).
• Une sauvegarde récente de votre configuration Docker Compose et des volumes persistants (pour le retour arrière si nécessaire).
• Accès réseau à l'hôte et, le cas échéant, aux paramètres de pare-feu du fournisseur cloud.

Chemin de configuration sûr

Lorsque vous appliquez des modifications réseau en production, suivez une approche ciblée : apportez des modifications minimales et réversibles, et testez après chaque étape. Évitez les modifications globales qui affectent plusieurs services simultanément.

Comprendre les bases du réseau Docker Compose

Docker Compose crée un réseau par défaut pour chaque projet (nommé <projet>_default). Les conteneurs peuvent se joindre par nom de service (qui est également le nom du conteneur) grâce au DNS intégré. Pour un contrôle explicite, définissez des réseaux personnalisés.

Exemple de réseau personnalisé avec un sous-réseau :

networks:
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16

Évitez d'utiliser le réseau par défaut en production si vous avez besoin d'un contrôle de la plage IP ou de l'isolation réseau.

Vérifiez la résolution DNS à l'intérieur des conteneurs

Le serveur DNS intégré de Docker à l'adresse 127.0.0.11 résout les noms de conteneurs. Testez depuis l'intérieur d'un conteneur :

docker exec -it app nslookup db

Sortie attendue :

Server: 127.0.0.11
Address: 127.0.0.11#53

Name: db
Address: 172.28.0.3

Si le DNS échoue, vérifiez que les deux conteneurs sont sur le même réseau personnalisé. Les conteneurs sur des réseaux différents ne peuvent pas se résoudre par nom, sauf si vous utilisez un alias de réseau ou les connectez via un réseau externe.

Vérifiez la publication et la liaison des ports

La publication de ports mappe un port hôte vers un port conteneur. Utilisez docker port pour vérifier :

docker port <nom_conteneur>

Exemple :

80/tcp -> 0.0.0.0:80
80/tcp -> :::80

Cela montre que le port hôte 80 est transféré vers le port conteneur 80. Si vous devez modifier le port hôte, modifiez la section ports du fichier Compose et exécutez docker compose up -d pour recréer le conteneur.

Important : La modification des ports peut perturber les connexions existantes. Testez toujours le nouveau port avant de supprimer l'ancien. Vous pouvez exposer temporairement les deux ports :

ports:
  - "8080:80"
  - "80:80"

Migrez ensuite le trafic et supprimez l'ancien port.

Utilisez des variables d'environnement pour la configuration

Le codage en dur des adresses IP et des ports rend le dépannage plus difficile. Utilisez des variables d'environnement avec des valeurs par défaut sensées.

Dans le fichier Compose :

services:
  app:
    environment:
      DB_HOST: ${DB_HOST:-db}
      DB_PORT: ${DB_PORT:-5432}

Dans le fichier .env :

DB_HOST=db
DB_PORT=5432

Cela permet des modifications rapides sans éditer le fichier Compose et est plus sûr pour la production.

Évitez le mode réseau hôte

Sauf nécessité absolue, évitez network_mode: host car il contourne l'isolation réseau de Docker et peut provoquer des conflits de ports. Préférez les réseaux pont pour un meilleur contrôle et une meilleure sécurité.

Vérification et diagnostics

Après toute modification de configuration, vérifiez la connectivité et les performances. Cette section fournit des commandes et des sorties attendues pour confirmer que le réseau fonctionne correctement.

Testez la communication inter-conteneurs

Depuis l'intérieur d'un conteneur, utilisez ping (si disponible) ou curl pour joindre un autre service. De nombreuses images minimales n'ont pas ping ; utilisez wget ou une simple vérification TCP.

Exemple :

docker compose exec app sh -c "wget -qO- http://db:5432/ || echo 'Connexion échouée'"

Pour une vérification de port TCP sans outils supplémentaires, utilisez nc (netcat) s'il est présent, ou installez-le temporairement (non recommandé en production). À la place, utilisez docker run avec un conteneur temporaire sur le même réseau :

docker run --rm -it --network myapp_default alpine sh -c "apk add --no-cache busybox-extras && telnet db 5432"

Sortie attendue si la connexion réussit :

Connected to db

Si elle expire, vérifiez l'interface d'écoute du service. Par exemple, si une base de données est configurée pour écouter uniquement sur localhost à l'intérieur du conteneur, elle n'acceptera pas les connexions des autres conteneurs. La solution est de configurer le service pour écouter sur 0.0.0.0.

Diagnostiquez les problèmes DNS

Si les noms de service ne se résolvent pas, inspectez la configuration DNS à l'intérieur du conteneur :

docker exec -it app cat /etc/resolv.conf

Attendu :

nameserver 127.0.0.11
options ndots:0

Si cela montre un serveur de noms différent (comme 8.8.8.8), le DNS intégré de Docker n'est pas utilisé, peut-être parce que vous avez défini dns dans le fichier Compose ou que le conteneur utilise un réseau personnalisé avec DNS remplacé.

Vérifiez la connectivité réseau au DNS Docker :

docker exec -it app sh -c 'echo -e "GET / HTTP/1.0\r\n\r\n" | nc 127.0.0.11 53'

Ce n'est pas une requête DNS standard, mais cela vérifie que le port est joignable. Pour un vrai test, utilisez dig s'il est disponible :

docker exec -it app dig db @127.0.0.11

Vérifiez la connectivité externe

Pour tester l'accès Internet sortant depuis un conteneur :

docker exec -it app wget -qO- http://example.com

Si cela échoue, vérifiez le pare-feu de l'hôte et le transfert IP. Sous Linux, assurez-vous que le transfert IP est activé :

sysctl net.ipv4.ip_forward

Doit afficher net.ipv4.ip_forward = 1. Sinon, activez-le temporairement :

sudo sysctl -w net.ipv4.ip_forward=1

Pour le rendre permanent, ajoutez net.ipv4.ip_forward=1 à /etc/sysctl.conf ou à un fichier dans /etc/sysctl.d/.

Vérifiez les règles de pare-feu

Les pare-feu (basés sur l'hôte comme iptables, ou les groupes de sécurité cloud) bloquent souvent le trafic Docker. Docker manipule iptables automatiquement, mais les règles manuelles peuvent interférer.

Listez les règles iptables pour la chaîne DOCKER :

sudo iptables -L DOCKER -n -v

Extrait d'exemple :

Chain DOCKER (2 references)
 pkts bytes target prot opt in out source destination
 0 0 ACCEPT tcp -- !br-abc123def456 br-abc123def456 0.0.0.0/0 172.28.0.2 tcp dpt:5432

Cela montre que le trafic vers le conteneur de base de données sur le port 5432 est autorisé. Si aucune règle n'existe, Docker peut être incapable de router.

Pour les environnements cloud, vérifiez les groupes de sécurité ou les paramètres de pare-feu pour vous assurer que les ports requis (par exemple, 80, 443) sont ouverts depuis Internet ou des plages IP spécifiques.

Examinez la configuration du réseau Docker

Inspectez le réseau pour voir les conteneurs connectés et les adresses IP :

docker network inspect myapp_default

La sortie comprend une liste de conteneurs avec leurs adresses IPv4. Vérifiez que les IP sont dans le sous-réseau attendu et que chaque conteneur a une IP unique.

Surveillez les journaux pour les erreurs réseau

Les journaux des conteneurs révèlent souvent des problèmes de connexion :

docker logs --tail 50 app

Recherchez des erreurs comme "connection refused", "name resolution failed" ou "timeout". Ajustez le nombre de lignes en fonction du volume du journal.

Modes de défaillance et récupération

Même avec une planification minutieuse, des problèmes de réseau peuvent survenir. Cette section décrit les modes de défaillance courants, leur impact et comment récupérer en toute sécurité.

Modes de défaillance courants

• Échec de la résolution DNS
• Symptôme : Les journaux d'application montrent getaddrinfo ENOTFOUND db ou similaire.
• Cause : Conteneurs pas sur le même réseau, paramètres DNS personnalisés ou nom de service incorrect.
• Récupération : Assurez-vous que les deux conteneurs sont attachés au même réseau (ou à un réseau externe). Vérifiez les réseaux dans le fichier Compose. Si vous utilisez un DNS personnalisé, supprimez ou ajustez l'option dns.

• Conflit de liaison de port
• Symptôme : docker compose up échoue avec Bind for 0.0.0.0:80 failed: port is already allocated.
• Cause : Un autre processus sur l'hôte utilise le port 80, ou un conteneur précédent le détient encore.
• Récupération : Identifiez le processus avec sudo lsof -i :80 ou sudo ss -tulpn | grep :80. Arrêtez le processus en conflit ou modifiez le port hôte dans Compose.

• Le conteneur ne peut pas atteindre le réseau externe
• Symptôme : Les requêtes sortantes du conteneur expirent.
• Cause : Transfert IP désactivé, mauvaise configuration d'iptables ou démon Docker pas démarré correctement.
• Récupération : Activez le transfert IP comme montré précédemment. Redémarrez le démon Docker (sudo systemctl restart docker) après vous être assuré qu'aucun conteneur critique ne tourne (utilisez docker compose down d'abord si nécessaire).

• La communication inter-conteneurs fonctionne par IP mais pas par nom
• Symptôme : ping 172.28.0.3 fonctionne mais ping db échoue.
• Cause : Entrées /etc/hosts personnalisées dans le conteneur remplaçant le DNS Docker, ou network_mode mal défini.
• Récupération : Supprimez toute modification manuelle de /etc/hosts et assurez-vous que le conteneur est sur le réseau Docker. Utilisez docker exec pour vérifier /etc/hosts ; il doit contenir l'IP et le nom d'hôte du conteneur, mais pas d'entrées pour les autres services (le DNS Docker les gère).

• Pare-feu bloquant des ports spécifiques
• Symptôme : L'hôte peut atteindre le port du conteneur en interne, mais les clients externes ne le peuvent pas.
• Cause : Groupe de sécurité ou pare-feu hôte bloquant le port publié.
• Récupération : Mettez à jour le groupe de sécurité cloud pour autoriser l'entrée sur le port, ou ajoutez des règles iptables. Par exemple, pour autoriser le port 8080 :

    sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

Remarque : Cette règle n'est pas persistante ; utilisez l'outil de gestion de pare-feu de votre distribution (par exemple, ufw allow 8080/tcp).

Stratégies de retour arrière

Ayez toujours un plan de retour arrière avant d'apporter des modifications réseau.

• Conservez le fichier Compose précédent : Avant de modifier, copiez docker-compose.yml vers docker-compose.yml.bak. Si les modifications cassent le réseau, restaurez et exécutez docker compose up -d.
• Utilisez le contrôle de version : Stockez les fichiers Compose dans Git. Revenez en arrière via git checkout et redéployez.
• Pour les changements de port : Gardez l'ancien port mappé temporairement jusqu'à ce que le nouveau port soit confirmé fonctionnel. Exemple :

  ports:
    - "80:80"   # ancien
    - "8080:80" # nouveau

Une fois vérifié, supprimez l'ancien mappage et mettez à jour l'équilibreur de charge en conséquence.

• Pour la reconfiguration du réseau : Si vous devez modifier le sous-réseau, créez d'abord un nouveau réseau et déplacez progressivement les services. Docker peut exiger la recréation des conteneurs, prévoyez donc une brève interruption.

Vérification après récupération

Après avoir appliqué un correctif, vérifiez toujours :

• docker compose ps montre tous les services en marche et sains.
• La résolution DNS fonctionne : docker exec app nslookup db.
• Connectivité des ports : curl -I http://localhost:80 depuis l'hôte.
• Les journaux d'application ne montrent pas de nouvelles erreurs.

Pièges courants et comment les éviter

Même les opérateurs expérimentés rencontrent des écueils récurrents avec le réseau Docker Compose. Voici les pièges courants et comment les éviter.

Oublier d'attacher les services au même réseau personnalisé

Par défaut, Compose crée un réseau par projet, mais si vous définissez plusieurs réseaux et oubliez de lister un service sous networks, il peut rester sur le réseau par défaut. Les autres services ne peuvent alors pas le résoudre par nom. Définissez et attachez toujours explicitement les services aux réseaux prévus.

Remplacer le DNS de Docker involontairement

Définir dns ou dns_search dans le fichier Compose pour un service remplace le DNS intégré de Docker, cassant la résolution de noms interne. Ne remplacez le DNS que si vous avez besoin de serveurs DNS externes ; assurez-vous alors que les noms internes restent résolubles via extra_hosts ou des alias de réseau.

Utiliser network_mode: host par commodité

Le mode hôte contourne le réseau Docker, ce qui peut provoquer des conflits de ports et des problèmes de sécurité. Il rend également le conteneur dépendant de la pile réseau de l'hôte. Utilisez les réseaux pont à moins d'avoir une raison spécifique, comme le besoin d'un accès à faible latence aux services hôtes.

Ne pas vérifier le transfert IP

Sans transfert IP activé, les conteneurs ne peuvent pas atteindre le réseau externe même si le pare-feu est correct. De nombreuses distributions Linux minimales le désactivent par défaut. Vérifiez toujours sysctl net.ipv4.ip_forward après les mises à jour du noyau ou les redémarrages du système.

Ignorer les groupes de sécurité cloud

Les règles iptables de Docker contrôlent le trafic sur l'hôte, mais les fournisseurs cloud ajoutent une autre couche. Un port peut être publié correctement mais toujours bloqué par le groupe de sécurité. Vérifiez toujours les deux couches lorsque l'accès externe échoue.

Coder en dur les adresses IP

L'utilisation d'adresses IP fixes dans la configuration de l'application ou les fichiers Compose entraîne des pannes lorsque les conteneurs sont recréés avec de nouvelles IP. Fiez-vous aux noms de service DNS et utilisez des variables d'environnement pour toute dépendance externe.

Ne pas tester les procédures de retour arrière

Un plan de retour arrière n'est aussi bon que son dernier test. Simulez régulièrement un déploiement échoué et entraînez-vous à restaurer à partir de la sauvegarde. Cela garantit que votre équipe peut agir rapidement sous pression.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après toute modification réseau dans Docker Compose en production. Chaque élément a un responsable attitré et une fréquence de revue.

Conclusion

Le dépannage du réseau Docker Compose en production nécessite une approche systématique : comprendre votre environnement, appliquer des modifications sûres, vérifier avec des commandes concrètes et être prêt à revenir en arrière. En suivant les étapes de ce guide, vous pouvez rapidement identifier les mauvaises configurations DNS, les conflits de ports, les blocages de pare-feu et les problèmes de routage.

N'oubliez pas de garder vos fichiers Compose sous contrôle de version, d'utiliser des variables d'environnement pour la flexibilité et de tester les modifications dans un environnement de préproduction chaque fois que possible. Le premier pilote de tout changement réseau doit être étroit et mesurable, vous permettant d'inspecter les résultats localement avant de passer à l'échelle.

Utilisez la liste de contrôle des opérations comme pratique de routine avant et après les déploiements. Avec ces outils, vous pouvez minimiser les temps d'arrêt et maintenir des services de production Docker Compose fiables.

Prochaines étapes : Commencez par inventorier votre environnement Docker actuel. Exécutez les commandes de version et de réseau pour établir une base de référence. Ensuite, testez le DNS et la connectivité inter-conteneurs. Si des problèmes surviennent, appliquez les diagnostics dans l'ordre et ayez toujours un plan de retour arrière prêt.