Terragrunt : stacks implicites ou explicites ?

Vous avez vu des mentions de “stacks” dans Terragrunt, mais vous ne savez pas si vous devez utiliser l’approche implicite ou explicite ? La reponse depend de la taille de votre repo et de votre besoin de reutilisation.

Cette page compare les deux approches sur un meme module minimal pour que vous puissiez les tester et choisir en connaissance de cause.

Ce que vous allez apprendre

• Comprendre la difference entre stack implicite et stack explicite
• Reproduire les deux approches sur un meme module minimal
• Choisir le bon point de depart selon la taille de votre repo
• Savoir quand passer de l’une a l’autre

Analogie : menu a la carte ou formule

Imaginez un restaurant. La stack implicite c’est choisir vos plats a la carte : chaque dossier (unit) est independant, vous composez votre repas librement. La stack explicite c’est une formule : un fichier unique decrit la composition entiere — entree, plat, dessert — et le serveur genere le tout pour vous.

Recommandation rapide

Commencez par cette regle simple :

Votre besoin	Point de depart recommande
Quelques units rangees naturellement par dossiers	Stack implicite
Une composition reutilisable de plusieurs units	Stack explicite
Un repo encore debutant, peu de repetition	Stack implicite
Un modele a generer plusieurs fois avec des valeurs differentes	Stack explicite

Glissez pour voir

Le module commun aux deux approches

Pour comparer les deux approches sans bruit, on reutilise exactement le meme module Terraform ou OpenTofu dans les deux cas. Placez-le dans modules/write-file/main.tf :

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 resultat observe est simple : chaque unit cree un fichier local avec un nom et un contenu differents.

Cas 1 : stack implicite

Dans une stack implicite, c’est l’arborescence qui raconte la composition. Terragrunt parcourt les dossiers deployables et construit sa logique a partir de la structure et, si besoin, des dependances declarees.

Structure minimale

• Répertoirelab-implicit/

  • Répertoiremodules/

    • Répertoirewrite-file/

      • main.tf
  • Répertoirelive/

    • root.hcl
    • Répertoire_env/

      • write-file.hcl
    • Répertoiredev/

      • Répertoirefoo/

        • terragrunt.hcl
      • Répertoirebar/

        • terragrunt.hcl

Fichiers a creer

Fichier live/root.hcl :

locals {
  stack_name = "dev"
}

Fichier live/_env/write-file.hcl :

locals {
  module_source = "${dirname(find_in_parent_folders("root.hcl"))}/../modules/write-file"
}

inputs = {
  content_prefix = "hello"
}

Fichier live/dev/foo/terragrunt.hcl :

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

include "env" {
  path   = "${get_terragrunt_dir()}/../../_env/write-file.hcl"
  expose = true
}

terraform {
  source = include.env.locals.module_source
}

inputs = {
  filename = "${get_terragrunt_dir()}/foo.txt"
  content  = "${include.env.inputs.content_prefix} from foo in ${include.root.locals.stack_name}"
}

Fichier live/dev/bar/terragrunt.hcl :

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

include "env" {
  path   = "${get_terragrunt_dir()}/../../_env/write-file.hcl"
  expose = true
}

terraform {
  source = include.env.locals.module_source
}

inputs = {
  filename = "${get_terragrunt_dir()}/bar.txt"
  content  = "${include.env.inputs.content_prefix} from bar in ${include.root.locals.stack_name}"
}

Ce que vous devez lancer

1. Creer les fichiers du live repo

   Verification : vous avez bien root.hcl, _env/write-file.hcl, puis deux units foo et bar.

2. Vous placer dans live/dev

   Puis lancer :

   terragrunt run --all apply

   Verification : foo/foo.txt contient hello from foo in dev et bar/bar.txt contient hello from bar in dev.

3. Nettoyer

   terragrunt run --all destroy

   Verification : les deux fichiers ont disparu.

Cas 2 : stack explicite

Dans une stack explicite, vous ne laissez plus uniquement l’arborescence porter la composition. Vous declarez la liste des units dans un fichier terragrunt.stack.hcl.

Structure minimale

• Répertoirelab-explicit/

  • Répertoiremodules/

    • Répertoirewrite-file/

      • main.tf
  • Répertoirestacks/

    • Répertoiredev/

      • terragrunt.stack.hcl
  • Répertoireunits/

    • Répertoirewrite-file-unit/

      • terragrunt.hcl

Fichiers a creer

Fichier units/write-file-unit/terragrunt.hcl :

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

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

Fichier stacks/dev/terragrunt.stack.hcl :

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"
  }
}

Ce que vous devez lancer

1. Vous placer dans stacks/dev

   Puis lancer :

   terragrunt stack generate

   Verification : deux dossiers app et worker apparaissent avec leurs fichiers terragrunt.hcl.

2. Appliquer la stack

   terragrunt run --all apply

   Verification : app/stack-app.txt contient hello from explicit stack app et worker/stack-worker.txt contient hello from explicit stack worker.

3. Nettoyer

   terragrunt run --all destroy

   Verification : les deux fichiers ont disparu.

La vraie difference entre les deux

Aspect	Stack implicite	Stack explicite
Source de verite	L’arborescence du repo	Le fichier terragrunt.stack.hcl
Mise en route	Plus simple au debut	Plus structuree
Generation de units	Manuelle	Automatique via stack generate
Lisibilite sur petit repo	Excellente	Parfois excessive
Reutilisation d’une composition	Limitee	Plus forte

Glissez pour voir

Quand choisir l’une ou l’autre

• Choisissez la stack implicite si votre repo reste lisible naturellement par dossiers et que vous voulez avancer sans sur-architecture.
• Choisissez la stack explicite si vous voulez decrire, generer et rejouer plusieurs units comme un bloc coherent et reutilisable.

Le bon point de depart

Pour un debutant, la meilleure strategie reste souvent : commencer en stack implicite, puis passer a une stack explicite quand la composition elle-meme devient un objet a maintenir.

Erreurs frequentes

Symptome	Cause probable	Solution
Le repo implicite devient confus	Trop de logique est dispersee dans les dossiers	Revenir a root.hcl, _env et des units plus lisibles
stack generate ne cree rien	Mauvais source ou mauvais chemin	Verifier terragrunt.stack.hcl et le dossier courant
Une stack explicite semble trop lourde	Le repo est encore trop simple	Revenir a une stack implicite

Glissez pour voir

A retenir

• Une stack implicite s’appuie surtout sur l’arborescence du repo.
• Une stack explicite decrit la composition dans terragrunt.stack.hcl.
• Les deux approches peuvent reutiliser exactement le meme module.
• Commencez simple, puis montez en explicite quand la composition devient un vrai sujet.
• Le bon choix depend moins de l’outil que de la taille et de la forme du repo.

Prochaine etape

terragrunt.stack.hcl Approfondir ensuite la variante explicite si vous voulez aller plus loin sur les blocs unit et values.

×

📖 Voir la documentation →