Fichiers tfvars Terraform : précédence et pièges

Un fichier .tfvars fournit des valeurs de variables sans toucher au code : une configuration, plusieurs environnements. C'est simple, mais deux choses piègent : l'ordre de précédence exact quand plusieurs sources se contredisent, et le sort d'une variable non déclarée, qui n'échoue pas de la même façon selon d'où elle vient. Ce guide traite le chargement automatique, la précédence, ce piège, les types complexes et le cas des secrets.

Tous les comportements ont été vérifiés sur Terraform v1.15.4.

Ce que vous allez apprendre

• Le chargement automatique des terraform.tfvars et *.auto.tfvars
• L'ordre de précédence exact (avec tfvars.json et l'ordre lexical)
• Le piège de la variable non déclarée : warning ou erreur selon la source
• Les types complexes en fichier et en ligne de commande (JSON)
• Le cas des secrets, et pourquoi tfvars finit dans le state

Prérequis

• Les variables d'entrée (variables Terraform)
• Terraform 1.15.x, la série stable courante

Le chargement automatique

Terraform charge sans argument quatre familles de fichiers, s'ils existent : terraform.tfvars, terraform.tfvars.json, et tout *.auto.tfvars ou *.auto.tfvars.json. Un fichier au nom quelconque (prod.tfvars) n'est pas chargé automatiquement : il faut le passer par -var-file.

terraform.tfvars

region   = "eu-west-3"
replicas = 3
tags     = { equipe = "infra", env = "prod" }

Un .tfvars ne contient que des assignations : pas de bloc variable, resource ni locals. Sa version JSON est un objet dont les clés sont les noms de variables :

{ "region": "eu-west-3", "replicas": 3 }

L'ordre de précédence, du plus faible au plus fort

Quand plusieurs sources donnent une valeur à la même variable, Terraform les applique dans un ordre fixe :

Rang	Source
1	le default du bloc variable
2	la variable d'environnement TF_VAR_<nom>
3	le fichier terraform.tfvars
4	le fichier terraform.tfvars.json
5	les *.auto.tfvars (et .json), en ordre lexical
6	les options -var / -var-file et les variables HCP Terraform

Glissez pour voir

Trois précisions que beaucoup de guides ratent. D'abord, terraform.tfvars.json est un niveau distinct au-dessus de terraform.tfvars : si les deux fournissent la même variable, la variante JSON gagne. Ensuite, les *.auto.tfvars sont chargés en ordre lexical, pas « alphabétique » : l'ordre compare les octets, donc Z.auto.tfvars passe avant a.auto.tfvars, et 20-x après 10-y. Enfin, les variables de workspace HCP Terraform sont au même niveau que la ligne de commande, tout en haut.

Le piège : la variable non déclarée

Voici le manque le plus coûteux, et le « faux diagnostic » que ce sujet promet d'éviter. Une valeur affectée à une variable sans bloc variable correspondant ne se comporte pas de la même façon selon sa source :

• dans un fichier .tfvars : un simple avertissement, le plan réussit ;
• via -var : une erreur, le plan échoue ;
• via TF_VAR_ : silencieusement ignorée, aucun message.

# faute de frappe dans terraform.tfvars : replika au lieu de replicas
terraform plan

Warning: Value for undeclared variable

Une faute de frappe qui ne casse rien

C'est le piège concret. Une variable mal orthographiée dans un .tfvars ne fait pas échouer le plan : elle produit un avertissement, et la vraie variable reste à son default. On croit avoir changé une valeur, il n'en est rien. En -var, la même faute lève une erreur franche. Lisez les avertissements, ou passez la valeur sensible en -var pour être averti tout de suite.

Les types complexes, en fichier et en ligne de commande

Un .tfvars accepte naturellement listes, maps et objets :

zones    = ["a", "b", "c"]
tags     = { env = "prod", equipe = "infra" }

En ligne de commande, c'est plus subtil : passer une liste, une map ou un objet via -var ou TF_VAR_ exige une syntaxe JSON valide, en respectant l'échappement du shell :

terraform apply -var 'zones=["a","b","c"]'

Ne passer que des scalaires en -var et réserver les structures aux fichiers est souvent plus lisible.

Variable sans valeur : le mode non interactif échoue

Une variable sans default et qu'aucune source n'alimente déclenche, sur un poste de travail, une demande interactive. Mais en automatisation, avec -input=false (le mode des pipelines), la même configuration échoue :

terraform plan -input=false
# Error: No value for required variable

C'est une cause classique d'échec en CI qui « marche pourtant en local ». Fournissez toujours les variables requises par un fichier, un -var ou un TF_VAR_ dans une chaîne d'automatisation.

Les secrets : tfvars finit dans le state

Un .tfvars ne doit jamais contenir de secret committé, mais le problème va plus loin : une valeur fournie par un .tfvars ou par TF_VAR_ finit dans le fichier d'état, en clair, même si la variable est sensitive. sensitive ne masque que l'affichage.

Le seul mécanisme qui exclut réellement une valeur du state et du plan est ephemeral = true (Terraform 1.10+). Pour un secret durable, préférez un gestionnaire de secrets et une variable éphémère, plutôt qu'un .tfvars, même gitignoré.

Ce que .gitignore ne suffit pas à protéger

Gitignorer un secrets.tfvars empêche de le committer, mais pas la valeur d'atterrir dans terraform.tfstate. Chiffrez le state (backend distant), ou utilisez ephemeral pour les valeurs qui ne doivent jamais toucher le disque.

Repasser un fichier auto-chargé avec -var-file

-var-file n'est pas réservé aux fichiers non auto-chargés. On peut très bien repasser explicitement un fichier déjà chargé automatiquement, ou en cumuler plusieurs, le dernier fourni l'emportant :

terraform apply -var-file="production.auto.tfvars"
terraform apply -var-file="base.tfvars" -var-file="prod.tfvars"

Dépannage

Ces symptômes viennent presque tous de la précédence ou d'une variable non déclarée.

Symptôme	Cause	Solution
Une valeur de .tfvars semble ignorée	Un *.auto.tfvars ou un -var la surcharge	Vérifier la précédence ; -var gagne toujours
Warning: Value for undeclared variable	Une variable d'un .tfvars sans bloc variable	Corriger le nom, ou déclarer la variable
Error: Value for undeclared variable	La même faute, mais via -var	Corriger le nom passé en ligne de commande
No value for required variable en CI	-input=false et aucune source pour une variable requise	Fournir la valeur par fichier, -var ou TF_VAR_
Un secret apparaît dans le state	tfvars et TF_VAR_ finissent en clair dans l'état	Chiffrer le state, ou utiliser ephemeral

Glissez pour voir

À retenir

1. Sont auto-chargés : terraform.tfvars, terraform.tfvars.json, et les *.auto.tfvars(.json). Un autre nom passe par -var-file.
2. Précédence : default < TF_VAR_ < terraform.tfvars < terraform.tfvars.json < *.auto.tfvars (ordre lexical) < -var / HCP.
3. Variable non déclarée : warning en fichier, erreur en -var, ignorée en TF_VAR_. Une faute de frappe dans un .tfvars ne casse rien.
4. Les types complexes en -var exigent une syntaxe JSON.
5. -input=false échoue sur une variable requise sans valeur.
6. Une valeur de .tfvars ou TF_VAR_ finit dans le state ; seul ephemeral l'en exclut.

FAQ : questions fréquentes

Les questions ci-dessous reprennent les confusions les plus fréquentes sur les tfvars : la précédence, la variable non déclarée, et les secrets.

Quel est l'ordre de précédence des fichiers tfvars Terraform ?

Du plus faible au plus fort : default du bloc, TF_VAR_, terraform.tfvars, terraform.tfvars.json, les *.auto.tfvars en ordre lexical, puis -var, -var-file et les variables HCP Terraform. terraform.tfvars.json est un niveau distinct au-dessus de terraform.tfvars.

terraform.tfvars.json l'emporte-t-il sur terraform.tfvars ?

Oui. Ce sont deux niveaux de précédence distincts : si les deux fichiers existent et donnent la même variable, la variante JSON l'emporte. Vérifié sur Terraform 1.15.4. Beaucoup de guides les placent à tort au même niveau.

Que se passe-t-il si une variable tfvars n'est pas déclarée ?

Cela dépend de la source. Dans un fichier .tfvars, c'est un simple avertissement et le plan réussit, la vraie variable restant au default. Via -var, c'est une erreur qui fait échouer le plan. Via TF_VAR_, elle est silencieusement ignorée.

Dans quel ordre les fichiers auto.tfvars sont-ils chargés ?

En ordre lexical, pas alphabétique. La comparaison porte sur les octets : Z.auto.tfvars passe avant a.auto.tfvars, et 20-x après 10-y. Le dernier fichier dans cet ordre l'emporte en cas de conflit sur une même variable.

Comment passer une liste ou une map en -var à Terraform ?

Avec une syntaxe JSON valide, en respectant l'échappement du shell : -var 'zones=["a","b"]'. Les fichiers tfvars acceptent la syntaxe HCL native pour les listes et maps, mais la ligne de commande exige du JSON pour les types complexes.

Pourquoi mon plan Terraform échoue-t-il en CI mais marche en local ?

Souvent parce qu'une variable requise n'a ni default ni valeur fournie. En local, Terraform la demande en interactif. En CI, avec -input=false, la même configuration échoue avec No value for required variable. Il faut fournir la valeur par fichier, -var ou TF_VAR_.

Un secret dans un fichier tfvars est-il protégé s'il est gitignoré ?

Non. Gitignorer un .tfvars empêche de le committer, mais la valeur finit quand même en clair dans terraform.tfstate, même si la variable est sensitive. Seul ephemeral = true (Terraform 1.10+) exclut réellement une valeur du state et du plan.

Pour aller plus loin

• Locals Terraform : La valeur calculée dans le code, complément des valeurs fournies par tfvars.
• Le style guide Terraform : Les conventions de nommage et le .gitignore qui protège les tfvars sensibles.
• sensitive : masquer les valeurs : Ce qui arrive à un secret placé dans un tfvars, et ce que sensitive masque vraiment.

×

📖 Voir la documentation →