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'équipe invente sa propre structure ? C'est le role de catalog et scaffold. Ce guide vous montre comment les utiliser pour standardiser la création de nouvelles units.

Ce que vous allez apprendre

Comprendre la différence entre catalog (découverte de modules) et scaffold (génération d'une unit)
Générer un terragrunt.hcl propre a partir d'un module avec scaffold
Configurer les garde-fous --no-hooks et --no-shell pour une génération sûre
Industrialiser le pattern avec un dépôt catalogue dédié

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 pièce choisie.

Commande	Role	Quand l'utiliser
`catalog`	Parcourir et sélectionner un module dans une TUI	Découvrir les modules approuves par l'équipe
`scaffold`	Générer un `terragrunt.hcl` pre-rempli a partir d'un module	Créer 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 création 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 ;
écrire automatiquement vos blocs generate existants dans tout le repo ;
refactorer des units déjà presentes.

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

Structure minimale du projet

L'exemple repose sur deux répertoires :

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

Le premier dépôt joue le role de catalogue de modules. Le second dépôt joue le role de repo consommateur dans lequel on veut générer une nouvelle unit.

Le module minimal du dépôt 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 déployer une base MySQL complète, mais de vérifier ce que scaffold déduit vraiment d'un module :

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

Prérequis du scenario

Avant de lancer scaffold, vous devez avoir :

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

Vous pouvez garder un root.hcl très simple dans le repo consommateur :

locals {
  environment = "dev"
}

Etape 1 : initialiser le dépôt catalogue

Dans le dossier terragrunt-catalog-repo, initialisezt un dépôt Git :

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

Verification : git status doit indiquer un dépôt propre avant de passer a l'étape suivante.

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

Etape 2 : générer 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 résultat attendu est la création du fichier dev/mysql/terragrunt.hcl.

Les options importantes sont les suivantes :

--output-folder indique ou écrire la nouvelle unit ;
--root-file-name root.hcl aligne la génération sur la convention de ce repo ;
--no-hooks et --no-shell évitent l'exécution implicite de templates actifs ;
--non-interactive rend la commande reproductible et plus proche d'un usage automatise.

Etape 3 : vérifier 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 déjà structurée, 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'écrire moins vite un fichier. Le vrai gain est de standardiser trois choses :

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

Autrement dit, scaffold sert moins a faire gagner dix secondes qu'a éviter que chaque nouvelle unit commence avec une structure différente.

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 générer des fichiers directement en batch, mais de rendre la découverte 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 même mecanisme de génération.

Exemple de configuration d'un catalogue

Terragrunt permet de déclarer 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 configurées, ou a défaut dans le dossier courant selon les règles de découverte de Terragrunt.

Industrialiser le pattern

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

Levier	A quoi il sert
Dépôt catalogue dédié	Centraliser les modules que l'équipe est autorisée a utiliser
`.boilerplate` dans un module	Fournir un template de unit plus riche que le template par défaut
`default_template` dans `catalog`	Imposer un rendu standard pour plusieurs modules

Le template integre suffit pour debuter. Les templates personnalisés 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 générés a côté du terragrunt.hcl.

Le flux minimal a reproduire

Créer le dépôt catalogue et le committer

Verification : le module modules/mysql/main.tf existe dans un dépôt Git propre.
Créer un repo consommateur avec live/root.hcl

Verification : root.hcl est bien present avant la génération.
Lancer terragrunt scaffold avec un dossier de sortie dédié

Verification : dev/mysql/terragrunt.hcl apparaît.
Relire les inputs générés

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 fréquentes

Symptôme	Cause probable	Solution
`scaffold` écrit 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 défaut	Ajouter `--root-file-name root.hcl`
Le template essaye d'exécuter des actions locales	Hooks ou shell actives	Ajouter `--no-hooks --no-shell`
L'équipe genere des units incoherentes	Chacun part d'un fichier vide	Imposer `scaffold` comme point d'entrée standard
Le catalogue n'affiche pas les bons repos	URLs absentes ou mauvaise racine de recherche	Déclarer `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 générer un terragrunt.hcl a partir d'un module ou d'un template.
Le flux le plus robuste pour une équipe est souvent : dépôt catalogue Git + scaffold + conventions de sécurité.
--root-file-name root.hcl permet d'aligner la génération sur un repo Terragrunt moderne.
--no-hooks et --no-shell sont de bons garde-fous quand vous ne voulez pas exécuter 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 création des units et limiter le blast radius dans les pipelines.