Deboguer Terragrunt : cache, chemins relatifs, hooks et logs

Votre terragrunt apply echoue et le message d’erreur ne vous aide pas ? Avant de modifier votre code, il faut comprendre ou Terragrunt travaille reellement. Le probleme ne vient pas toujours du module Terraform ou OpenTofu : tres souvent, il vient du dossier de travail reel, du cache, d’un chemin relatif mal pense ou d’un manque de logs. Ce guide vous donne une methode reproductible pour diagnostiquer ces situations.

Ce que vous allez apprendre

Comment fonctionne .terragrunt-cache et pourquoi Terragrunt n’execute pas depuis votre dossier source
Utiliser terragrunt info print pour voir le contexte reel d’execution
Activer les logs de debug avec --log-level debug pour comprendre ce que Terragrunt fait
Appliquer les bons reflexes pour les chemins relatifs et les hooks

L’exemple minimal a reproduire

On repart volontairement d’un seul unit, pour isoler les mecanismes de debug.

Répertoirelab-debug/
- Répertoiremodules/
  - Répertoirewrite-file/
    main.tf
- Répertoirelive/
  - Répertoiredev/
    Répertoireapp/
    terragrunt.hcl

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

Fichier live/dev/app/terragrunt.hcl :

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

inputs = {
  filename = "${get_terragrunt_dir()}/hello.txt"
  content  = "hello from lab a"
}

Etape 1 : provoquer un run simple

Placez-vous dans live/dev/app puis lancez :

terragrunt --non-interactive apply -auto-approve

Le resultat attendu est double :

hello.txt apparait dans le dossier du unit ;
un dossier .terragrunt-cache apparait aussi.

Ce point est fondamental : Terragrunt n’execute pas directement depuis votre dossier source. Il prepare un repertoire de travail intermediaire.

Etape 2 : demander a Terragrunt ce qu’il utilise vraiment

La commande la plus utile pour commencer est :

terragrunt info print

Elle renvoie notamment :

config_path : le terragrunt.hcl charge ;
download_dir : le chemin de .terragrunt-cache ;
working_dir : le dossier reel depuis lequel Terragrunt execute le module.

Autrement dit, cette commande vous dit ou Terragrunt travaille vraiment, au lieu de vous laisser raisonner uniquement depuis le dossier visible dans le repo.

Etape 3 : regarder le cache au lieu de le subir

Vous pouvez voir la structure du cache avec :

find .terragrunt-cache -maxdepth 3 | sort

Vous y retrouvez typiquement :

le main.tf du module ;
le terragrunt.hcl recopie dans le repertoire de travail ;
le state local si vous travaillez sans backend distant ;
les dossiers .terraform et les manifestes Terragrunt.

Le cache n’est donc pas un bruit parasite. C’est le lieu concret de l’execution.

Etape 4 : activer des logs utiles

Pour enrichir le diagnostic sans modifier votre code, lancez :

terragrunt --log-level debug info print

Sur Terragrunt 1.0.0, cette commande montre notamment :

la version de Terragrunt ;
le binaire Terraform ou OpenTofu detecte ;
la lecture du fichier terragrunt.hcl ;
le moment ou le working directory est defini dans le cache.

Etape 5 : comprendre les chemins relatifs

Le point le plus piegeux est simple : Terragrunt execute le module depuis le working directory du cache, pas depuis votre dossier visible.

Cela explique pourquoi cette ligne est importante :

filename = "${get_terragrunt_dir()}/hello.txt"

get_terragrunt_dir() ancre le chemin sur le dossier du unit. Sans cette precaution, un chemin ecrit en supposant un autre dossier courant peut viser le mauvais emplacement.

Sur un repo plus structure, le meme principe vaut aussi pour les sources de modules. Au lieu de raisonner “depuis la ou la commande est lancee”, ancrez les chemins depuis un repere stable comme :

get_terragrunt_dir() pour le dossier courant du unit ;
find_in_parent_folders("root.hcl") pour retrouver une racine connue.

Etape 6 : nettoyer le cache quand il brouille le diagnostic

Si vous voulez repartir proprement, utilisez une commande simple :

find . -type d -name '.terragrunt-cache' -prune -exec rm -rf {} +

Cette commande ne corrige pas la cause racine, mais elle elimine un etat local qui peut masquer le vrai probleme pendant l’analyse.

Et les hooks ?

Les hooks Terragrunt ne sont pas detailles dans cet exemple, mais les bons reflexes restent les memes quand un hook casse :

verifier d’abord le working_dir avec terragrunt info print ;
activer --log-level debug pour voir quand Terragrunt prepare l’execution ;
eviter les chemins ambigus dans les scripts de hook ;
faire en sorte qu’un hook affiche ses erreurs clairement et reste idempotent.

Le flux minimal a reproduire

Appliquer le unit
Fenêtre de terminal
```
terragrunt --non-interactive apply -auto-approve
```
Verification : hello.txt et .terragrunt-cache existent.
Afficher le contexte Terragrunt
Fenêtre de terminal
```
terragrunt info print
```
Verification : la sortie contient config_path, download_dir et working_dir.
Activer les logs de debug
Fenêtre de terminal
```
terragrunt --log-level debug info print
```
Verification : vous voyez la lecture du terragrunt.hcl et la definition du working directory.

Lister puis nettoyer le cache

find .terragrunt-cache -maxdepth 3 | sort
find . -type d -name '.terragrunt-cache' -prune -exec rm -rf {} +

Verification : le cache est d’abord visible, puis supprime.

Detruire proprement le unit
Fenêtre de terminal
```
terragrunt --non-interactive destroy -auto-approve
```
Verification : hello.txt disparait.

Erreurs frequentes

Symptome	Cause probable	Solution
Le module semble s’executer dans un dossier incomprehensible	Terragrunt travaille dans `.terragrunt-cache`	Utiliser `terragrunt info print`
Un chemin relatif fonctionne mal	Le chemin suppose un mauvais dossier courant	Repartir de `get_terragrunt_dir()` ou d’une racine stable
Les logs sont trop pauvres	Niveau par defaut trop bas	Relancer avec `--log-level debug`
Le comportement reste bizarre apres plusieurs essais	Etat local parasite dans le cache	Supprimer `.terragrunt-cache` puis recommencer

A retenir

.terragrunt-cache est le vrai lieu d’execution de Terragrunt.
terragrunt info print est le premier diagnostic a lancer.
--log-level debug permet de voir le contexte Terragrunt sans improviser.
Les chemins relatifs doivent etre ancres sur des reperes stables.
Pour les hooks aussi, le bon debug commence par le contexte et les chemins.

Prochaine etape

Utiliser terragrunt.stack.hcl pour une stack explicite