Utiliser terragrunt.stack.hcl pour une stack explicite

Comment déployer plusieurs units d'un coup sans gérer chaque dossier a la main ? Une stack explicite Terragrunt permet de décrire plusieurs units dans un fichier unique terragrunt.stack.hcl, puis de générer les dossiers et les terragrunt.hcl correspondants. Cette approche devient utile quand vous voulez reproduire une composition complète de composants de manière prévisible.

Ce que vous allez apprendre

Comprendre le role d'un fichier terragrunt.stack.hcl et sa syntaxe
Générer des units app et worker depuis une stack explicite avec terragrunt stack generate
Maîtriser le cycle complet generate → apply → destroy sur une stack
Savoir quand choisir une stack explicite plutôt 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 :

décrire une composition reutilisable de plusieurs units ;
générer ces units depuis un modèle commun ;
centraliser les valeurs injectées dans chaque unit ;
rendre la relation entre les composants plus évidente.

Structure minimale du projet

Pour reproduire la stack explicite, créez 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 même :

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 recommandée :

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

Élément	Role
`unit "app"`	Declare une unit a générer
`source`	Pointe vers le modèle de unit
`path`	Définit le dossier de sortie
`values`	Injecte les valeurs propres a la unit
`no_dot_terragrunt_stack = true`	Genere directement dans le dossier courant plutôt que sous `.terragrunt-stack`

Le modèle 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 même :

Générer 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 créés avec le contenu attendu.
Detruire la stack
Fenêtre de terminal
```
terragrunt run --all destroy
```
Verification : les deux units sont nettoyees proprement.

Résultat 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 prévisible ;
une composition explicite de deux units peut être reproduite sans intervention manuelle sur chaque dossier.

Stack implicite ou stack explicite ?

La bonne réponse dépend du besoin :

Cas	Meilleur point de départ
Quelques units rangees proprement par dossiers	Stack implicite
Composition reutilisable de plusieurs units	Stack explicite
Besoin de générer plusieurs units depuis un modèle	Stack explicite

Erreurs fréquentes

Symptôme	Cause probable	Solution
`stack generate` ne cree rien	Mauvais `source` ou syntaxe du bloc `unit`	Revoir le chemin et la déclaration des units
Les units générées écrivent le mauvais fichier	`values` mal passes ou mal relus	Vérifier `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 déclarer une composition explicite de plusieurs units.
stack generate cree ensuite les units a partir du modèle défini.
Les values permettent de parametrer chaque unit sans dupliquer la logique du modèle.
Une stack explicite est utile quand vous voulez reproduire une composition complète de composants.
Si votre repo reste simple, une arborescence implicite peut encore suffire.

Prochaines étapes

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