Le problème
Notre boutique en ligne tourne en développement avec une
stack Docker Compose par service : order,
stock, shipping. Chacune a son
api
FrankenPHP, sa database PostgreSQL et son
redis. RabbitMQ et Mercure vivent dans une
stack commune, que les autres rejoignent par un réseau
externe, app-network.
Tout commence par l'API. Pour joindre RabbitMQ, elle reçoit
networks: [app-network] et quitte du même coup
le réseau default de sa stack. Elle ne trouve
plus database, et le correctif rapide branche
aussi database et redis sur
app-network.
Cela fonctionne tant qu'une seule stack tourne. Au démarrage
de stock, le nom database désigne
deux conteneurs sur app-network, car chaque nom
de service y est un alias réseau. Le DNS embarqué de Docker
renvoie alors les deux adresses, dans un ordre mélangé à
chaque réponse.
Le client PostgreSQL (libpq, sous pdo_pgsql)
essaie les adresses dans l'ordre reçu et garde la première
qui accepte la connexion. Les stacks viennent du même
gabarit : même utilisateur, même mot de passe, même nom
de base. L'API de order peut donc lire, écrire
ou migrer la base de stock sans la moindre
erreur, et redis pose le même problème.
La solution
Seule l'API rejoint le réseau partagé : elle parle à
RabbitMQ et à Mercure, et les autres stacks l'appellent.
Elle liste aussi default, car nommer un réseau
retire le réseau implicite. database et
redis ne listent aucun réseau : Compose
les branche sur default, et seulement sur lui.
# services/order/compose.override.yaml
services:
api:
networks:
# Nommer un réseau retire le réseau implicite : nous le gardons.
default: {}
app-network:
# Le nom à utiliser depuis les autres stacks.
aliases:
- order-api
# database et redis ne listent aucun réseau : ils restent sur default.
networks:
app-network:
external: true
Sur default, database ne désigne
plus que la base de la stack. Sur app-network,
le nom api reste ambigu : chaque stack y
branche le sien. Les autres stacks appellent donc
order-api, un alias qui n'existe que sur ce
réseau.
Docker Compose 5.7.0, publié le 2 novembre 2026, ajoute
use_service_name_alias. Placé à
false à côté de aliases, il retire
le nom api de app-network. Avant
cette version, la règle reste de ne jamais appeler
api depuis une autre stack.
Le piège
Une API qui démarre ne prouve rien : elle a peut-être migré la base d'à côté. Nous vérifions la résolution depuis le conteneur, car c'est lui qui interroge le DNS embarqué. Le test n'a de sens qu'avec au moins deux stacks démarrées.
# Depuis la stack order, la stack stock étant démarrée
docker compose exec api getent hosts database
docker compose exec api getent hosts redis
docker compose exec api bin/console dbal:run-sql "SELECT inet_server_addr()"
Sur une image Debian, getent hosts affiche une
ligne par adresse trouvée (celui d'Alpine n'affiche que la
première) : nous en attendons une seule. La requête SQL
renvoie l'adresse du serveur qui a accepté la connexion, à
comparer avec celle de getent. Si
getent ne renvoie rien, l'API a perdu
default : c'est l'oubli qui avait poussé
la base sur le réseau partagé.
Sources
-
Docker Compose,
services : networks,
aliases
et
use_service_name_alias : réseau
defaultimplicite, nom de service enregistré comme alias, alias partagé sans garantie sur le conteneur choisi. - Docker Compose, Networking in Compose et réseaux externes : plusieurs projets sur un réseau partagé.
-
Docker Compose,
pull request 14342
et
version 5.7.0
du 2 novembre 2026 :
use_service_name_alias. - Docker Engine, DNS services, notes de version 1.11.0 (plusieurs enregistrements A pour un même nom) et resolver.go : adresses mélangées à chaque réponse.
- PostgreSQL 18, libpq, plusieurs hôtes et inet_server_addr() ; PHP, PDO_PGSQL (libpq).
- Symfony, dbal:run-sql ; Linux, getent(1) ; Alpine, getent.c (seule la première adresse est affichée).
- Lychen, pull request 266 : une mise en œuvre open source de ce que décrit cette note, dans un monorepo moon.