Réseaux Docker avec bridge, host et overlay : guide pratique

Introduction

Docker networking décide comment vos services se découvrent entre eux et comment les clients y accèdent. Dans ce guide, vous allez :

Comprendre les réseaux bridge, host et overlay
Publier des ports en sécurité pour que le trafic atteigne le bon conteneur
Utiliser le Docker DNS entre conteneurs pour parler par nom
Définir des réseaux avec Docker Compose pour des déploiements reproductibles
Dépanner rapidement une connectivité défaillante

Ce guide s'adresse aux opérateurs pressés qui veulent des étapes concrètes et des exemples à copier-coller qui fonctionnent sur de vraies machines.

Vue d'ensemble du workflow

Suivez cette séquence pour choisir et mettre en place le bon mode réseau :

Clarifier le périmètre

Hôte unique : commencez par un user-defined bridge network. Il isole les conteneurs et fournit un Docker DNS intégré entre eux.
Besoin de performances proches du bare-metal sur Linux : envisagez host network. Il supprime le NAT mais expose directement les ports des conteneurs sur la pile réseau de l'hôte.
Multi-hôte : utilisez un overlay network avec Swarm pour relier des services entre nœuds.

Créer le réseau

Bridge (user-defined) : docker network create app-net
Host : pas d'étape de création ; on attache avec --network host
Overlay : docker swarm init puis docker network create -d overlay --attachable app-ol

Lancer les services sur le réseau choisi

Bridge : attacher avec --network app-net ou via les réseaux Compose
Host : lancer avec --network host ; s'assurer que l'app écoute sur 0.0.0.0
Overlay : utiliser des services (docker service ...) ou un stack file (docker stack deploy)

Ne publier que l'indispensable

Bridge/overlay : publier les ports hôte avec -p ou ports: de Compose
Host network : ne pas utiliser -p ; le conteneur utilise directement la pile de l'hôte

Vérifier et documenter

Depuis un conteneur : résoudre un pair par nom (curl http://api:8080)
Depuis l'hôte : tester les ports publiés (curl http://localhost:8080)
Noter les ports et réseaux choisis pour les réutiliser

Bridge networking en pratique (par défaut local)

Un user-defined bridge network isole le trafic et active la résolution DNS entre services par défaut. Préférez-le au pont « bridge » hérité.

Créer un réseau :

docker network create app-net

Lancer une base de données et une API sur le même réseau :

# PostgreSQL
docker run -d \
  --name db \
  --network app-net \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

# API simple écoutant sur 8080 et utilisant DATABASE_HOST=db
docker run -d \
  --name api \
  --network app-net \
  -e DATABASE_HOST=db \
  -p 8080:8080 \
  myorg/api: latest

Ce que vous obtenez :

DNS entre conteneurs : « db » se résout à l'intérieur du réseau ; l'API se connecte à db:5432.
Accès depuis l'hôte : vos tests ou clients atteignent http://localhost:8080 grâce à -p 8080:8080.
Isolation : les autres réseaux ne peuvent pas joindre ces conteneurs par nom.

Vérifier le DNS depuis un conteneur :

docker exec -it api sh -lc 'ping -c1 db || true'; \
  docker exec -it api sh -lc 'getent hosts db || true'

Exemple minimal de Dockerfile d'API

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY app.py .
RUN pip install --no-cache-dir flask psycopg2-binary
ENV PORT=8080
CMD ["python", "app.py"]

Exemple d'app.py (très court) :

from flask import Flask
import os
app = Flask(__name__)
@app.get("/")
def hello():
    return {"ok": True, "port": os.getenv("PORT", "8080")}
app.run(host="0.0.0.0", port=int(os.getenv("PORT", "8080")))

Construire et exécuter :

docker build -t myorg/api: latest .

Bases de la publication de ports

Syntaxe : -p hostPort: containerPort[/protocol]
Publier expose un port du conteneur sur l'hôte. À l'intérieur du réseau Docker, les autres conteneurs se connectent toujours au port du conteneur, pas au port hôte.
En host network : n'utilisez pas -p. Votre application doit écouter sur 0.0.0.0 et le port doit être libre sur l'hôte.
Vous pouvez exécuter plusieurs conteneurs écoutant sur le même port interne en publiant des ports hôte différents (ex. -p 8081:8080 et -p 8082:8080).

Vérifier les ports publiés :

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

DNS entre conteneurs

Sur les user-defined bridge et overlay networks, Docker fournit un résolveur DNS embarqué. Les conteneurs se résolvent par nom :

Hôte unique : utilisez le nom de conteneur sur le même user-defined bridge (ex. http://api:8080).
Compose : utilisez le nom de service (ex. http://web:80).

Dans un conteneur, /etc/resolv.conf pointe généralement vers 127.0.0.11, le serveur Docker DNS du réseau.

Réseaux Docker Compose (recommandé pour les stacks)

Docker Compose crée automatiquement un réseau dédié à votre projet et attribue à chaque service un nom DNS égal à sa clé. C'est le schéma local le plus reproductible.

compose.yaml :

version: "3.9"
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    networks: [app-net]

  api:
    build: .
    environment:
      DATABASE_HOST: db
    ports:
      - "8080:8080"
    depends_on: [db]
    networks: [app-net]

  web:
    image: nginx: alpine
    ports:
      - "8081:80"
    networks: [app-net]

networks:
  app-net:
    driver: bridge

Utilisation :

docker compose up -d
# Test service-à-service
docker compose exec web sh -lc 'wget -qO- http://api:8080 || curl -s http://api:8080'
# Test depuis l'hôte
curl -s http://localhost:8081

Host networking (Linux uniquement dans la plupart des cas)

Le host networking place le conteneur sur la pile réseau de l'hôte. Avantages : pas de NAT, overhead réduit, arrivée plus simple du trafic entrant. Inconvénients : isolement moindre, conflits de ports, et généralement limité à Linux.

Exemple :

# Assurez-vous que votre app écoute sur 0.0.0.0:8080
docker run -d --name fastapi --network host myorg/api: latest
# L'app est joignable sur l'hôte au port :8080 sans -p

N'envisagez le mode host que si vous en avez réellement besoin et que vous comprenez les compromis de sécurité et d'exploitation.

Overlay networking (multi-hôte avec Swarm)

Les réseaux overlay relient des services sur plusieurs hôtes Docker. Swarm doit être activé.

Initialiser Swarm et créer un overlay attachable :

docker swarm init
# Créer un réseau overlay utilisable par services et conteneurs autonomes
docker network create -d overlay --attachable app-ol

Déployer des services avec des ports publiés :

# Service API
docker service create \
  --name api \
  --network app-ol \
  -p 8080:8080 \
  myorg/api: latest

# Service Web
docker service create \
  --name web \
  --network app-ol \
  -p 80:80 \
  nginx: alpine

Ou utiliser un stack file (stack.yaml) :

version: "3.9"
services:
  api:
    image: myorg/api: latest
    ports: ["8080:8080"]
    networks: [app-ol]
  web:
    image: nginx: alpine
    ports: ["80:80"]
    networks: [app-ol]
networks:
  app-ol:
    driver: overlay

Déployer la stack :

docker stack deploy -c stack.yaml mystack

Vérifier :

docker service ls
curl -s http://<any-node-ip>:80

Dépannage d'une connectivité cassée

Utilisez cette checklist pour isoler vite les causes courantes.

Les conteneurs sont-ils sur le même réseau ?

docker network inspect app-net --format '{{json .Containers}}' | jq '.'

S'il manque un pair, connectez-le :

docker network connect app-net api

Le port est-il bien publié sur l'hôte ?

docker ps --format 'table {{.Names}}\t{{.Ports}}'
# Cherchez 0.0.0.0:8080->8080/tcp (ou votre IP/port)

Sinon, ajoutez -p ou ports: dans Compose.

L'app écoute-t-elle sur 0.0.0.0 dans le conteneur ?

# Remplacez par un outil disponible dans votre image
docker exec -it api sh -lc 'ss -tln || netstat -tln'

Si elle n'écoute que sur 127.0.0.1, mettez-la à l'écoute sur 0.0.0.0.

Les conteneurs se résolvent-ils par nom ?

docker exec -it api sh -lc 'getent hosts db || ping -c1 db || nslookup db || true'

En cas d'échec, utilisez un user-defined bridge ou overlay et assurez-vous que les deux conteneurs partagent le même réseau.

Pare-feu hôte bloquant ?

Autorisez l'entrée sur les ports publiés (ex. 80, 8080). Ajustez vos règles si nécessaire.

Conflits de ports sur l'hôte ?

# Sur Linux
ss -tulpn | grep :8080 || netstat -tulpn | grep :8080

Si un processus occupe déjà le port, choisissez-en un autre ou stoppez le service en conflit.

Vérifications spécifiques overlay

docker info | grep -i swarm
# Doit afficher : Swarm: active

docker service ps api

Si des tâches échouent, inspectez les logs et la disponibilité des nœuds. Assurez-vous que tous les services rejoignent le même overlay.

Si vous utilisez le pont hérité « bridge », basculez vers un user-defined bridge pour un meilleur DNS et une meilleure isolation :

Pièges du pont « bridge » par défaut

docker network create app-net
# Recréez les conteneurs avec --network app-net

En cas de doute, supprimez et recréez avec réseaux et ports explicites :

Nettoyer et recréer

docker rm -f api db web || true
docker network rm app-net || true

Puis relancez les commandes validées ou Compose.

Plan pilote local

Gardez un premier pilote petit, mesurable et facile à inspecter en local.

Objectif

Une stack de 3 services (db, api, web) sur un user-defined bridge avec DNS opérationnel et ports publiés.
Indicateur de succès : curl renvoie le JSON attendu et la page d'accueil Nginx en moins de 200 ms en localhost.

Étapes

Builder l'image API et créer le réseau

docker build -t myorg/api: latest .
docker network create app-net

Démarrer les services

docker run -d --name db --network app-net -e POSTGRES_PASSWORD=secret postgres:16
docker run -d --name api --network app-net -e DATABASE_HOST=db -p 8080:8080 myorg/api: latest
docker run -d --name web --network app-net -p 8081:80 nginx: alpine

Vérifier

# DNS entre conteneurs
docker exec web sh -lc 'wget -qO- http://api:8080 || curl -s http://api:8080'
# Accès depuis l'hôte
curl -sS http://localhost:8080
curl -sS http://localhost:8081

Documenter les ports et le nom du réseau pour réutilisation.

Pilote optionnel suivant (overlay)

Activez Swarm et répétez avec un réseau overlay entre deux hôtes ou deux VM.

Conclusion

Utilisez un user-defined bridge pour la plupart des applications monohôte : vous gagnez en isolation, en DNS prévisible entre conteneurs et en simplicité de published ports.
Envisagez host network uniquement sur Linux et seulement si vous avez besoin de l'overhead minimal, en comprenant bien les compromises de sécurité et d'exploitation.
Optez pour des overlay networks avec Swarm lorsque vous devez relier plusieurs hôtes.
Ne publiez que les ports nécessaires, vérifiez depuis l'hôte et entre conteneurs, et gardez une courte checklist de troubleshooting sous la main.
Commencez par un pilote local mesurable, puis étendez le même pattern à plus de services et, si besoin, à plusieurs hôtes.