Quand j’ai commencé à former mes étudiants en BTS SIO sur Docker, la confusion entre docker compose net et networks revenait à chaque promotion. Je recevais des questions du type : « Pourquoi mon option --net ne fonctionne pas dans mon fichier Compose ? » ou « Quelle est la différence entre net, network_mode et networks ? ». Si vous vous posez ces mêmes questions, vous êtes au bon endroit. Je vais vous expliquer précisément ce que recouvre chaque terme, comment ils s’articulent et comment bien configurer vos réseaux dans Docker Compose.

Comprendre la notion de net dans Docker

Avant de parler de Docker Compose, il faut revenir aux fondamentaux. L’option –net (ou son alias –network) appartient à la commande docker run. Elle permet de spécifier le réseau auquel rattacher un conteneur au moment de son lancement. Par exemple :

docker run --net=host nginx
docker run --network=mon-reseau-custom alpine

Cette option accepte plusieurs valeurs : bridge (le réseau par défaut), host (partage la pile réseau de l’hôte), none (aucun réseau) ou le nom d’un réseau personnalisé que vous avez créé avec docker network create. L’option --net est en réalité un héritage des premières versions de Docker. Depuis la version 1.13, Docker recommande d’utiliser --network à la place, même si les deux fonctionnent de manière identique.

Le point crucial à retenir : cette option n’existe pas dans le fichier docker-compose.yml. Je vois régulièrement des étudiants tenter d’écrire net: host dans leur fichier Compose, ce qui provoque une erreur de syntaxe. Docker Compose possède sa propre logique de configuration réseau, distincte de docker run. Si vous débutez avec Docker, je vous recommande de consulter mon guide sur la formation Docker pour acquérir les bases avant d’aborder la partie réseau.

Différence entre net et networks dans Docker Compose

La confusion entre net et networks vient du fait que ces deux termes semblent désigner la même chose, mais ils appartiennent à des contextes très différents. Voici la distinction fondamentale :

L’option –net (ou –network) est un paramètre en ligne de commande pour docker run. Elle s’utilise exclusivement dans le terminal. La clé networks, elle, est une directive YAML qui se place dans le fichier docker-compose.yml. Elle existe à deux niveaux : au niveau du service (pour indiquer à quels réseaux un conteneur doit se connecter) et au niveau racine (pour déclarer et configurer les réseaux eux-mêmes).

Concrètement, quand vous écrivez un fichier docker-compose.yml, la configuration réseau se fait ainsi :

services:
  web:
    image: nginx
    networks:
      - frontend
      - backend

  api:
    image: node:20
    networks:
      - backend

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge

Dans cet exemple, le service web est connecté à deux réseaux (frontend et backend), tandis que le service api n’est connecté qu’au réseau backend. Les deux services peuvent communiquer via le réseau backend, mais seul web est exposé sur le réseau frontend. Cette segmentation réseau est impossible avec un simple --net en ligne de commande, ce qui montre toute la puissance de la directive networks de Compose.

Pour approfondir les cinq configurations réseau les plus utiles, consultez mon article dédié aux configurations réseau Docker Compose.

Le rôle de network_mode dans Docker Compose

Si --net n’existe pas dans Compose, comment reproduire son comportement ? C’est là qu’intervient network_mode. Cette directive est l’équivalent direct de --net dans le fichier docker-compose.yml. Elle permet de définir le mode réseau global d’un service :

services:
  monitoring:
    image: prometheus
    network_mode: host

  isolated:
    image: alpine
    network_mode: none

Les valeurs acceptées par network_mode sont les mêmes que celles de --net : bridge, host, none ou service:[nom_service]. Ce dernier mode permet de partager la pile réseau d’un autre service, ce qui est pratique pour le débogage ou les sidecars.

Attention cependant à une règle fondamentale : network_mode et networks sont mutuellement exclusifs. Vous ne pouvez pas utiliser les deux en même temps sur le même service. Si vous déclarez network_mode: host, toute directive networks sur ce service provoquera une erreur. C’est une source de confusion fréquente que je rencontre en formation.

Le mode host est particulièrement utile dans certains cas de figure : monitoring réseau, applications nécessitant un accès direct aux interfaces réseau de l’hôte, ou situations où la traduction d’adresses (NAT) du bridge pose problème. Pour mieux comprendre la gestion des ports dans ce contexte, je vous invite à lire mon article sur les ports Docker.

Les types de réseaux disponibles dans Docker Compose

Docker Compose supporte plusieurs types de réseaux (drivers), chacun adapté à un usage spécifique. En tant que formatrice, je constate que beaucoup de développeurs restent sur le driver par défaut sans explorer les alternatives. Voici un panorama complet :

Le driver bridge est le plus courant. Il crée un réseau isolé sur la machine hôte, avec un sous-réseau dédié et une passerelle (gateway). Les conteneurs connectés à un même réseau bridge peuvent communiquer entre eux par leur nom de service. C’est le comportement par défaut quand vous lancez docker compose up sans configuration réseau explicite. Docker crée alors automatiquement un réseau nommé [nom_du_projet]_default.

Le driver host supprime l’isolation réseau entre le conteneur et l’hôte. Le conteneur utilise directement la pile réseau de la machine. Ce mode est performant car il élimine le surcoût du NAT, mais il empêche d’utiliser le mapping de ports (la directive ports est ignorée).

Le driver overlay permet de connecter des conteneurs répartis sur plusieurs machines Docker (mode Swarm). Si vous travaillez sur un cluster, c’est le driver à privilégier. Il chiffre le trafic entre les nœuds et gère automatiquement la découverte de services.

Le driver none désactive totalement le réseau pour un conteneur. Le conteneur ne dispose que de l’interface loopback. Ce mode est utile pour des tâches de calcul pur ou des conteneurs qui ne doivent avoir aucun accès réseau pour des raisons de sécurité.

Enfin, le réseau internal est une option que vous pouvez activer sur n’importe quel driver. Un réseau marqué internal: true empêche tout accès à l’extérieur : les conteneurs connectés peuvent communiquer entre eux, mais n’ont pas accès à Internet. C’est une mesure de sécurité précieuse pour les bases de données ou les services qui ne doivent jamais être exposés.

networks:
  db-net:
    driver: bridge
    internal: true
    ipam:
      config:
        - subnet: 172.28.0.0/16
          gateway: 172.28.0.1

La configuration IPAM (IP Address Management) vous permet de définir précisément le sous-réseau et la passerelle. C’est indispensable quand vos conteneurs doivent s’intégrer à un réseau existant ou quand vous avez besoin d’adresses IP prévisibles. Pour aller plus loin sur l’isolation réseau dans un contexte de sécurité, consultez mon article sur les configurations réseau Docker Compose.

Configurer un réseau personnalisé pas à pas

Passons à la pratique. Je vais vous montrer comment mettre en place une architecture réseau complète avec Docker Compose, en partant d’un cas concret que j’utilise régulièrement en cours : une application web avec un frontend, une API et une base de données.

L’objectif est le suivant : le frontend communique avec l’API, l’API communique avec la base de données, mais le frontend ne doit jamais pouvoir accéder directement à la base de données. Voici le fichier docker-compose.yml complet :

services:
  frontend:
    image: nginx:alpine
    ports:
      - "8080:80"
    networks:
      - front-net
    depends_on:
      - api

  api:
    build: ./api
    networks:
      - front-net
      - back-net
    environment:
      DB_HOST: db
      DB_PORT: 5432

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      back-net:
        ipv4_address: 172.20.0.10
    environment:
      POSTGRES_PASSWORD: secret

networks:
  front-net:
    driver: bridge
  back-net:
    driver: bridge
    internal: true
    ipam:
      config:
        - subnet: 172.20.0.0/24
          gateway: 172.20.0.1

volumes:
  pgdata:

Analysons cette configuration point par point. Le service api est connecté aux deux réseaux : il sert de pont entre le frontend et la base de données. Le réseau back-net est marqué internal: true, ce qui signifie que la base de données n’a aucun accès à Internet. J’ai également fixé l’adresse IP de la base de données à 172.20.0.10, ce qui peut être utile pour des configurations de monitoring ou de pare-feu.

Pour vérifier que tout fonctionne, lancez la stack puis inspectez les réseaux :

docker compose up -d
docker network ls
docker network inspect projet_back-net

La commande inspect vous montrera les conteneurs connectés, leurs adresses IP et la configuration du sous-réseau. C’est un outil de diagnostic indispensable que je recommande d’utiliser systématiquement lors de la mise en place d’un nouveau projet.

Si vous déployez un service d’authentification comme Keycloak avec Docker, cette architecture à double réseau est exactement le schéma à suivre pour isoler la base d’identités du reste de l’infrastructure.

Erreurs fréquentes et solutions pour le réseau Compose

Au fil de mes années de formation et de développement, j’ai recensé les erreurs les plus courantes liées au réseau dans Docker Compose. Voici celles que je rencontre le plus souvent, avec leurs solutions.

Erreur n°1 : utiliser net au lieu de networks dans le YAML. Comme je l’ai expliqué, net n’est pas une directive valide dans docker-compose.yml. Docker Compose retournera une erreur de validation. La solution : utilisez networks pour connecter un service à un ou plusieurs réseaux, ou network_mode pour définir un mode réseau global.

Erreur n°2 : mélanger network_mode et networks. Ces deux directives sont incompatibles sur un même service. Si vous avez besoin du mode host, supprimez toute référence à networks sur ce service. Si vous avez besoin de réseaux personnalisés, n’utilisez pas network_mode.

Erreur n°3 : oublier de déclarer le réseau au niveau racine. Quand vous référencez un réseau dans un service avec networks: [mon-reseau], ce réseau doit être déclaré dans la section networks au niveau racine du fichier. Sans cette déclaration, Docker Compose créera le réseau avec les paramètres par défaut, ce qui peut fonctionner mais n’est pas une bonne pratique.

Erreur n°4 : conflit de sous-réseaux. Si vous définissez manuellement un sous-réseau qui entre en conflit avec un réseau existant sur votre machine (y compris votre réseau local), Docker refusera de créer le réseau. Vérifiez les réseaux existants avec docker network ls et ip addr show avant de choisir votre plage d’adresses. Les plages 172.16.0.0/12 et 192.168.0.0/16 sont souvent déjà utilisées par le réseau local.

Erreur n°5 : ne pas utiliser le nom de service comme hostname. Dans un réseau Docker Compose, chaque service est automatiquement résolvable par son nom. Inutile de chercher l’adresse IP d’un conteneur : utilisez directement le nom du service comme hostname. Par exemple, DB_HOST=db dans l’exemple précédent fonctionne grâce au DNS intégré de Docker.

Pour mieux structurer vos fichiers et éviter ces pièges, mon guide sur le fichier docker-compose.yml vous sera très utile.

Docker Compose est-il toujours pertinent en 2026 ?

C’est une question que mes étudiants me posent régulièrement. La réponse est claire : oui, Docker Compose reste un outil incontournable en 2026. Malgré l’essor de Kubernetes et l’émergence d’alternatives comme Podman, Docker Compose conserve sa place pour plusieurs raisons.

D’abord, Docker Compose a évolué. La version V2, intégrée directement dans la CLI Docker sous la commande docker compose (sans tiret), a remplacé l’ancien binaire Python docker-compose. Cette version est plus rapide, plus stable et prend en charge des fonctionnalités avancées comme les profils, les dépendances conditionnelles et la gestion de versions améliorée des fichiers Compose.

Ensuite, Docker Compose excelle dans les environnements de développement local et les déploiements mono-serveur. Pour une application avec quelques services (un serveur web, une API, une base de données, un cache), Kubernetes serait disproportionné. Docker Compose offre la simplicité d’un fichier YAML unique avec une gestion automatique des réseaux, des volumes et des dépendances.

Qu’en est-il des alternatives ? Podman Compose offre une compatibilité partielle avec les fichiers docker-compose.yml, mais ne couvre pas encore tous les cas d’usage. Kubernetes avec des outils comme Kompose permet de convertir des fichiers Compose en manifestes K8s, mais c’est un écosystème bien plus complexe. Pour le développement et les projets de taille modeste, Docker Compose reste le choix le plus pragmatique, comme le confirme la documentation officielle de Docker Compose qui continue d’être activement maintenue.

En termes de chiffres, le plugin Docker Compose V2 dépasse les 13 millions de téléchargements mensuels sur les registres officiels. L’écosystème reste dynamique, avec des mises à jour régulières et une communauté active. Docker n’est pas mort ; il a simplement trouvé sa niche aux côtés de Kubernetes, chacun répondant à des besoins différents.

Bonnes pratiques réseau pour vos projets Compose

Pour conclure la partie technique, voici les recommandations que j’applique systématiquement dans mes projets et que je transmets à mes étudiants en alternance informatique.

Toujours déclarer explicitement vos réseaux. Même si Docker Compose crée un réseau par défaut, il est préférable de le déclarer dans votre fichier YAML. Cela rend la configuration lisible, documentée et reproductible. Un collègue qui lit votre fichier comprend immédiatement l’architecture réseau.

Segmenter les réseaux par responsabilité. Séparez le réseau frontend du réseau backend. Les services qui n’ont pas besoin de communiquer ne doivent pas partager le même réseau. C’est un principe de moindre privilège appliqué au réseau, essentiel en cybersécurité.

Utiliser le flag internal pour les services sensibles. Les bases de données, les files d’attente et les caches ne doivent généralement pas avoir accès à Internet. Marquez leurs réseaux comme internal: true pour renforcer l’isolation. C’est une bonne pratique que l’on retrouve dans les recommandations de la ANSSI sur la sécurisation des systèmes d’information.

Documenter la topologie réseau. Ajoutez un commentaire en début de fichier ou un schéma dans votre documentation pour expliquer quels services communiquent et via quels réseaux. En formation, j’impose à mes étudiants de dessiner le schéma réseau avant d’écrire le fichier Compose.

Ne pas fixer les adresses IP sauf nécessité. Le DNS intégré de Docker résout les noms de service automatiquement. Fixer les IP rend la configuration rigide et fragile. Réservez cette option aux cas où un outil externe a besoin d’une adresse stable (monitoring, pare-feu matériel).

Tester la connectivité après chaque modification. Utilisez docker compose exec web ping api ou docker compose exec api nslookup db pour vérifier que la résolution DNS et la connectivité fonctionnent comme prévu. Un test rapide évite des heures de débogage, comme le recommande la documentation Docker sur le réseau Compose.

Lucie Moreau

Formatrice IT indépendante depuis 2016, ancienne étudiante BTS SIO SLAM. 6 ans d'expérience en entreprise.