Organiser un dépôt Terraform

Un dépôt Terraform bien rangé se lit en quelques secondes : on sait où sont les variables, où est le backend, ce qui est versionné. Le découpage qui y mène est simple, mais il traîne deux idées fausses tenaces, celle du nom de fichier « standard » qui n'est pas celui de la documentation, et celle du découpage sans risque parce que terraform validate passe.

Tout ce qui suit a été exécuté sur Terraform v1.15.4 : sorties, codes de retour et verdicts de git check-ignore compris.

Ce que vous allez apprendre

• Le socle de fichiers que la documentation nomme, et ceux qu'elle ignore
• Comment prouver qu'un découpage n'a rien changé, puisque validate ne le fait pas
• Le seul nom de fichier qui ait un effet fonctionnel
• Pourquoi -recursive décide de la valeur de votre contrôle de formatage
• Le motif de .gitignore que presque tout le monde rate

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform).
• Une configuration qui fonctionne, même monolithique : ce guide range, il ne réécrit pas.

Le socle de fichiers, et les noms qui surprennent

Terraform charge tous les .tf d'un répertoire et les traite comme un seul document. Aucun nom n'est donc imposé par le moteur, ce qui rend d'autant plus utile de suivre la convention publiée plutôt que la sienne. Le style guide officiel nomme ceci :

Fichier	Ce qu'il contient
terraform.tf	un seul bloc terraform : required_version, required_providers
providers.tf	tous les blocs provider, dont une configuration par défaut
variables.tf	tous les variable, en ordre alphabétique
outputs.tf	tous les output, en ordre alphabétique
main.tf	les resource et les data source
backend.tf	la configuration du backend, quand il y en a une
locals.tf	les valeurs locales, si elles deviennent nombreuses

Glissez pour voir

Deux surprises pour beaucoup de lecteurs. Le nom versions.tf, très répandu, n'apparaît nulle part dans la documentation : celui qui y figure est terraform.tf. Et le bloc provider a son fichier, il ne partage pas celui du bloc terraform.

Un socle, pas une obligation

La doc recommande ces fichiers « even if they're empty », et autorise explicitement le regroupement par domaine (network.tf, storage.tf) quand la base de code grossit. Ce qui compte est la prévisibilité : un lecteur doit trouver sans chercher.

Le seul nom de fichier qui ait un effet

Il existe une exception à « les noms sont cosmétiques », et elle est rarement énoncée : override.tf, override.tf.json et tout fichier terminé par _override.tf. Terraform les charge en dernier et fusionne leur contenu par-dessus les blocs existants.

Ce n'est pas un fichier généré, contrairement à ce qu'on lit parfois : le style guide le range parmi les fichiers du module. Il sert à surcharger localement, et c'est précisément pour cela qu'on l'exclut souvent du dépôt.

Découper sans changer le plan

Voici le point que la plupart des guides ratent. terraform validate ne prouve pas qu'un découpage est neutre :

The validate command does not check if argument values are valid for a specific provider, but it will verify that they are the correct type. It does not evaluate any existing state.

Mesuré sur un découpage où une ressource et sa sortie ont disparu :

Success! The configuration is valid, but there were some validation warnings

La configuration est valide, et le plan n'a plus rien à voir. La seule preuve d'invariance est la comparaison de deux plans :

1. Avant de toucher au code, enregistrer le plan de référence :

   terraform plan -out=avant.tfplan
   terraform show -json avant.tfplan > avant.json

2. Découper, en déplaçant les blocs sans les réécrire.

3. Rejouer le plan, et comparer ce qui doit être stable :

   terraform plan -out=apres.tfplan
   terraform show -json apres.tfplan > apres.json
   
   diff <(jq -S '.planned_values, .resource_changes' avant.json) \
        <(jq -S '.planned_values, .resource_changes' apres.json)

La section configuration du JSON, elle, change légitimement : c'est la représentation du code, qui reflète le découpage. Ce sont planned_values, resource_changes et output_changes qui doivent rester identiques.

Le diff est le contrôle, pas le sentiment

Un découpage se fait en déplaçant des blocs, jamais en les retapant. Et il se contrôle par un diff de plans, pas par la conviction d'avoir tout recopié : c'est exactement le genre de tâche où l'attention faiblit à la quatrième ressource.

Formater toute l'arborescence

terraform fmt -check ne regarde que le répertoire courant. Sur un dépôt à plusieurs niveaux, c'est un contrôle qui rassure sans rien vérifier.

terraform fmt -check -recursive

La documentation nomme l'option pour ce cas : « The terraform fmt command can use the -recursive flag for subdirectories. » Deux réflexes pour l'intégration continue : toujours -recursive, et tester un code de retour différent de zéro plutôt qu'égal à 1, puisque -check sort en 3 quand un fichier doit être reformaté.

Terraform n'embarque par ailleurs aucun linter : fmt met en forme, validate vérifie la cohérence interne, et les règles d'équipe relèvent d'un outil séparé, TFLint en tête.

Le .gitignore, et le piège du plan enregistré

Trois familles ne se committent jamais, et une doit toujours l'être :

Fichier	Versionné ?
.terraform/	non, répertoire de travail
terraform.tfstate, *.tfstate.backup	non, l'état contient les valeurs
un plan enregistré par -out=	non, il contient les valeurs résolues
.terraform.lock.hcl	oui, toujours

Glissez pour voir

Le piège tient au nom du plan enregistré :

terraform plan -out=tfplan

Ce fichier n'a aucune extension. Un .gitignore qui ne connaît que *.tfplan ne l'attrape pas, et le fichier contient les valeurs résolues, secrets compris. Le motif doit donc couvrir les deux formes :

.terraform/
*.tfstate
*.tfstate.*

tfplan
*.tfplan

!.terraform.lock.hcl

Enfin, un .gitignore ne se vérifie pas en le lisant, mais en le faisant travailler :

git check-ignore -v projet/tfplan projet/terraform.tfstate
git check-ignore projet/.terraform.lock.hcl && echo "PROBLEME : le verrou est ignore"

Ranger un dépôt qui contient des modules

Un module vit sous modules/<nom>/, et il porte son socle, README.md compris : la doc attache une conséquence à ce fichier, « nested modules with a README are considered publicly usable, those without are internal-only ». Un module sans README est donc déclaré interne, ce qui est rarement l'intention.

Les exemples d'usage vont sous examples/, avec une règle propre : leur source doit pointer l'adresse externe du module, pas un chemin relatif, puisqu'ils sont faits pour être recopiés ailleurs. Et l'appel d'un module imbriqué depuis la racine se fait par un chemin relatif, ./modules/reseau, ce qui le garde dans le même paquet que son appelant.

depot/
├── terraform.tf
├── providers.tf
├── variables.tf
├── outputs.tf
├── main.tf
├── .gitignore
├── modules/
│   └── reseau/
│       ├── README.md
│       ├── main.tf
│       ├── variables.tf
│       └── outputs.tf
└── examples/
    └── minimal/
        └── main.tf

Trois environnements, trois states

Des répertoires envs/dev, envs/staging et envs/prod ne sont pas trois dossiers, ce sont trois configurations racine, donc trois states indépendants. Une racine ne lit une valeur d'une autre que par les outputs de son état distant, sujet traité dans séparer dev, staging et prod.

Dépannage

Symptôme	Cause probable	Correction
le plan change après un découpage	un bloc perdu ou une valeur déplacée	comparer les deux JSON, validate ne le dira pas
la CI est verte, le code est mal formaté	fmt -check sans -recursive	ajouter l'option, tester un code non nul
un plan enregistré part dans un commit	motif *.tfplan seul	ajouter tfplan, sans extension
.terraform.lock.hcl absent du dépôt	motif trop large sur .terraform*	ajouter !.terraform.lock.hcl
une surcharge locale part dans le dépôt	override.tf versionné	l'ignorer, en sachant que ce n'est pas un fichier généré
un module imbriqué est retéléchargé	source distant au lieu d'un chemin relatif	./modules/<nom>

Glissez pour voir

Mettre en pratique

Le lab organiser un dépôt Terraform remet un main.tf monolithique à découper selon le socle officiel. Les tests replanifient la configuration d'origine dans un répertoire temporaire et comparent les deux empreintes de plan : un découpage qui perd une ressource passe validate avec Success! et tombe ici. Ils mettent aussi le .gitignore à l'épreuve avec git check-ignore, dans un dépôt jetable. Il se joue hors ligne.

À retenir

• Le socle officiel nomme terraform.tf et providers.tf ; versions.tf n'apparaît nulle part dans la documentation.
• Variables et outputs se déclarent en ordre alphabétique.
• validate ne prouve pas qu'un découpage est neutre : il ignore l'état et la valeur des arguments.
• La preuve, c'est le diff de planned_values et resource_changes entre deux plans.
• override.tf est le seul nom de fichier qui change le résultat : chargé en dernier, il fusionne.
• fmt -check sans -recursive ne voit qu'un répertoire, et sort en 3 en cas d'écart.
• Un plan enregistré s'appelle souvent tfplan, sans extension : le .gitignore doit le nommer.
• Le .terraform.lock.hcl se committe toujours, et se vérifie avec git check-ignore.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui casse en pratique : le découpage qui change le plan sans prévenir, la CI verte qui n'a rien formaté, et le plan enregistré qui part dans un commit.

Comment nommer les fichiers d'une configuration Terraform ?

Le style guide officiel nomme terraform.tf pour le bloc terraform, providers.tf pour les providers, puis variables.tf, outputs.tf et main.tf. Le nom versions.tf, très répandu, n'apparaît nulle part dans la documentation, et le bloc provider a son fichier à lui.

terraform validate suffit-il après avoir découpé une configuration ?

Non. La documentation borne son périmètre : validate ne vérifie pas la valeur des arguments et n'évalue aucun état existant. Un découpage qui perd une ressource passe donc avec Success. La seule preuve d'invariance est la comparaison de deux plans.

Pourquoi terraform fmt -check ne détecte-t-il rien dans mes sous-répertoires ?

Parce que la commande ne traite que le répertoire courant. Sur une arborescence, il faut l'option -recursive, sans quoi un contrôle d'intégration continue reste vert avec des sous-répertoires mal formatés.

Quels fichiers Terraform faut-il mettre dans le .gitignore ?

Le répertoire .terraform, l'état et ses sauvegardes, et les plans enregistrés. Attention au nom du plan : terraform plan -out=tfplan produit un fichier sans extension, qu'un motif *.tfplan ne capture pas, et qui contient les valeurs résolues.

Le nom d'un fichier .tf a-t-il un effet sur le comportement de Terraform ?

Une seule famille en a un : override.tf, override.tf.json et tout fichier terminé par _override.tf. Terraform les charge en dernier et fusionne leur contenu par-dessus les blocs existants. Tous les autres noms sont une convention pour les humains.

Où placer les modules et les exemples dans un dépôt Terraform ?

Les modules imbriqués sous modules/, appelés par un chemin relatif pour rester dans le même paquet, et les exemples sous examples/, dont le source doit pointer l'adresse externe du module puisqu'ils sont faits pour être recopiés ailleurs.

Trois répertoires d'environnement, est-ce trois states Terraform ?

Oui. envs/dev, envs/staging et envs/prod sont trois configurations racine, donc trois états indépendants. Une racine ne peut lire une valeur d'une autre que par les outputs de son état distant, jamais par une référence directe entre répertoires.

Faut-il committer le fichier .terraform.lock.hcl ?

Oui, toujours. Il enregistre les versions de providers effectivement sélectionnées et leurs empreintes, ce qui garantit que toute l'équipe et la CI emploient exactement les mêmes. Il ne couvre en revanche pas les modules.

Pour aller plus loin

• Structure standard d'un module : le socle d'un module, ses exemples et son README.
• Quiz Organiser les environnements Terraform : un contrôle des acquis sur l'organisation et l'isolation.
• Le style guide officiel : noms de fichiers, ordre des blocs et recommandations d'outillage.
• Structure des modules : la référence officielle : modules/, examples/ et la règle du README.

×

📖 Voir la documentation →