Premier projet Terragrunt : votre premier unit

Vous avez installe Terragrunt et vous voulez voir concretement 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 resultat observable, puis un destroy pour revenir a un etat 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 designe simplement un dossier deployable qui contient un terragrunt.hcl.

Ce que vous allez apprendre

• Creer un premier unit Terragrunt fonctionnel
• Comprendre le role de terraform.source et des inputs
• Lancer un apply, verifier le resultat puis detruire proprement
• Poser la base du raisonnement Terragrunt : un module, plusieurs instanciations

Ce guide part volontairement petit

Le premier contact avec Terragrunt doit rester lisible. On ne commence pas par un gros live repo ni par un backend distant. On commence par un unit simple, pour voir le role exact de terragrunt.hcl.

Vocabulaire minimal

Avant de lancer le premier apply, gardez ces trois definitions en tete :

• 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.

Analogie : la recette et les ingredients

Pensez au module comme une recette de cuisine et au unit comme la commande d’un plat en restaurant. La recette est ecrite une fois, mais chaque table peut demander des quantites ou des variantes differentes. C’est exactement le role de terragrunt.hcl : il dit quel module utiliser et avec quelles valeurs.

Prerequis

Avant de lancer le scenario, vous devez avoir :

• OpenTofu ou Terraform installe ;
• Terragrunt installe ;
• un module deja ecrit, meme minimal ;
• un terminal dans lequel vous pouvez executer 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, creez 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 creer 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 ecrit un fichier local avec un nom et un contenu fournis en entree. Il est parfait pour un premier projet parce que le resultat est immediatement 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	Concretement
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’execution
get_terragrunt_dir()	Donne le dossier du unit courant	Le fichier cree se retrouve a cote du terragrunt.hcl, pas ailleurs

Glissez pour voir

Le point important est simple : Terragrunt ne cree pas ici une nouvelle resource. Il pilote un module deja existant et lui passe des entrees.

Etapes de validation

1. Creer le module puis le fichier terragrunt.hcl

   Creez 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.

2. Lancer l’apply

   Placez-vous dans le dossier live/dev/app puis executez :

   terragrunt apply

   Verification : Terragrunt doit initialiser l’engine, resoudre le module, puis annoncer la creation de la ressource attendue.

3. Verifier le resultat observable

   Dans notre exemple, l’apply cree un fichier hello.txt a cote du unit.

   cat hello.txt

   Verification : le contenu attendu est hello from lab a.

4. Detruire proprement

   Quand le test est termine, revenez a un etat propre :

   terragrunt destroy

   Verification : le fichier cree pendant l’apply ne doit plus etre present.

Ce que Terragrunt ajoute deja ici

Sur ce premier exemple, le gain ne saute pas toujours aux yeux. Pourtant, plusieurs idees utiles sont deja en place :

• le module reste separe du unit qui l’instancie ;
• les valeurs d’entree vivent dans terragrunt.hcl plutot que dans un bloc module du code racine ;
• la meme source peut ensuite etre rejouee pour plusieurs units avec des inputs differents.

Autrement dit, le premier unit pose deja la base du raisonnement Terragrunt : un meme motif reutilisable, plusieurs instanciations organisees proprement.

Erreurs frequentes

Symptome	Cause probable	Solution
source introuvable	Le chemin du module est faux	Verifier le chemin reel depuis le dossier du unit
Le fichier se cree dans un endroit inattendu	filename utilise un chemin mal resolu	Utiliser get_terragrunt_dir()
terragrunt apply redemande toujours une init lourde	Le cache a ete nettoye ou la source a change	Rejouer normalement, c’est attendu dans ce cas

Glissez pour voir

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 dependances 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.

×

📖 Voir la documentation →