Comment transformer un fichier Docker Compose en diagramme d'architecture

Un fichier Compose est souvent la description la plus honnête que vous ayez d'un système. C'est ce qui démarre réellement sur un poste de développement, en CI et parfois en production. C'est aussi un mur de YAML, et une nouvelle recrue doit quand même demander quel service parle à quel autre.

Ce guide transforme un fichier Compose en diagramme d'architecture digne de confiance : faites le rendu du fichier que Compose exécute vraiment, associez chaque clé à un élément du diagramme, ajoutez les appels que le fichier ne peut pas exprimer et gardez le dessin synchronisé avec le fichier. À la fin, nous utilisons l'outil gratuit d'Archboard pour obtenir une première version en quelques secondes.

L'exemple : une petite stack shop

Voici le compose.yaml que nous allons dessiner. Il est court, mais il contient les pièges habituels : un service sur deux réseaux, une dépendance qui n'existe que dans un fichier de configuration et un outil réservé au développement.

name: shop

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - api
    networks: [frontend]

  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://shop:${POSTGRES_PASSWORD}@db:5432/shop
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks: [frontend, backend]

  worker:
    build: ./api
    command: ["node", "worker.js"]
    environment:
      DATABASE_URL: postgres://shop:${POSTGRES_PASSWORD}@db:5432/shop
      REDIS_URL: redis://cache:6379/0
    depends_on:
      - db
    deploy:
      replicas: 2
    networks: [backend]

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 5s
    networks: [backend]

  cache:
    image: redis:7
    networks: [backend]

  adminer:
    image: adminer
    ports:
      - "8081:8080"
    profiles: [debug]
    networks: [backend]

volumes:
  db-data:

networks:
  frontend:
  backend:

Étape 1 : faire le rendu du fichier que Compose exécute vraiment

Les équipes exécutent rarement un fichier unique tel qu'il est écrit. Un fichier override ajoute des ports, un fichier .env renseigne les variables, et extends reprend des champs d'un autre service. Avant de dessiner, demandez le résultat à Compose :

docker compose config > rendered.yaml

docker compose config fusionne les fichiers override, remplace les variables et résout extends, puis affiche le modèle que Compose va exécuter. Dessinez à partir de cette sortie, pas du fichier que vous avez ouvert à ce moment-là.

Un avertissement : la sortie contient les vraies valeurs de vos variables, y compris tout ce qui est secret dans .env. Traitez rendered.yaml comme le fichier .env lui-même : ne le commitez pas et ne le partagez pas.

Étape 2 : associer les clés Compose aux éléments du diagramme

L'essentiel du diagramme vient directement du fichier :

Deux règles gardent le schéma honnête. Un service qui rejoint deux réseaux, comme api, fait le pont entre eux : placez-le au bord du cadre de son premier réseau et laissez ses liens passer dans l'autre. Et les réplicas sont un nombre, pas une pile de boîtes : worker ×2 reste juste quand vous passez à cinq.

Étape 3 : ajouter les appels que le fichier ne montre pas

C'est l'étape qu'aucun outil ne peut faire à votre place. depends_on concerne l'ordre de démarrage : Compose démarre db avant api et, avec condition: service_healthy, attend que le healthcheck réussisse. Il ne dit rien de qui appelle qui à l'exécution.

Les vrais appels se cachent à trois endroits :

• Les chaînes de connexion. DATABASE_URL et REDIS_URL nomment des hôtes (db, cache) et des ports. Chacune est un lien.
• Les fichiers de configuration montés dans les conteneurs. nginx.conf contient proxy_pass http://api:3000;. C'est le lien de web vers api, et il se trouve en dehors du fichier Compose.
• Le code. Un service peut en appeler un autre sans qu'aucune ligne de Compose le mentionne. worker utilise REDIS_URL mais n'a pas de depends_on sur cache. Si Redis démarre en retard, le worker échoue au démarrage, et le diagramme est le premier endroit où ce manque devient visible.

Une recherche rapide trouve la plupart d'entre eux :

grep -rnE "://([^/@[:space:]]*@)?(api|web|db|cache)[:/]|proxy_pass" --include="*.conf" --include="*.yaml" --include="*.yml" --include="*.env" .

Confirmez ensuite avec le responsable de chaque service. Dessinez les appels à l'exécution en liens pleins, étiquetés avec le protocole et le port, et gardez depends_on sous forme de note ou de lien en pointillés, pour que personne ne confonde ordre de démarrage et trafic.

Étape 4 : décider ce qu'on laisse de côté

Un fichier Compose mélange le système et les outils qui l'entourent. En général, vous laissez de côté :

• Les services réservés au développement derrière profiles, comme adminer, les mail catchers ou les proxys de débogage.
• Les jobs ponctuels comme les migrations ou les seeders, sauf si le diagramme porte sur le déploiement.
• Les bind mounts du code source et des fichiers de configuration. Ne montrez un fichier de configuration qu'à travers la dépendance qu'il porte, comme ici le lien proxy_pass issu de nginx.conf.
• Les valeurs d'environnement. Les noms de variables peuvent expliquer un lien ; les valeurs ont leur place dans votre gestionnaire de secrets, pas sur un diagramme.

Étape 5 : organiser la mise en page

Placez le trafic de gauche à droite : le navigateur, puis le port publié, puis les services qui se trouvent derrière. Dessinez chaque réseau comme un cadre, pour qu'un appel qui traverse des réseaux saute aux yeux. Regroupez les stockages de données et placez les volumes sous le service qui les monte. Étiquetez chaque lien avec le protocole et le port, par exemple HTTP :3000 ou SQL :5432.

Obtenir une première version avec l'outil gratuit

Inutile de dessiner les cartes à la main. Collez le fichier (ou la sortie rendue ; l'outil ne lit pas les valeurs d'environnement) dans l'outil gratuit Docker Compose en diagramme. Aucun compte n'est nécessaire pour l'afficher. Les services deviennent des cartes avec leur image, leurs ports et leurs réplicas, les réseaux deviennent des cadres, les volumes nommés, secrets et configs sont reliés aux services qui les utilisent, et depends_on devient des liens entre services.

L'outil ne dessine que ce que dit le fichier. Il ne montre pas les appels à l'exécution, ne lit ni les valeurs d'environnement ni le contenu des env_file, ne suit pas include, et pour un service qui utilise extends, il ne dessine que les champs écrits dans ce service. C'est pourquoi les étapes 1 et 3 restent importantes.

Avec un compte gratuit, vous ouvrez le résultat dans Archboard comme nouveau diagramme, puis vous ajoutez les liens d'exécution de l'étape 3 et retirez le bruit de l'étape 4. Voici la stack shop après ce passage :

Les cartes viennent du pack Docker, le navigateur du pack Réseau, et l'ensemble du diagramme tient dans les 15 nœuds de diagramme de l'offre Free. Pour une autre mise en page Docker, avec des conteneurs, un registre et un répartiteur de charge, consultez l'exemple Docker Runtime Mesh.

Garder le diagramme à jour

Un diagramme tiré d'un fichier Compose devient obsolète le jour où quelqu'un ajoute un service. Trois habitudes aident :

• Ajoutez une ligne au template de pull request : « Ajoute un service, un réseau, un port publié ou une chaîne de connexion ? Mettez à jour le diagramme. »
• Relancez docker compose config pendant les revues et comparez la liste des services avec le diagramme.
• Dans le README, mettez un lien vers le diagramme en direct plutôt qu'une capture d'écran, pour n'avoir qu'une seule copie à mettre à jour.

Quand la stack passe à Kubernetes, la même méthode s'applique aux manifestes ; voir Du YAML Kubernetes au diagramme d'architecture.

FAQ

depends_on signifie-t-il qu'un service en appelle un autre ? Non. Il contrôle l'ordre de démarrage et, avec condition: service_healthy, attend aussi un healthcheck. Les appels à l'exécution viennent des chaînes de connexion, des fichiers de configuration et du code.

Puis-je représenter plusieurs fichiers Compose à la fois ? Faites-en d'abord le rendu avec docker compose config, qui fusionne les fichiers override en un seul modèle. L'outil gratuit lit un fichier à la fois.

L'outil lit-il mon fichier .env ? Non. Les variables ne sont pas remplacées : un tag d'image ou un port écrit avec une variable, comme image: shop-api:${TAG}, s'affiche tel quel, et les valeurs sous environment et dans env_file ne sont pas lues.

Dois-je dessiner une boîte par conteneur ? Dessinez une carte par service et inscrivez-y le nombre de réplicas. Les conteneurs individuels vont et viennent ; c'est sur le service que l'équipe raisonne.

Le diagramme se met-il à jour quand je modifie compose.yaml ? Non. C'est un point de départ. Gardez-le à jour avec les habitudes ci-dessus, ou redessinez-le avec l'outil et reportez vos liens d'exécution.

Commencez gratuitement — un siège, sans carte bancaire.