Terraform multi-comptes AWS : structurer un monorepo avec Terragrunt
Arborescence calquée sur AWS Organizations, état distant et provider générés, rôle par compte, stacks et garde-fous CI : notre structure Terragrunt.
Dès qu'une organisation AWS compte plusieurs comptes, chaque root module Terraform répète les mêmes blocs : backend S3, provider, rôle à assumer, région. Copiés d'un dossier à l'autre, ils dérivent. Une clé de state dupliquée fait écrire deux environnements dans le même fichier, un provider oublié applique en staging ce qui était destiné à la production. Terragrunt sert à cela : garder des modules Terraform simples et sans configuration d'environnement, et générer tout le reste depuis un seul endroit.
Terragrunt a beaucoup changé ces deux dernières années, jusqu'à la version 1.0 publiée en mars 2026 avec un engagement de compatibilité. Une bonne partie des exemples qui circulent utilisent encore une syntaxe dépréciée. Nous signalons au fil de l'article ce qui a changé.
Une arborescence qui suit l'organisation
Le principe est simple : un dossier égale un state, et le chemin du dossier devient la clé du state. L'arborescence fixe donc à la fois l'organisation du code et le rayon d'impact de chaque apply. Nous la calquons sur les comptes AWS, puis sur les régions, puis sur les composants.
live/
root.hcl
network-prod/
account.hcl
eu-west-3/
region.hcl
transit-gateway/terragrunt.hcl
workload-prod/
account.hcl
eu-west-3/
region.hcl
vpc/terragrunt.hcl
eks/terragrunt.hcl
workload-staging/
account.hcl
eu-west-3/
region.hcl
vpc/terragrunt.hcl
eks/terragrunt.hcl
Le premier niveau correspond à un compte, pas à un « environnement » abstrait. C'est la frontière d'isolation qu'AWS met en avant dans ses recommandations d'organisation multi-comptes : comptes de sécurité et d'infrastructure partagée d'un côté, comptes de workloads de production et hors production de l'autre. Si votre code suit ce découpage, une revue de code montre immédiatement quel compte une modification touche. account.hcl et region.hcl ne contiennent que des locals (identifiant du compte, région) lus par la configuration racine.
La gestion de l'organisation elle-même, c'est-à-dire les OU, les SCP et la création de comptes, vit dans le compte de management. Nous la sortons de ce dépôt, ou au minimum dans un dossier dont le pipeline et les droits sont distincts : une erreur à ce niveau touche tous les comptes à la fois.
Le fichier racine s'appelle root.hcl, et non plus terragrunt.hcl. Terragrunt recommande ce renommage pour ne plus confondre la configuration partagée avec une unité déployable. L'ancien nom fonctionne encore avec un avertissement et restera supporté au moins jusqu'à Terragrunt 2.0, mais il oblige à écrire find_in_parent_folders("root.hcl") au lieu de l'appel sans argument que l'on voit dans les anciens exemples.
Une racine qui génère le backend et le provider
locals {
account = read_terragrunt_config(find_in_parent_folders("account.hcl"))
region = read_terragrunt_config(find_in_parent_folders("region.hcl"))
account_id = local.account.locals.account_id
aws_region = local.region.locals.aws_region
}
iam_role = "arn:aws:iam::${local.account_id}:role/terragrunt-deployer"
remote_state {
backend = "s3"
generate = {
path = "backend.tf"
if_exists = "overwrite_terragrunt"
}
config = {
bucket = "acme-tfstate-${local.account_id}"
key = "${path_relative_to_include()}/terraform.tfstate"
region = "eu-west-3"
encrypt = true
use_lockfile = true
}
}
Trois choix méritent d'être expliqués. Le bloc generate écrit le backend.tf à la place du module, qui n'a plus besoin de déclarer un backend vide. La clé dérive de path_relative_to_include(), donc du chemin de l'unité : deux unités ne peuvent pas partager un state par erreur.
Le verrouillage passe par use_lockfile, le verrouillage natif S3. La documentation du backend S3 indique que le verrouillage par DynamoDB est déprécié et sera retiré dans une future version mineure ; dynamodb_table, encore présent dans la plupart des exemples, n'a plus de raison d'apparaître dans une nouvelle configuration. Les deux mécanismes peuvent coexister le temps d'une migration. Vérifiez que votre version de Terraform ou d'OpenTofu prend en charge le verrou S3 avant de basculer.
Enfin, iam_role fait assumer à Terragrunt le rôle de déploiement du compte cible avant d'appeler Terraform. Le state vit alors dans un bucket du compte qu'il décrit, ce qui limite le rayon d'impact d'une fuite de credentials ou d'une erreur de droits. L'alternative, un bucket central dans un compte dédié et un assume_role dans le provider, simplifie l'amorçage et la supervision, mais concentre tous les states, qui contiennent souvent des secrets, au même endroit. Nous préférons un bucket par compte. Préfixez son nom par celui de votre organisation : les noms de buckets S3 sont uniques pour tous les clients AWS.
Les versions actuelles de Terragrunt ne créent plus le bucket implicitement. L'amorçage est explicite, avec terragrunt backend bootstrap ou l'option --backend-bootstrap, désactivée par défaut. C'est mieux ainsi : on décide quand un nouveau compte reçoit son bucket, plutôt que de le découvrir au premier plan.
La racine génère aussi le provider, sur le même principe :
generate "provider" {
path = "provider.tf"
if_exists = "overwrite_terragrunt"
contents = <<EOF
provider "aws" {
region = "${local.aws_region}"
allowed_account_ids = ["${local.account_id}"]
}
EOF
}
allowed_account_ids est un filet de sécurité bon marché : si les credentials pointent vers un autre compte que celui de l'arborescence, Terraform refuse de travailler.
Unités, dépendances et versions de modules
Une unité se réduit à quatre éléments : l'inclusion de la racine, la source du module, ses dépendances et ses entrées.
include "root" {
path = find_in_parent_folders("root.hcl")
}
terraform {
source = "git::https://github.com/acme/terraform-modules.git//eks?ref=v3.4.0"
}
dependency "vpc" {
config_path = "../vpc"
mock_outputs = {
vpc_id = "vpc-00000000"
private_subnet_ids = ["subnet-00000000"]
}
mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}
inputs = {
cluster_name = "workload-prod"
vpc_id = dependency.vpc.outputs.vpc_id
subnet_ids = dependency.vpc.outputs.private_subnet_ids
}
La source est épinglée sur un tag, jamais sur une branche. Ce point en appelle un autre, souvent négligé : un dossier modules/ dans le même dépôt, référencé par chemin relatif, n'est versionné par rien. Toute modification d'un module s'applique à tous les comptes au prochain plan, production comprise. Si vous voulez qu'un changement de module soit d'abord promu en staging, les modules doivent vivre dans un dépôt séparé, ou être référencés par une source Git taguée même lorsqu'ils sont dans le même dépôt. Le monorepo convient très bien à la configuration live/ ; il convient mal aux modules non versionnés.
Les mock_outputs permettent de lancer un plan sur une unité dont la dépendance n'a jamais été appliquée. Sans eux, terragrunt run --all plan échoue sur un environnement neuf, faute de state à lire. Le prix est qu'un plan construit sur des mocks n'a aucune valeur : il faut le lire comme une vérification de syntaxe, pas comme une prévision. Nous limitons par ailleurs les dependency au périmètre d'un même compte et d'une même région. Pour consommer un réseau partagé depuis un compte d'infrastructure, des data sources filtrées par tags couplent moins les cycles de déploiement de deux équipes qu'une dépendance inter-comptes.
Stacks : implicites d'abord
Terragrunt appelle désormais « stack » un ensemble d'unités gérées ensemble. L'arborescence ci-dessus est une stack implicite : la structure des dossiers suffit. Les stacks explicites ajoutent un fichier terragrunt.stack.hcl, qui décrit des unités à générer à partir d'un catalogue versionné :
unit "vpc" {
source = "git::https://github.com/acme/terragrunt-catalog.git//units/vpc?ref=v1.2.0"
path = "vpc"
values = {
cidr = "10.20.0.0/16"
}
}
unit "eks" {
source = "git::https://github.com/acme/terragrunt-catalog.git//units/eks?ref=v1.2.0"
path = "eks"
values = {
cluster_name = "workload-staging"
}
}
terragrunt stack generate produit les unités dans un dossier .terragrunt-stack, que la documentation des stacks explicites recommande d'ignorer dans Git, et l'unité du catalogue lit ses paramètres via values.cidr. Le gain est réel quand des dizaines de comptes reçoivent le même socle et ne diffèrent que par quelques valeurs. Le coût l'est aussi : le code exécuté n'est plus celui que l'on relit dans la pull request, le débogage passe par des fichiers générés, et la documentation reconnaît encore des limites, comme l'impossibilité pour une stack de déclarer elle-même des dépendances. Terragrunt conseille de commencer par des stacks implicites ; nous faisons de même et ne passons aux stacks explicites que lorsque la duplication entre comptes devient le vrai problème.
La CLI a changé
Si votre CI date de quelques années, elle utilise probablement terragrunt run-all plan, des options préfixées --terragrunt- et des variables d'environnement TERRAGRUNT_*. Tout cela est déprécié. On écrit désormais terragrunt run --all plan, --non-interactive au lieu de --terragrunt-non-interactive, et TG_NON_INTERACTIVE. Le guide de migration de la CLI donne la table de correspondance complète, car certaines options ont été renommées au-delà de la simple suppression du préfixe.
L'option --filter remplace plusieurs anciennes options de sélection, et --filter-affected limite l'exécution aux unités modifiées entre la branche par défaut et HEAD : exactement ce qu'il faut pour un plan de pull request dans un monorepo.
Les garde-fous que nous jugeons indispensables
Le pipeline exécute un plan sur chaque pull request, limité aux unités touchées, et publie le résultat en commentaire. Checkov et tflint y sont bloquants. Les credentials viennent d'une fédération OIDC entre le système de CI et AWS, jamais de clés statiques : un rôle en lecture seule pour les plan des pull requests, un rôle capable d'assumer terragrunt-deployer dans chaque compte réservé à la branche principale, ce que la trust policy peut imposer.
L'apply n'est lancé que par le pipeline. Ce n'est pas une préférence de confort : run --all apply ajoute automatiquement -auto-approve, car l'entrée standard partagée rend les confirmations unitaires impossibles. Lancé depuis un poste de travail au mauvais niveau de l'arborescence, il applique tout ce qui se trouve en dessous sans poser de question. En production, une SCP qui refuse les actions d'écriture à tout autre principal que le rôle de déploiement rend cette règle vérifiable, au lieu de la laisser reposer sur la discipline.
Enfin, un plan planifié chaque nuit sur l'ensemble des unités détecte le drift introduit par des modifications manuelles ou par un module mis à jour sans être appliqué partout. Un écart qui n'ouvre pas de ticket n'est pas surveillé, il est seulement journalisé.
Need help with this topic?
Our engineers can audit your context and propose a concrete action plan.