Premier projet Terragrunt : votre premier unit

Vous avez installe Terragrunt et vous voulez voir concrètement a quoi ressemble un premier fichier terragrunt.hcl ? Ce guide vous montre le plus petit scenario utile : un module minimal, un fichier de configuration Terragrunt, un apply qui produit un résultat observable, puis un destroy pour revenir a un état propre.

L'objectif n'est pas encore de traiter les includes, la run queue ou les stacks, mais de comprendre ce que Terragrunt ajoute des le premier unit. Ici, un unit désigne simplement un dossier deployable qui contient un terragrunt.hcl.

Ce que vous allez apprendre

Créer un premier unit Terragrunt fonctionnel
Comprendre le role de terraform.source et des inputs
Lancer un apply, vérifier le résultat puis detruire proprement
Poser la base du raisonnement Terragrunt : un module, plusieurs instanciations

Vocabulaire minimal

Avant de lancer le premier apply, gardez ces trois definitions en tête :

un module contient le code reutilisable Terraform ou OpenTofu ;
un unit est un dossier qui instancie ce module avec ses propres valeurs ;
un live repo est l'ensemble de ces units quand le projet grandit.

Prérequis

Avant de lancer le scenario, vous devez avoir :

OpenTofu ou Terraform installe ;
Terragrunt installe ;
un module déjà écrit, même minimal ;
un terminal dans lequel vous pouvez exécuter terragrunt apply.

Si Terragrunt n'est pas encore installe sur votre poste, commencez par Installer Terragrunt.

Si les bases Terraform restent encore floues, revenez d'abord sur Terraform et sur le hub Terragrunt.

Structure minimale du projet

Si vous voulez reproduire ce scenario de zero, créez cette arborescence :

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

Le principe est simple :

modules/write-file contient le code Terraform ou OpenTofu ;
live/dev/app contient la unit Terragrunt qui appelle ce module.

Code du module

Commencez par créer le module reutilisable 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
}

Ce module est volontairement minimal : il écrit un fichier local avec un nom et un contenu fournis en entrée. Il est parfait pour un premier projet parce que le résultat est immédiatement observable.

Ce que contient un premier unit

Un unit Terragrunt est simplement un dossier qui contient un fichier terragrunt.hcl. Ce fichier ne remplace pas votre module Terraform ou OpenTofu. Il indique surtout :

quelle source de module utiliser ;
quelles valeurs injecter dans ce module ;
dans certains cas, quelles conventions de backend, de provider ou d'orchestration appliquer.

Pour un tout premier test, un unit minimal ressemble a ceci :

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

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

Comment lire ce fichier

Voici ce que fait chaque bloc :

Bloc	Role	Concrètement
`terraform.source`	Pointe vers le module a instancier	Terragrunt copie ce module dans son cache de travail puis lance l'engine IaC
`inputs`	Passe les valeurs au module	Les variables `filename` et `content` sont resolues avant l'exécution
`get_terragrunt_dir()`	Donne le dossier du unit courant	Le fichier cree se retrouve a côté du `terragrunt.hcl`, pas ailleurs

Le point important est simple : Terragrunt ne cree pas ici une nouvelle resource. Il pilote un module déjà existant et lui passe des entrées.

Étapes de validation

Créer le module puis le fichier terragrunt.hcl

Créez d'abord modules/write-file/main.tf, puis ajoutez le fichier live/dev/app/terragrunt.hcl avec le contenu montre plus haut.

Verification : votre arborescence doit contenir exactement un module et une unit.
Lancer l'apply

Placez-vous dans le dossier live/dev/app puis exécutez :
Fenêtre de terminal
```
terragrunt apply
```
Verification : Terragrunt doit initialiser l'engine, résoudre le module, puis annoncer la création de la ressource attendue.
Vérifier le résultat observable

Dans notre exemple, l'apply cree un fichier hello.txt a côté du unit.
Fenêtre de terminal
```
cat hello.txt
```
Verification : le contenu attendu est hello from lab a.
Detruire proprement

Quand le test est termine, revenez a un état propre :
Fenêtre de terminal
```
terragrunt destroy
```
Verification : le fichier cree pendant l'apply ne doit plus être present.

Ce que Terragrunt ajoute déjà ici

Sur ce premier exemple, le gain ne saute pas toujours aux yeux. Pourtant, plusieurs idées utiles sont déjà en place :

le module reste separe du unit qui l'instancie ;
les valeurs d'entrée vivent dans terragrunt.hcl plutôt que dans un bloc module du code racine ;
la même source peut ensuite être rejouee pour plusieurs units avec des inputs différents.

Autrement dit, le premier unit pose déjà la base du raisonnement Terragrunt : un même motif reutilisable, plusieurs instanciations organisees proprement.

Erreurs fréquentes

Symptôme	Cause probable	Solution
`source` introuvable	Le chemin du module est faux	Vérifier le chemin réel depuis le dossier du unit
Le fichier se cree dans un endroit inattendu	`filename` utilise un chemin mal résolu	Utiliser `get_terragrunt_dir()`
`terragrunt apply` redemande toujours une init lourde	Le cache a été nettoyé ou la source a change	Rejouer normalement, c'est attendu dans ce cas

A retenir

Un unit Terragrunt est un dossier avec un fichier terragrunt.hcl.
Le bloc terraform.source indique quel module instancier.
Le bloc inputs fournit les valeurs a ce module.
Terragrunt ne remplace pas votre module, il l'orchestre.
Ce premier scenario sert de base aux guides sur le live repo, les dépendances et la run queue.

Prochaine étape

Structurer un live repo Passer ensuite d'un unit isole a une structure root.hcl, _env et plusieurs units coherents.