Le diagramme de conteneurs (modèle C4 niveau 2) montre les blocs déployables de votre système : applications web, APIs, bases de données, files de messages. Ce guide explique ce qu'est un diagramme de conteneurs, ce qu'il doit contenir, un exemple complet, les erreurs courantes, et comment le garder synchronisé avec votre code.

Diagramme de conteneurs C4 : guide complet avec exemples

Si vous ne deviez dessiner qu'un seul diagramme d'architecture pour votre système, ce serait celui-là. Le diagramme de conteneurs est le niveau 2 du modèle C4, et c'est en pratique le plus utilisé des quatre niveaux -- parce qu'il correspond directement à ce que les équipes construisent, déploient et exploitent réellement : applications web, APIs, bases de données, message brokers.

Ce guide couvre tout ce qu'il faut pour créer un bon diagramme de conteneurs C4 : ce que c'est (et ce que ce n'est pas -- non, un conteneur C4 n'est pas un conteneur Docker), ce qu'il doit montrer, un exemple complet pour un produit SaaS typique, les erreurs qui ruinent la plupart des diagrammes de conteneurs, et comment en créer un à la main ou le générer depuis votre codebase.

Si vous découvrez le modèle C4, commencez par notre guide complet du modèle C4, puis revenez ici.

Qu'est-ce qu'un diagramme de conteneurs C4 ?

Le diagramme de conteneurs est le niveau 2 du modèle C4, créé par Simon Brown. Il zoome dans la boîte unique qui représente votre système dans le diagramme de Contexte Système et révèle les blocs de construction techniques de haut niveau qui le composent.

Dans la terminologie C4, un conteneur (container en anglais) est toute unité séparément déployable ou exécutable : quelque chose qui exécute du code ou stocke des données, tourne dans son propre processus (ou possède son propre cycle de vie de stockage), et pourrait en principe être déployé indépendamment du reste du système.

Cette définition couvre des choses comme :

Une application single-page (React, Vue, Angular) qui tourne dans le navigateur de l'utilisateur
Une application web côté serveur (Next.js, Rails, Django)
Une application mobile (app iOS, app Android)
Un service API backend (API Go, serveur Node.js, service Spring Boot)
Une base de données (PostgreSQL, MongoDB, MySQL)
Un cache (Redis, Memcached)
Un message broker ou une file de messages (Kafka, RabbitMQ, SQS)
Un worker de fond ou un processus de tâches planifiées
Un stockage de fichiers ou d'objets (bucket S3, MinIO)
Une fonction serverless (AWS Lambda, Cloud Functions)

Le test décisif est simple : est-ce que ça tourne dans son propre processus ou est-ce que ça détient ses propres données ? Deux packages Go compilés dans un même binaire appartiennent au même conteneur. Deux services déployés indépendamment sont deux conteneurs -- même s'ils partagent un dépôt.

Pour une définition de référence concise, consultez l'entrée diagramme de conteneurs de notre glossaire.

Un conteneur C4 n'est pas un conteneur Docker

C'est de loin la confusion la plus fréquente, alors réglons-la explicitement.

Le modèle C4 est antérieur à l'adoption massive de Docker, et le mot "container" en C4 a un sens plus large : un bloc de construction de votre système au niveau runtime. Le recouvrement avec Docker est accidentel et partiel :

Un conteneur C4 peut tourner dans un conteneur Docker. Votre API Go, probablement.
Un conteneur C4 peut aussi tourner comme simple processus OS, comme onglet de navigateur, comme app mobile, ou comme service cloud managé. Rien de tout ça n'est un conteneur Docker.
Un seul conteneur Docker pourrait même héberger plusieurs conteneurs C4 (une app plus une base embarquée dans une image de dev), même si c'est inhabituel.

Autrement dit : les conteneurs Docker sont une technologie de packaging et de déploiement. Les conteneurs C4 sont une abstraction architecturale. Une SPA React qui tourne dans Chrome est un conteneur C4 et ne sera jamais un conteneur Docker. Une instance PostgreSQL sur RDS est un conteneur C4 sans que Docker ne soit nulle part dans le décor.

Quand vous étiquetez une boîte "conteneur" sur un diagramme C4, vous dites "ceci est une partie séparément exécutable ou déployable de mon système" -- rien de plus.

Ce qui doit figurer sur un diagramme de conteneurs

Un bon diagramme de conteneurs montre exactement trois catégories d'informations :

1. Les conteneurs eux-mêmes

Chaque unité déployable ou exécutable à l'intérieur de la frontière de votre système, chacune étiquetée avec son nom, sa responsabilité et son choix technologique : "Service Commandes (Go)", "Cache de sessions (Redis)", "Application Web (SPA React)". L'étiquette technologique n'est pas décorative -- c'est la moitié de la valeur du diagramme. C'est ce qui permet à un nouvel ingénieur ou à une équipe plateforme de raisonner sur le système sans ouvrir douze dépôts.

2. Les relations et les protocoles

Des flèches entre conteneurs, chacune étiquetée avec ce qui circule et comment : "lit/écrit les factures (SQL)", "publie des événements (AMQP)", "fait des appels API (HTTPS/JSON)". Les protocoles de communication comptent à ce niveau parce qu'ils pilotent les préoccupations opérationnelles -- politiques réseau, budgets de latence, sémantique de retry, modes de défaillance.

3. Le contexte immédiat

Les utilisateurs et systèmes externes de votre diagramme de contexte, conservés en périphérie pour que le lecteur voie comment les requêtes entrent et sortent du système. Vous ne les re-documentez pas en détail ; ce sont des points d'ancrage.

À qui s'adresse ce diagramme ?

L'audience du diagramme de conteneurs est technique : les développeurs qui rejoignent l'équipe, les architectes qui prennent des décisions structurelles, et les ingénieurs ops/plateforme qui planifient déploiements, monitoring et capacité. C'est le niveau où des conversations comme "ces deux services devraient-ils partager une base ?" ou "qu'est-ce qui casse si Redis tombe ?" ont réellement lieu. Les parties prenantes non techniques devraient plutôt regarder le diagramme de contexte.

Ce qui ne doit PAS y figurer

Les modules, classes ou packages internes -- ils vivent dans le diagramme de composants (niveau 3)
Les détails d'infrastructure comme les load balancers, VPCs, nœuds Kubernetes -- ils appartiennent à un diagramme de déploiement
Chaque micro-interaction -- si une relation n'a pas de sens architectural, laissez-la de côté

Exemple de diagramme de conteneurs : un produit SaaS web

Construisons un exemple complet de diagramme de conteneurs pour un produit SaaS fictif -- "FactureHub", un outil de facturation web. Cette forme (SPA + API + base de données + cache + worker + file de messages) décrit une énorme partie des produits web réels, vous pouvez donc probablement l'adapter directement.

Les conteneurs

Conteneur	Technologie	Responsabilité
Application Web	SPA React	L'interface que les clients utilisent pour créer et envoyer des factures
Application API	Go (Fiber)	Logique métier, authentification, API REST consommée par la SPA
Base de données	PostgreSQL	Source de vérité pour les comptes, factures, paiements
Cache	Redis	Stockage des sessions et cache des résumés de factures
File de messages	RabbitMQ	Découple le travail lent (rendu PDF, emails) des requêtes API
Worker de fond	Go	Consomme les messages de la file : génère les PDF, envoie les emails, synchronise les statuts de paiement

Les relations

[Client] --> [Application Web (SPA React)] : Utilise (HTTPS)
[Application Web] --> [Application API (Go)] : Fait des appels API (HTTPS/JSON)
[Application API] --> [Base de données (PostgreSQL)] : Lit/écrit factures et comptes (SQL/TCP)
[Application API] --> [Cache (Redis)] : Lit/écrit sessions et résumés en cache (RESP)
[Application API] --> [File de messages (RabbitMQ)] : Publie invoice.created, email.requested (AMQP)
[Worker de fond (Go)] --> [File de messages] : Consomme les jobs (AMQP)
[Worker de fond] --> [Base de données (PostgreSQL)] : Met à jour les statuts de jobs et paiements (SQL/TCP)
[Worker de fond] --> [Service email (SendGrid)] : Envoie les emails de facture (HTTPS/REST)
[Application API] --> [Passerelle de paiement (Stripe)] : Crée les liens de paiement, reçoit les webhooks (HTTPS/REST)

Ce que ce diagramme vous apprend

Relisez cette liste et remarquez combien de questions d'ingénierie concrètes elle résout :

Où vit l'état ? À deux endroits : PostgreSQL (durable) et Redis (éphémère). Si vous avez déjà débattu de la survie des sessions à un redémarrage de Redis, le diagramme rend la question visible.
Quel est le rayon d'explosion d'une panne ? Le worker et l'API partagent la base de données. RabbitMQ en panne signifie que les factures se créent encore mais que les emails s'accumulent dans la file -- par design.
Où sont les frontières de confiance ? La SPA tourne sur des appareils clients non fiables ; tout ce qu'elle peut faire passe par l'authentification de l'API.
Que doit faire tourner l'équipe ops ? Six choses, avec leurs protocoles. C'est votre checklist de monitoring et, en gros, votre fichier docker-compose.

Un nouveau développeur absorbe tout ça en deux minutes. C'est exactement l'intérêt du modèle C4 niveau 2.

Erreurs courantes sur les diagrammes de conteneurs

La plupart des diagrammes de conteneurs échouent de quelques façons prévisibles.

Confondre conteneurs et composants

Si votre diagramme de conteneurs montre "OrderController", "InvoiceRepository" ou "AuthMiddleware", vous avez zoomé un niveau trop loin. Ce sont des composants -- des blocs internes à l'intérieur d'un conteneur -- et ils appartiennent au diagramme de composants de niveau 3. Le test : est-ce que ça peut être déployé ou exécuté seul ? Une classe repository, non. Gardez chaque diagramme à un seul niveau de zoom ; mélanger les niveaux est le moyen le plus rapide de produire un diagramme illisible.

Omettre les bases de données et les caches

Les équipes dessinent souvent uniquement ce pour quoi elles ont écrit du code, et oublient que les bases de données, caches et files de messages sont aussi des conteneurs. Un diagramme de conteneurs sans ses systèmes de stockage cache précisément l'information dont les architectes et les ingénieurs ops ont le plus besoin : où vit l'état, ce qui est partagé, ce qui constitue un point unique de défaillance. Si votre système utilise PostgreSQL, Redis et S3, les trois figurent sur le diagramme.

Dessiner le déploiement au lieu de la structure runtime

Un diagramme de conteneurs n'est pas un schéma d'infrastructure. Load balancers, pods Kubernetes, groupes d'auto-scaling, zones de disponibilité et nombre de réplicas sont des préoccupations de déploiement -- le C4 a un diagramme de déploiement complémentaire dédié pour ça. Le diagramme de conteneurs répond à "quelles sont les pièces logiques au runtime et comment communiquent-elles ?", pas à "combien d'instances tournent où ?". Dessiner trois boîtes "API" identiques parce que vous avez trois réplicas ajoute du bruit, pas de l'information.

Des relations vagues ou non étiquetées

Une flèche qui dit juste "utilise" gâche le potentiel du diagramme. "Fait des appels API (HTTPS/JSON)", "publie les événements de commande (AMQP)", "lit/écrit les sessions (RESP)" -- le verbe et le protocole transforment un dessin en documentation.

Le laisser pourrir

L'erreur la plus dommageable n'est même pas sur le diagramme. Un diagramme de conteneurs dessiné il y a dix-huit mois qui montre encore le monolithe que vous avez depuis découpé en quatre services induit activement en erreur chaque nouveau lecteur. Une archi C4 documentée mais obsolète est pire que pas de documentation du tout -- c'est pourquoi garder le diagramme synchronisé avec le code compte plus que son esthétique.

Comment créer un diagramme de conteneurs

À la main

Vous pouvez construire un diagramme de conteneurs solide en moins d'une heure :

Partez de votre diagramme de contexte. Gardez les utilisateurs et systèmes externes en périphérie.
Listez vos unités déployables. Parcourez vos dépôts, votre fichier docker-compose, votre console cloud. Tout ce qui tourne comme processus indépendant ou stocke des données est candidat.
Ajoutez explicitement les systèmes de stockage. Bases de données, caches, files, stockage objet.
Tracez les relations. Pour chaque paire de conteneurs qui communiquent, ajoutez une flèche avec un groupe verbal et un protocole.
Étiquetez les technologies. Nom et techno dans chaque boîte.
Faites une revue en équipe. La discussion que ça déclenche ("attends, le worker parle à Stripe directement ?") vaut souvent plus que le diagramme lui-même.

N'importe quel outil convient -- Structurizr, PlantUML avec l'extension C4, draw.io, voire un tableau blanc. La notation compte bien moins que le contenu et la discipline de le garder à jour.

Avec Archyl

L'approche manuelle a une faiblesse structurelle : elle capture un instantané, et le logiciel ne reste pas immobile. Archyl prend le diagramme de conteneurs par l'autre bout -- il dérive le modèle du code :

Découverte par IA depuis votre codebase. Connectez un dépôt et la découverte par IA d'Archyl analyse la structure de votre code, votre configuration et vos manifestes de dépendances pour proposer un brouillon de modèle C4 -- systèmes, conteneurs, composants et les relations entre eux. Vous passez en revue et validez les suggestions au lieu de dessiner des boîtes de mémoire.
La détection de drift le garde honnête. Une fois le modèle créé, Archyl compare en continu les conteneurs documentés avec ce que la codebase montre réellement et calcule un score de drift. Quand quelqu'un découpe un service ou remplace RabbitMQ par Kafka, vous l'apprenez depuis le dashboard, pas lors d'un onboarding confus six mois plus tard.
Architecture as Code. Vous préférez le texte ? Vous pouvez définir tout votre modèle C4 -- conteneurs, technologies, relations -- en YAML, le versionner avec votre code, et laisser Archyl générer les diagrammes interactifs. Les changements de diagramme passent par des pull requests comme tout le reste.

Dans les deux cas, l'objectif est le même : un diagramme de conteneurs exact aujourd'hui et encore exact le trimestre prochain.

FAQ

Un conteneur C4 est-il la même chose qu'un conteneur Docker ?

Non. Un conteneur C4 est une abstraction architecturale : toute unité séparément déployable ou exécutable d'un système, comme une application web, une API, une base de données ou un message broker. Un conteneur Docker est une technologie de packaging. Beaucoup de conteneurs C4 sont effectivement déployés en conteneurs Docker, mais beaucoup ne le sont pas -- une SPA React tourne dans un navigateur, une app mobile sur un téléphone, et une base managée comme service cloud. Le nom partagé est un malheureux accident de l'histoire.

Qu'est-ce que le modèle C4 niveau 2 ?

Le niveau 2 du modèle C4 est le diagramme de conteneurs. Il zoome dans un système logiciel (la boîte unique du diagramme de contexte de niveau 1) et montre les unités déployables/exécutables qui le composent, leurs choix technologiques, et les protocoles qu'elles utilisent pour communiquer. Il se situe entre le diagramme de contexte (niveau 1) et le diagramme de composants (niveau 3).

Combien de conteneurs un diagramme doit-il montrer ?

Il n'y a pas de règle absolue, mais la lisibilité se dégrade rapidement au-delà de 15-20 conteneurs. Si votre système en a réellement plus, découpez la vue : un diagramme de conteneurs par sous-système, ou des regroupements visuels de conteneurs liés. Si vous en avez des centaines, vous documentez probablement plusieurs systèmes et il vous faut des modèles C4 séparés, reliés au niveau contexte.

Chaque microservice doit-il être un conteneur séparé ?

Oui -- par définition. Chaque service déployable indépendamment est son propre conteneur, ainsi que la base de données de chaque service si vous suivez le pattern database-per-service. C'est d'ailleurs un bon test : si vos "microservices" ne peuvent pas être dessinés comme des conteneurs séparés parce qu'ils partagent un processus ou ne peuvent pas se déployer indépendamment, vous avez peut-être un monolithe distribué.

Prêt à générer votre diagramme de conteneurs au lieu de le dessiner ? Essayez Archyl gratuitement et obtenez un modèle C4 depuis votre codebase en quelques minutes. Continuez la série C4 : Qu'est-ce que le modèle C4 ? Guide complet | Guide du diagramme de Contexte Système C4 | Guide du diagramme de composants C4.

Diagramme de conteneurs C4 : guide complet avec exemples - Archyl Blog