Réseaux Docker Compose : noms de services, ports et isolation

Les réseaux Docker Compose permettent aux conteneurs de trouver et de contacter les services nécessaires. Pour comprendre une connexion qui échoue, commencez par trois questions : où s’exécute le client, quel réseau partage-t-il avec la destination et sur quel port celle-ci écoute-t-elle ?

Ce guide utilise un petit exemple avec un serveur web et un client. Il distingue ensuite l’appartenance aux réseaux, l’accès depuis l’hôte et la disponibilité de l’application, afin de diagnostiquer une panne sans publier des ports supplémentaires.

Comment fonctionne le réseau Compose par défaut ?

Compose crée normalement un réseau de projet et y connecte ses services. Les conteneurs de ce réseau peuvent résoudre les noms des services grâce au DNS Docker. Pour ces connexions, utilisez le nom du service et son port interne plutôt que son adresse IP actuelle. Le guide réseau de Compose explique ce fonctionnement.

Ce réseau de projet est distinct du réseau intégré à Docker Engine nommé bridge. Les ponts définis par l’utilisateur assurent la résolution des noms entre conteneurs ; le pont intégré a d’autres réglages par défaut. Ces réseaux fonctionnent sur un seul hôte Docker, comme l’indique la documentation du pilote bridge. Employer le même nom dans deux fichiers Compose ne relie pas deux serveurs.

Un petit exemple de réseau Docker Compose

Créez un répertoire distinct et enregistrez ce fichier sous le nom compose.yaml. Utilisez un moteur Docker local avec des conteneurs Linux, le plugin Compose et un port hôte 8088 disponible. Gardez cet exercice séparé des projets existants. Les images utilisent des tags lisibles ; en production, consignez les versions exactes ou les empreintes des images testées.

services:
  web:
    image: nginx:stable-alpine
    ports:
      - "127.0.0.1:8088:80"
  client:
    image: alpine:3.22
    command: ["sleep", "3600"]

Le service web exécute Nginx. Le service client reste disponible pendant une heure pour permettre une requête depuis son conteneur. Il ne publie aucun port, car il n’a pas besoin de recevoir des requêtes de l’hôte.

Depuis ce répertoire, validez le fichier, puis démarrez ce projet de test :

docker compose -p net-demo config --quiet
docker compose -p net-demo up -d

Nous avons validé la configuration avec Docker Compose v5.1.4. Le modèle résolu place les deux services sur net-demo_default et conserve la liaison à l’interface de bouclage, le port hôte 8088 et le port interne 80. Le moteur Docker était arrêté dans notre environnement : nous n’avons téléchargé aucune image, démarré aucun conteneur ni testé de connexion réelle. Les commandes d’exécution suivantes sont destinées à votre environnement de test.

docker compose config vérifie et affiche le modèle Compose. Une réussite ne prouve pas qu’une image peut être téléchargée, qu’un port hôte est libre ou qu’un service répond. Conservez cette distinction lors de la préparation du déploiement.

Choisir l’adresse selon l’emplacement du client

Client	Adresse dans cet exemple	Raison
Le conteneur client	http://web:80	Utilise le nom du service et le port du conteneur web.
Un navigateur sur l’hôte Docker	http://127.0.0.1:8088	Utilise le port publié sur l’hôte.
Une autre machine	Aucun accès distant prévu	La publication cible explicitement l’interface de bouclage de l’hôte.

Avec des espaces réseau de conteneurs séparés, localhost désigne le conteneur qui émet la requête. Une requête du client vers localhost:80 vise donc le client lui-même, pas le serveur web. De même, web:8088 confond le port publié sur l’hôte et le port d’écoute du serveur.

Pour joindre un service de l’hôte, Docker Desktop fournit host.docker.internal. Suivez ses instructions de connexion à l’hôte ; ne supposez pas que ce nom existe automatiquement sur toute installation native de Docker Engine sous Linux. Avec un contexte Docker distant, l’hôte Docker n’est pas nécessairement l’ordinateur qui exécute la CLI.

Vérifier la connexion et la publication du port

Lorsque les deux conteneurs sont démarrés, utilisez ces commandes :

docker compose -p net-demo exec -T client wget -qO- http://web:80
docker compose -p net-demo port web 80
docker compose -p net-demo logs web
docker network inspect net-demo_default

La première exécute wget dans le conteneur client ; une requête réussie devrait renvoyer le HTML de la page Nginx. La commande port devrait afficher la publication correspondant au port interne 80. Les journaux et l’inspection réseau apportent des preuves distinctes sur le serveur et les conteneurs connectés. La référence Compose exec décrit l’exécution de commandes dans un service.

En cas d’échec, conservez l’erreur exacte et vérifiez une couche à la fois :

1. Confirmez le contexte Docker et le projet, puis vérifiez que les deux conteneurs fonctionnent.
2. Inspectez leur appartenance aux réseaux et le nom utilisé par le client.
3. Vérifiez le processus destinataire, son adresse d’écoute et son port.
4. Testez le protocole de l’application depuis l’emplacement du client.
5. Examinez séparément l’accès depuis l’hôte et l’accès entre conteneurs.

Une erreur de résolution de nom, une connexion refusée, un délai dépassé et une réponse HTTP d’erreur donnent des indices différents. Une réponse HTTP établit qu’un serveur a répondu, sans garantir un résultat applicatif réussi. Notez l’URL en échec et l’emplacement du test avant de modifier le réseau.

Employer ports et expose à bon escient

ports publie un port de conteneur via l’hôte. Sans adresse IP hôte précisée, Docker publie normalement sur toutes ses adresses. Cet exemple utilise 127.0.0.1 pour un test local. Docker documente un problème d’exposition des ports publiés sur localhost dans les versions d’Engine antérieures à 28.0.0. Utilisez un moteur maintenu et corrigé, puis vérifiez l’accès prévu. Consultez la documentation sur la publication des ports.

expose ne publie pas de port sur l’hôte et ne remplace pas le processus d’écoute. Ce n’est pas non plus une liste de contrôle bloquant tous les autres ports d’un réseau bridge partagé. La référence des services Compose précise sa syntaxe. Ajoutez une séparation réseau et une authentification lorsque nécessaire.

Pour un déploiement réel, déterminez le point d’entrée qui demande un accès distant et configurez-le explicitement. Ne publiez pas le port d’une base de données pour corriger une faute dans un nom de service. Notre guide Docker sur une VM Compute, en anglais, traite de l’installation sur l’hôte et de l’exposition des ports.

Séparer les réseaux front et back

Cette configuration autonome illustre une topologie. Ses trois conteneurs Alpine restent simplement en attente ; leurs noms représentent des rôles prévus, pas des logiciels de proxy, d’application ou de base de données opérationnels.

services:
  proxy:
    image: alpine:3.22
    command: ["sleep", "3600"]
    networks: [front]
  app:
    image: alpine:3.22
    command: ["sleep", "3600"]
    networks: [front, back]
  store:
    image: alpine:3.22
    command: ["sleep", "3600"]
    networks: [back]
networks:
  front: {}
  back:
    internal: true

Notre contrôle confirme que proxy rejoint front, store rejoint back et app rejoint les deux. Seul back porte internal: true. Ce réglage crée un réseau isolé de l’extérieur ; un service également relié à un réseau ordinaire peut conserver un accès externe. Consultez les attributs réseau de Compose pour adapter le fichier.

Dessinez les communications nécessaires avant de choisir les appartenances. Un processus connecté aux deux côtés mérite une attention particulière, puisqu’il peut communiquer avec chacun. Cette disposition ne remplace ni les identifiants, ni les autorisations, ni l’examen des données que l’application transmet. Testez les chemins autorisés et interdits dans l’environnement de déploiement.

Partager un réseau existant entre projets

Utilisez un réseau externe lorsque son cycle de vie est géré hors du projet Compose courant. Il doit déjà exister sur le même démon Docker. Dans cet exemple distinct, son nom exact est team-demo-network :

services:
  client:
    image: alpine:3.22
    command: ["sleep", "3600"]
    networks: [shared]
networks:
  shared:
    external: true
    name: team-demo-network

Notre contrôle du modèle résolu conserve ce nom explicite sans préfixe de projet. Définissez le responsable, les services participants et les noms avant de connecter un autre projet. Considérez cette appartenance comme une extension délibérée des communications possibles. Ce fichier ne crée pas le réseau et ne prouve pas qu’un autre projet y est connecté.

Distinguer disponibilité applicative et réseau

Découvrir un conteneur ne prouve pas que son application est prête. La forme courte de depends_on fixe l’ordre de démarrage ; une dépendance avec condition: service_healthy peut attendre un contrôle de santé configuré. Suivez la documentation sur l’ordre de démarrage et prévoyez les nouvelles tentatives adaptées aux pannes ultérieures.

Évitez aussi network_mode: host comme correction générale d’une panne de connexion. Ce mode change l’isolation et rend les publications ordinaires de ports inapplicables. La documentation du pilote host précise les plateformes prises en charge. Notre contrôle confirme également que l’association de network_mode et networks est rejetée.

Terminer l’exercice et conserver les résultats

À la fin du premier exemple, exécutez cette commande depuis son répertoire pour arrêter et supprimer les conteneurs et le réseau par défaut de ce projet :

docker compose -p net-demo down

La référence Compose down précise les suppressions effectuées ; les réseaux externes sont conservés. N’appliquez pas ces commandes de nettoyage à un autre projet.

Conservez ensemble le fichier Compose, les versions des outils, les adresses source et destination et les réponses observées. Notre guide de l’environnement de développement propose des vérifications plus larges. Ici, huit contrôles de configuration ont réussi : appartenances réseau, ports, réseaux internes et externes, et deux configurations invalides. Le DNS, les connexions, l’isolation et la disponibilité applicative restent à tester en exécution réelle.