Terragrunt pour structurer Terraform et OpenTofu

Terragrunt devient utile quand vos projets Terraform ou OpenTofu restent lisibles a l’echelle d’un module, mais commencent a devenir repetitifs a l’echelle d’un repo complet. Si vous dupliquez les memes conventions entre dev, staging et prod, si vous recopiez le backend partout, ou si vous ne savez plus comment lancer proprement plusieurs composants ensemble, Terragrunt est la couche qui remet de l’ordre.

Ce que vous allez apprendre

Ce qu’est Terragrunt et ce qu’il ne remplace pas
Le vocabulaire minimal pour suivre les guides pratiques sans vous perdre
Comment Terragrunt fonctionne, etape par etape, au-dessus de Terraform ou OpenTofu
Dans quel ordre lire les guides de cette section pour progresser efficacement

Terragrunt en une phrase

Terragrunt est une couche d’organisation au-dessus de Terraform ou OpenTofu. Il ne remplace ni le langage HCL, ni les providers, ni les resources. Il sert surtout a instancier vos modules, centraliser des regles communes et orchestrer plusieurs dossiers deployables.

Le probleme qu’il resout

Sans Terragrunt, un repo d’infrastructure grossit souvent de cette facon :

le meme backend est recopie dans plusieurs dossiers ;
les memes variables reviennent dans tous les environnements ;
l’ordre entre composants devient flou ;
un pipeline declenche trop large, faute de ciblage propre ;
le repo reste executable, mais il devient penible a maintenir.

Terragrunt apporte une reponse structurelle a ces problemes. Il permet de garder les modules d’un cote, les instances concretes de l’autre, et les regles communes a un niveau central.

Vocabulaire minimal

Si vous retenez mal le vocabulaire, les guides deviennent vite abstraits. Voici les definitions a garder en tete pour toute la section.

Terme	Ce que c’est	Concretement
module	Le code Terraform ou OpenTofu reutilisable	Le dossier qui contient les resources, variables et outputs
unit	Un dossier deployable pilote par `terragrunt.hcl`	Une instance concrete d’un module avec ses propres valeurs
live repo	L’arborescence qui regroupe les units	Souvent rangee par environnement, compte, region ou application
include	Un mecanisme d’heritage Terragrunt	Une unit relit des conventions definies plus haut
root.hcl	Le fichier racine des regles partagees	Backend, generate, locals communs, conventions globales
run queue	La file d’execution calculee par Terragrunt	L’ordre reel dans lequel les units vont etre traitees
stack	Un groupe de units gerees ensemble	Implicite par l’arborescence ou explicite avec `terragrunt.stack.hcl`

Comment Terragrunt fonctionne

Le modele mental le plus simple est le suivant :

Vous ecrivez un module Terraform

Le module contient la logique Terraform ou OpenTofu reutilisable.
Vous creez une unit avec terragrunt.hcl

Cette unit ne reecrit pas les resources. Elle choisit le module et fournit les valeurs d’entree.
Terragrunt ajoute les regles communes

Via include, root.hcl, remote_state ou generate, Terragrunt injecte ce qui doit etre partage entre plusieurs units.
Terragrunt lance ensuite Terraform ou OpenTofu

L’engine IaC fait le vrai travail de plan, apply et destroy.

En pratique, il faut retenir cette separation des roles :

Terraform ou OpenTofu decrivent et executent l’infrastructure ;
Terragrunt organise comment cette infrastructure est instanciee et pilotee dans le repo.

Schema simple d’un live repo

Voici un exemple minimal pour visualiser ou se place Terragrunt :

Répertoirelive/
- root.hcl
- Répertoire_env/
  - app.hcl
- Répertoiredev/
  - Répertoireapp/
    terragrunt.hcl
  - Répertoireworker/
    terragrunt.hcl
Répertoiremodules/
- Répertoireapp/
  - main.tf
  - variables.tf
  - outputs.tf

Comment lire cette arborescence :

modules/ contient la logique reutilisable ;
live/ contient les units reelles a executer ;
root.hcl porte les conventions communes ;
_env/ factorise des reglages partages par famille de units ;
chaque dossier comme dev/app est une unit concrete.

Quand Terragrunt vaut l’effort

Terragrunt commence a etre rentable quand au moins un de ces problemes apparait :

Situation	Ce qui fait mal sans Terragrunt	Ce que Terragrunt apporte
Plusieurs environnements proches	Duplication entre `dev`, `staging` et `prod`	include, root.hcl et structure de live repo
Plusieurs composants dependants	Ordre de `plan` ou `apply` fragile	dependency, mock_outputs et run queue
Backend ou provider repetes partout	Fichiers presque identiques dans chaque dossier	remote_state et generate
Pipeline trop large	Trop de composants touches a chaque run	run —all et —filter

Quand il est trop tot

Terragrunt n’est pas automatiquement un progres. Il est souvent trop tot si :

vous apprenez encore les bases de Terraform ;
vous avez seulement un ou deux dossiers tres simples ;
vous ne dupliquez pas encore de logique ;
votre vrai probleme est d’abord la qualite des modules.

Dans ce cas, il vaut mieux stabiliser vos bases sur Terraform ou OpenTofu avant d’ajouter une couche d’orchestration.

A retenir

Terragrunt n’est pas un remplacement de Terraform ou OpenTofu.
Son vrai role est d’organiser un live repo, de centraliser des conventions et de piloter plusieurs units.
Le mot unit designe simplement un dossier deployable contenant un terragrunt.hcl.
Si vous avez encore peu de duplication, il est souvent trop tot pour l’adopter.
Si votre repo devient repetitif et difficile a orchestrer, il devient tres vite rentable.

Prochaine étape

Installer Terragrunt Commencer ici pour installer Terragrunt avec mise et verifier que la commande fonctionne avant le premier guide pratique.