Diagramme d'architecture Terraform : des fichiers .tf à une image que tout le monde peut lire

Terraform décrit déjà votre infrastructure, avec précision et sous contrôle de version. Alors pourquoi personne ne comprend le système à partir du code ? Parce qu'un fichier .tf répond à « qu'est-ce qui existe et comment c'est configuré », alors que les personnes qui lisent un diagramme d'architecture posent d'autres questions : par où entre le trafic, qui parle à qui, où vivent les données et qu'est-ce qui est exposé ?

Ce guide montre comment passer de Terraform à un diagramme que des humains peuvent lire : pourquoi terraform graph n'est pas ce diagramme, comment faire correspondre les ressources à des cadres et à des cartes, quand utiliser le plan JSON, quoi laisser de côté et comment utiliser le résultat dans les revues de pull requests.

Pourquoi ni le code ni terraform graph ne sont le diagramme

Une petite stack de production atteint facilement une centaine de ressources réparties dans plusieurs fichiers et modules, et beaucoup d'entre elles sont de la colle : attachements de politiques IAM, associations de tables de routage, règles de groupes de sécurité, attachements de groupes cibles. La réponse à « Internet peut-il atteindre la base de données ? » s'y trouve, mais éparpillée sur une douzaine de références.

terraform graph ne règle pas ce problème. La commande affiche un graphe en langage DOT, et depuis Terraform 1.7 la sortie par défaut est un graphe simplifié qui, selon la référence de la commande, décrit uniquement l'ordre de dépendance des ressources. Des options comme -type=plan montrent une approximation du graphe plus complet que Terraform utilise pour construire un plan, et depuis Terraform 1.16, -format=mermaid produit du Mermaid au lieu du DOT.

Un graphe de dépendances répond à « qu'est-ce qui doit exister avant quoi ». Le service ECS dépend d'un rôle IAM, d'un groupe cible et d'une définition de tâche : les flèches vont donc du service vers ses prérequis, souvent à l'inverse du sens du trafic, et les ressources de colle prennent autant de place que la base de données. C'est utile pour déboguer un plan. Ce n'est pas un diagramme d'architecture.

La stack d'exemple

Une application web typique sur AWS : un VPC avec des sous-réseaux publics et privés dans deux zones de disponibilité, un Application Load Balancer, un service ECS sur Fargate, une base PostgreSQL sur RDS et un bucket S3 pour les fichiers envoyés. Un extrait de la configuration :

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "private_a" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = "10.0.11.0/24"
  availability_zone = "eu-west-1a"
}

resource "aws_lb" "web" {
  name               = "web"
  load_balancer_type = "application"
  subnets            = [aws_subnet.public_a.id, aws_subnet.public_b.id]
  security_groups    = [aws_security_group.alb.id]
}

resource "aws_ecs_service" "app" {
  name            = "app"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.app.arn
  launch_type     = "FARGATE"
  desired_count   = 2

  network_configuration {
    subnets         = [aws_subnet.private_a.id, aws_subnet.private_b.id]
    security_groups = [aws_security_group.app.id]
  }

  load_balancer {
    target_group_arn = aws_lb_target_group.app.arn
    container_name   = "app"
    container_port   = 8080
  }
}

resource "aws_db_instance" "main" {
  identifier                  = "app-db"
  engine                      = "postgres"
  instance_class              = "db.t4g.medium"
  allocated_storage           = 50
  username                    = "app"
  manage_master_user_password = true
  multi_az                    = true
  db_subnet_group_name        = aws_db_subnet_group.main.name
  vpc_security_group_ids      = [aws_security_group.db.id]
}

Faire correspondre Terraform à un diagramme

L'essentiel du travail consiste à décider quelles ressources deviennent des éléments du diagramme et lesquelles deviennent des détails d'autres éléments :

Fichiers .tf ou plan JSON

Vous pouvez travailler à partir de la configuration elle-même ou d'un plan :

terraform plan -out plan.out
terraform show -json plan.out > plan.json

Les fichiers .tf sont rapides et ne demandent rien à exécuter, mais count et for_each ne sont pas développés, les variables sont inconnues et les modules distants restent fermés. Dans le plan JSON, tout cela est résolu, et sa liste resource_changes indique ce que le plan fera de chaque ressource : ["create"], ["update"], ["delete"], ou ["delete", "create"] pour un remplacement. C'est donc la meilleure entrée pour relire une modification. Manipulez ce fichier avec précaution : la documentation de terraform show avertit que les valeurs sensibles de l'état apparaissent en clair dans sa sortie JSON.

Le diagramme

Comment le lire :

• Entrée. Les utilisateurs atteignent l'Application Load Balancer en HTTPS sur le port 443. L'enregistrement d'alias DNS pointe vers lui.
• Frontières réseau. Le VPC contient deux cadres : des sous-réseaux publics pour le répartiteur de charge et des sous-réseaux privés pour tout le reste. Rien dans les sous-réseaux privés n'est joignable depuis Internet.
• Le chemin. Le répartiteur de charge transmet au service ECS sur le port 8080. Le service parle à PostgreSQL sur le port 5432 et écrit les fichiers envoyés dans S3 en HTTPS.
• La note. Elle relie chaque carte aux adresses de ressources qu'elle recouvre et liste ce qui a été volontairement laissé de côté, pour que le lecteur retrouve le code.

Élaguer, puis ajouter ce que Terraform ne sait pas

Élaguez franchement. La colle IAM, les associations de tables de routage, les groupes de logs et les ressources de règle de groupe de sécurité ont leur place dans le code. Une carte par élément déployable ou par stockage de données est le bon niveau pour la plupart des lecteurs.

Ajoutez ensuite ce que Terraform ne peut pas vous dire :

• Qui utilise le système et par où entre le trafic.
• Le sens du flux. Les références vont d'une ressource vers ce dont elle a besoin ; le trafic circule souvent dans l'autre sens.
• Les ports et protocoles tirés des règles des groupes de sécurité, écrits sur les liens.
• Les services externes que l'application appelle et qui ne sont pas gérés dans cette configuration.
• Les faits qui comptent pendant un incident : Multi-AZ, sauvegardes, nombre souhaité de tâches.

L'utiliser dans les revues de pull requests

Un diagramme généré à partir du plan d'une pull request montre aux relecteurs la forme d'une modification plutôt qu'un long diff. Cherchez en particulier quelques éléments :

• Un nouveau point d'entrée public, comme un répartiteur de charge, un sous-réseau public ou un groupe de sécurité ouvert à 0.0.0.0/0.
• Le remplacement d'une ressource avec état. Un ["delete", "create"] sur une base de données ou un bucket mérite un second relecteur.
• Des ressources qui changent de sous-réseau ou sortent du réseau privé.
• De nouveaux stockages de données, qui ont besoin d'un responsable, de sauvegardes et d'une entrée dans votre cartographie des données.

Gardez séparés le diagramme généré et le diagramme d'architecture soigné. Le premier est une aide à la revue d'une modification ; le second est une documentation qui explique le système.

Le tenir à jour

Traitez le diagramme soigné comme du code : un responsable, un lien depuis le README du module et une mise à jour dès qu'une modification ajoute un point d'entrée, un stockage de données ou une frontière réseau. Des diagrammes d'architecture qui ne se périment pas décrit un workflow exactement pour cela. Pour le côté réseau de la même stack, consultez le guide du diagramme de VPC AWS, et pour l'exécuter dans deux régions, le diagramme d'architecture AWS multirégion.

Le construire dans Archboard

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Pour une première version, collez vos fichiers .tf ou votre plan JSON dans l'outil gratuit Terraform en diagramme. Il transforme les VPC et sous-réseaux en cadres, les ressources en cartes et les références en connexions, signale les modifications prévues à partir du plan JSON et replie la colle, comme les attachements de groupes cibles, dans les connexions. Sélectionnez Ouvrir dans Archboard pour continuer l'édition.
3. Pour dessiner à la main, ajoutez un cadre VPC du pack Réseau avec deux cadres Sous-réseau, un Répartiteur de charge cloud du pack Cloud dans les sous-réseaux publics, et une Instance de calcul et une Base de données gérée dans les sous-réseaux privés.
4. Ajoutez un nœud Stockage objet du pack Cloud pour le bucket, un nœud Internet du pack Réseau pour les utilisateurs et un nœud DNS pour l'enregistrement d'alias.
5. Étiquetez les liens avec les ports et protocoles, et ajoutez un bloc Markdown du pack Base qui relie les cartes aux adresses de ressources.

L'exemple utilise 10 nœuds de diagramme et reste dans les limites de l'offre Free. Si votre stack est définie en CloudFormation, l'outil CloudFormation en diagramme fait la même chose pour les templates.

FAQ

terraform graph peut-il produire un diagramme d'architecture ? Il produit un graphe de dépendances en DOT ou, depuis Terraform 1.16, en Mermaid. C'est utile pour déboguer des plans, mais il montre l'ordre de construction plutôt que le trafic et inclut les ressources de colle ; il faut donc le retravailler avant que des humains puissent le lire comme une architecture.

Faut-il dessiner à partir des fichiers .tf ou du plan JSON ? Utilisez les fichiers .tf pour un coup d'œil rapide à un module et le plan JSON pour relire une modification, car le plan a résolu les nombres, les modules et les actions prévues.

Comment représenter les groupes de sécurité ? Sous forme de ports et de protocoles sur les liens entre les ressources qu'ils protègent, pas comme des boîtes séparées.

Que faut-il laisser de côté ? Les attachements IAM, les associations de tables de routage, les ressources utilitaires comme random_id, et tout ce qui ne change pas la façon dont un lecteur comprend le trafic, les données ou l'exposition.

Comment garder le diagramme synchronisé avec le code ? Régénérez une version quand une modification ajoute un point d'entrée, un stockage de données ou une frontière réseau, et mettez à jour le diagramme soigné dans la même pull request.

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