Terragrunt : catalogues, scaffold et industrialisation

Comment ajouter rapidement une nouvelle unit Terragrunt sans repartir d’un fichier vide et sans que chaque membre de l’equipe invente sa propre structure ? C’est le role de catalog et scaffold. Ce guide vous montre comment les utiliser pour standardiser la creation de nouvelles units.

Ce que vous allez apprendre

Comprendre la difference entre catalog (decouverte de modules) et scaffold (generation d’une unit)
Generer un terragrunt.hcl propre a partir d’un module avec scaffold
Configurer les garde-fous --no-hooks et --no-shell pour une generation sure
Industrialiser le pattern avec un depot catalogue dedie

Ce qu’apportent catalog et scaffold

Pensez a un magasin de pieces detachees : catalog est le catalogue ou vous feuilletez les references disponibles, et scaffold est le bon de commande qui genere la fiche technique de la piece choisie.

Commande	Role	Quand l’utiliser
`catalog`	Parcourir et selectionner un module dans une TUI	Decouvrir les modules approuves par l’equipe
`scaffold`	Generer un `terragrunt.hcl` pre-rempli a partir d’un module	Creer une nouvelle unit sans partir de zero

Ces deux commandes ne servent pas a centraliser vos conventions existantes (root.hcl, remote_state, generate). Elles servent a standardiser la creation de nouvelles units qui respecteront ensuite ces conventions.

Ce que catalog et scaffold ne font pas

Si votre objectif est de factoriser ce qui est commun a toutes les units, catalog et scaffold ne sont pas le bon premier outil.

Ils ne servent pas a :

remplacer un root.hcl partage ;
centraliser un backend via remote_state ;
ecrire automatiquement vos blocs generate existants dans tout le repo ;
refactorer des units deja presentes.

Ils servent a autre chose : preparer proprement une nouvelle unit qui respectera ensuite vos conventions racines.

Structure minimale du projet

L’exemple repose sur deux repertoires :

Répertoireterragrunt-catalog-repo/
- Répertoiremodules/
  - Répertoiremysql/
    main.tf
Répertoireterragrunt-consumer/
- Répertoirelive/
  - root.hcl
  - Répertoiredev/
    Répertoiremysql/
    …

Le premier depot joue le role de catalogue de modules. Le second depot joue le role de repo consommateur dans lequel on veut generer une nouvelle unit.

Le module minimal du depot catalogue

Dans terragrunt-catalog-repo/modules/mysql/main.tf, placez ce module minimal :

terraform {
  required_version = ">= 1.6.0"
}

variable "name" {
  description = "Database name"
  type        = string
}

variable "instance_class" {
  description = "Instance class"
  type        = string
}

variable "storage_gib" {
  description = "Allocated storage in GiB"
  type        = number
  default     = 20
}

Ce module est volontairement petit. L’objectif n’est pas de deployer une base MySQL complete, mais de verifier ce que scaffold deduit vraiment d’un module :

les variables obligatoires ;
les variables optionnelles ;
une structure de terragrunt.hcl pre-remplie.

Prerequis du scenario

Avant de lancer scaffold, vous devez avoir :

Terragrunt 1.0.0 installe ;
OpenTofu ou Terraform disponible ;
un depot catalogue initialisé avec Git ;
un repo consommateur avec au moins un root.hcl minimal.

Vous pouvez garder un root.hcl tres simple dans le repo consommateur :

locals {
  environment = "dev"
}

Etape 1 : initialiser le depot catalogue

Dans le dossier terragrunt-catalog-repo, initialisezt un depot Git :

git init
git add .
git commit -m "Initialise le catalogue de modules"

Verification : git status doit indiquer un depot propre avant de passer a l’etape suivante.

Cette etape compte vraiment. Dans cet exemple, scaffold fonctionne bien sur un depot Git local. C’est aussi la forme la plus proche d’un vrai depot de catalogue d’equipe.

Etape 2 : generer une nouvelle unit avec scaffold

Placez-vous dans terragrunt-consumer/live puis lancez :

terragrunt scaffold ../terragrunt-catalog-repo//modules/mysql \
  --output-folder dev/mysql \
  --root-file-name root.hcl \
  --non-interactive \
  --no-hooks \
  --no-shell

Le resultat attendu est la creation du fichier dev/mysql/terragrunt.hcl.

Les options importantes sont les suivantes :

--output-folder indique ou ecrire la nouvelle unit ;
--root-file-name root.hcl aligne la generation sur la convention de ce repo ;
--no-hooks et --no-shell evitent l’execution implicite de templates actifs ;
--non-interactive rend la commande reproductible et plus proche d’un usage automatise.

Etape 3 : verifier le terragrunt.hcl genere

Dans cet exemple, scaffold produit un fichier de cette forme :

# This is a Terragrunt unit generated by Gruntwork Boilerplate (https://github.com/gruntwork-io/boilerplate).
terraform {
  source = "file:///.../terragrunt-catalog-repo//modules/mysql"
}

include "root" {
  path = find_in_parent_folders("root.hcl")
}

inputs = {
  # --------------------------------------------------------------------------------------------------------------------
  # Required input variables
  # --------------------------------------------------------------------------------------------------------------------

  # Description: Database name
  # Type: string
  name = "" # TODO: fill in value

  # Description: Instance class
  # Type: string
  instance_class = "" # TODO: fill in value


  # --------------------------------------------------------------------------------------------------------------------
  # Optional input variables
  # Uncomment the ones you wish to set
  # --------------------------------------------------------------------------------------------------------------------

  # Description: Allocated storage in GiB
  # Type: number
  # storage_gib = 20
}

Ce point est le coeur du guide : Terragrunt lit les variables du module et genere une unit deja structuree, au lieu de vous laisser repartir d’un fichier vide.

Etape 4 : comprendre ce que scaffold apporte vraiment

Le gain n’est pas seulement d’ecrire moins vite un fichier. Le vrai gain est de standardiser trois choses :

la forme du terragrunt.hcl genere ;
l’inclusion racine du repo ;
la visibilite des variables du module, avec types et descriptions.

Autrement dit, scaffold sert moins a faire gagner dix secondes qu’a eviter que chaque nouvelle unit commence avec une structure differente.

Ce que fait catalog au-dessus de scaffold

La commande terragrunt catalog lance une TUI pour parcourir un catalogue de modules. Son role n’est pas de generer des fichiers directement en batch, mais de rendre la decouverte plus simple :

recherche et filtrage dans les modules ;
affichage de la documentation du module selectionne ;
lancement de scaffold quand vous validez un module.

En pratique, catalog est donc une couche de navigation au-dessus du meme mecanisme de generation.

Exemple de configuration d’un catalogue

Terragrunt permet de declarer des URLs de catalogue dans la configuration racine. Un exemple minimal ressemble a ceci :

catalog {
  urls = [
    "../terragrunt-catalog-repo",
  ]
  no_shell = true
  no_hooks = true
}

Avec ce type de configuration, vous pouvez ensuite lancer :

terragrunt catalog --root-file-name root.hcl

La TUI cherchera alors les modules dans les URLs configurees, ou a defaut dans le dossier courant selon les regles de decouverte de Terragrunt.

Industrialiser le pattern

Une fois le mecanisme compris, trois leviers deviennent utiles pour une equipe :

Levier	A quoi il sert
Depot catalogue dedie	Centraliser les modules que l’equipe est autorisee a utiliser
`.boilerplate` dans un module	Fournir un template de unit plus riche que le template par defaut
`default_template` dans `catalog`	Imposer un rendu standard pour plusieurs modules

Le template integre suffit pour debuter. Les templates personnalises deviennent interessants quand vous voulez ajouter automatiquement :

une structure de dossier plus riche ;
des conventions d’include ;
des blocs d’inputs plus opinionated ;
des fichiers annexes generes a cote du terragrunt.hcl.

Le flux minimal a reproduire

Creer le depot catalogue et le committer

Verification : le module modules/mysql/main.tf existe dans un depot Git propre.
Creer un repo consommateur avec live/root.hcl

Verification : root.hcl est bien present avant la generation.
Lancer terragrunt scaffold avec un dossier de sortie dedie

Verification : dev/mysql/terragrunt.hcl apparait.
Relire les inputs generes

Verification : les variables obligatoires sont decommentées, les optionnelles sont commentees.
Activer ensuite catalog seulement si vous avez besoin de navigation

Verification : vous savez que catalog est une couche TUI autour de scaffold, pas un remplacement.

Erreurs frequentes

Symptome	Cause probable	Solution
`scaffold` ecrit au mauvais endroit	Aucun `--output-folder` clair	Toujours cibler un dossier de sortie explicite
Le fichier genere inclut `terragrunt.hcl` au lieu de `root.hcl`	Nom de racine par defaut	Ajouter `--root-file-name root.hcl`
Le template essaye d’executer des actions locales	Hooks ou shell actives	Ajouter `--no-hooks --no-shell`
L’equipe genere des units incoherentes	Chacun part d’un fichier vide	Imposer `scaffold` comme point d’entree standard
Le catalogue n’affiche pas les bons repos	URLs absentes ou mauvaise racine de recherche	Declarer `catalog.urls` ou lancer `catalog` depuis le bon dossier

A retenir

catalog sert surtout a parcourir un catalogue de modules dans une TUI.
scaffold sert a generer un terragrunt.hcl a partir d’un module ou d’un template.
Le flux le plus robuste pour une equipe est souvent : depot catalogue Git + scaffold + conventions de securite.
--root-file-name root.hcl permet d’aligner la generation sur un repo Terragrunt moderne.
--no-hooks et --no-shell sont de bons garde-fous quand vous ne voulez pas executer de templates actifs.

Prochaine etape ?

Nous sommes arrives a la fin de la formation Terragrunt !

D’autres sujets peuvent vous interesser pour aller plus loin :

Structurer un live repo Revenir d'abord a root.hcl et _env si la structure cible du repo n'est pas encore stabilisee.

Stacks implicites ou explicites Voir ensuite comment un catalogue de modules s'insere dans une organisation implicite ou explicite des units.

Terragrunt en CI/CD Prolonger ensuite ce sujet si vous voulez standardiser la creation des units et limiter le blast radius dans les pipelines.