Utiliser terragrunt.stack.hcl pour une stack explicite

Comment deployer plusieurs units d’un coup sans gerer chaque dossier a la main ? Une stack explicite Terragrunt permet de decrire plusieurs units dans un fichier unique terragrunt.stack.hcl, puis de generer les dossiers et les terragrunt.hcl correspondants. Cette approche devient utile quand vous voulez reproduire une composition complete de composants de maniere previsible.

Ce que vous allez apprendre

Comprendre le role d’un fichier terragrunt.stack.hcl et sa syntaxe
Generer des units app et worker depuis une stack explicite avec terragrunt stack generate
Maitriser le cycle complet generate → apply → destroy sur une stack
Savoir quand choisir une stack explicite plutot qu’une arborescence implicite

Ce guide s’appuie sur un exemple avec deux units : app et worker.

Quand une stack explicite devient interessante

Une arborescence implicite suffit souvent pour debuter. En revanche, une stack explicite devient interessante quand vous voulez :

decrire une composition reutilisable de plusieurs units ;
generer ces units depuis un modele commun ;
centraliser les valeurs injectees dans chaque unit ;
rendre la relation entre les composants plus evidente.

Structure minimale du projet

Pour reproduire la stack explicite, creez cette arborescence :

Répertoirelab-f/
- Répertoiremodules/
  - Répertoirewrite-file/
    main.tf
- Répertoirestacks/
  - Répertoiredev/
    terragrunt.stack.hcl
- Répertoireunits/
  - Répertoirewrite-file-unit/
    terragrunt.hcl

Le module reutilisable

Le module reutilise ici reste le meme :

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    local = {
      source  = "hashicorp/local"
      version = "~> 2.5"
    }
  }
}

variable "filename" {
  type = string
}

variable "content" {
  type = string
}

resource "local_file" "this" {
  filename = var.filename
  content  = var.content
}

output "file_path" {
  value = local_file.this.filename
}

output "content" {
  value = local_file.this.content
}

Le fichier terragrunt.stack.hcl

Voici la forme recommandee :

unit "app" {
  source                  = "../../units/write-file-unit"
  path                    = "app"
  no_dot_terragrunt_stack = true
  values = {
    filename = "stack-app.txt"
    content  = "hello from explicit stack app"
  }
}

unit "worker" {
  source                  = "../../units/write-file-unit"
  path                    = "worker"
  no_dot_terragrunt_stack = true
  values = {
    filename = "stack-worker.txt"
    content  = "hello from explicit stack worker"
  }
}

Comment lire ce fichier

Element	Role
`unit "app"`	Declare une unit a generer
`source`	Pointe vers le modele de unit
`path`	Definit le dossier de sortie
`values`	Injecte les valeurs propres a la unit
`no_dot_terragrunt_stack = true`	Genere directement dans le dossier courant plutot que sous `.terragrunt-stack`

Le modele utilise par les deux units est ensuite un terragrunt.hcl simple qui relit values.filename et values.content.

Voici le contenu exact de units/write-file-unit/terragrunt.hcl :

terraform {
  source = "../../modules/write-file"
}

inputs = {
  filename = "${get_terragrunt_dir()}/${values.filename}"
  content  = values.content
}

Le cycle de travail

La sequence a suivre est toujours la meme :

Generer les units
Fenêtre de terminal
```
terragrunt stack generate
```
Verification : les dossiers app et worker apparaissent avec leurs fichiers terragrunt.hcl.
Appliquer la stack
Fenêtre de terminal
```
terragrunt run --all apply
```
Verification : stack-app.txt et stack-worker.txt sont bien crees avec le contenu attendu.
Detruire la stack
Fenêtre de terminal
```
terragrunt run --all destroy
```
Verification : les deux units sont nettoyees proprement.

Resultat attendu

Ce scenario confirme que :

la stack genere bien les units attendues ;
chaque unit recupere les values qui lui sont propres ;
le cycle stack generate -> run --all apply -> run --all destroy reste previsible ;
une composition explicite de deux units peut etre reproduite sans intervention manuelle sur chaque dossier.

Stack implicite ou stack explicite ?

La bonne reponse depend du besoin :

Cas	Meilleur point de depart
Quelques units rangees proprement par dossiers	Stack implicite
Composition reutilisable de plusieurs units	Stack explicite
Besoin de generer plusieurs units depuis un modele	Stack explicite

Erreurs frequentes

Symptome	Cause probable	Solution
`stack generate` ne cree rien	Mauvais `source` ou syntaxe du bloc `unit`	Revoir le chemin et la declaration des units
Les units generees ecrivent le mauvais fichier	`values` mal passes ou mal relus	Verifier `values.filename` et `values.content`
Le repo devient plus confus qu’avant	Stack explicite introduite trop tot	Revenir a une structure implicite plus simple

A retenir

terragrunt.stack.hcl sert a declarer une composition explicite de plusieurs units.
stack generate cree ensuite les units a partir du modele defini.
Les values permettent de parametrer chaque unit sans dupliquer la logique du modele.
Une stack explicite est utile quand vous voulez reproduire une composition complete de composants.
Si votre repo reste simple, une arborescence implicite peut encore suffire.

Prochaines etapes

Terragrunt Catalog et Scaffold Voir ensuite comment reutiliser une composition de units dans un catalogue pour la rendre encore plus accessible et partageable.