Gérer les variables par environnement avec Terraform

Pour servir plusieurs environnements avec un seul code Terraform, on écrit un fichier de valeurs par environnement et on le sélectionne au moment du plan : terraform apply -var-file=envs/prod.tfvars. Le code ne change pas, seules les valeurs changent.

Reste la question qui décide de ce que vous déployez : quand plusieurs sources donnent une valeur à la même variable, laquelle gagne ? Tout ce qui suit a été exécuté sur Terraform v1.15.4, et deux idées très répandues n'y survivent pas, celle du tableau de précédence à cinq niveaux, et celle du drapeau -var qui surcharge tout.

Ce que vous allez apprendre

• Écrire un fichier de valeurs par environnement, et le sélectionner
• Reconnaître les fichiers que Terraform charge sans qu'on les demande
• Classer les six sources de valeurs, du plus faible au plus fort
• Prouver quelle valeur a été retenue, sans la lire à l'écran
• Passer une map ou une liste en ligne de commande
• Repérer une clé mal orthographiée qui ne fait échouer aucun plan

Prérequis

• Terraform 1.11 ou plus récent (installer Terraform). Les mesures viennent de la branche stable du moment, 1.15.x.
• Savoir déclarer une variable (variables Terraform) et connaître les fichiers tfvars.

Un fichier de valeurs par environnement

Le code déclare ce qui varie sans fixer aucune valeur. Les variables sans default sont un garde-fou : elles obligent l'appelant à choisir un environnement.

variables.tf

variable "env_name" {
  description = "Nom de l'environnement servi."
  type        = string
}

variable "disk_size_gb" {
  description = "Taille du volume, en Go."
  type        = number
}

variable "retention_jours" {
  description = "Duree de retention des sauvegardes, en jours."
  type        = number
  default     = 7
}

Chaque environnement reçoit alors son fichier, en syntaxe nom = valeur, sans le mot-clé variable :

envs/prod.tfvars

env_name        = "prod"
disk_size_gb    = 8
retention_jours = 90

Et on le sélectionne à l'exécution :

terraform apply -var-file=envs/prod.tfvars

Les fichiers que Terraform charge sans qu'on les demande

Quatre noms sont automatiques, et c'est la source d'une bonne partie des surprises. Terraform charge sans aucune option :

Fichier	Chargé
terraform.tfvars	toujours, s'il existe
terraform.tfvars.json	toujours, s'il existe
*.auto.tfvars	tous, en ordre lexical
*.auto.tfvars.json	tous, en ordre lexical

Glissez pour voir

Tout autre nom, envs/prod.tfvars compris, demande un -var-file explicite.

C'est très utile pour les valeurs partagées par tous les environnements, une image de base ou des étiquettes communes, qu'on n'a alors pas à recopier dans chaque fichier :

commun.auto.tfvars

base_image = "debian-13-genericcloud-amd64.qcow2"

tags = {
  equipe = "infra"
  projet = "formation-terraform"
}

Un terraform.tfvars peut neutraliser votre garde-fou

Une variable sans default n'oblige plus à rien dès qu'un terraform.tfvars lui donne une valeur : il est chargé automatiquement, et terraform plan réussit alors qu'aucun environnement n'a été choisi. Le garde-fou n'a pas disparu du code, il a été rempli par un fichier que personne ne mentionne dans la commande.

L'échelle de précédence, mesurée

Voici l'ordre officiel, du plus faible au plus fort. Chaque marche a été vérifiée en opposant deux sources et en lisant la valeur retenue :

Rang	Source	Chargement
1 (le plus faible)	default du bloc variable	implicite
2	variable d'environnement TF_VAR_<nom>	implicite
3	terraform.tfvars	automatique
4	terraform.tfvars.json	automatique
5	*.auto.tfvars et *.auto.tfvars.json, en ordre lexical	automatique
6 (le plus fort)	-var et -var-file, dans l'ordre fourni	explicite

Glissez pour voir

Deux marches manquent à presque tous les tableaux publiés. La deuxième, les variables d'environnement, et surtout la sixième, où -var et -var-file partagent le même rang.

Les variables d'environnement existent, et elles perdent

Terraform lit toute variable d'environnement préfixée par TF_VAR_. Elle bat le default, ce qui en fait un moyen commode d'injecter une valeur depuis un runner :

export TF_VAR_env_name=depuis-la-ci

Mais elle perd contre le moindre fichier de valeurs du dépôt. Mesuré, avec la variable exportée et un terraform.tfvars présent :

TFVARS

C'est la valeur du fichier qui l'emporte. Une chaîne d'intégration qui pose ses valeurs par l'environnement peut donc être écrasée en silence par un fichier commité.

Vérifier la valeur retenue, sans la lire à l'écran

C'est le contrôle qui tranche tous les doutes de précédence, et il ne demande aucun apply. La représentation JSON du plan expose la valeur résolue de chaque variable racine :

terraform plan -out=tfplan -var-file=envs/prod.tfvars
terraform show -json tfplan | jq '.variables'

{
  "disk_size_gb": { "value": 8 },
  "env_name": { "value": "prod" },
  "retention_jours": { "value": 90 }
}

Une valeur passée par -var reste une chaîne

Mesuré sur 1.15.4 : une valeur fournie par -var figure en chaîne dans cette représentation, "16", même pour une variable typée number, là où la même valeur venue d'un .tfvars apparaît en nombre. Terraform la convertit bien selon le type déclaré pour l'utiliser : c'est la représentation du plan qui expose l'entrée brute.

Passer une map ou une liste en ligne de commande

Un type complexe se passe très bien par -var, à condition de respecter les règles d'échappement du shell. La documentation recommande la syntaxe JSON :

terraform plan -var 'tags={"equipe":"astreinte","criticite":"haute"}'

La syntaxe HCL native fonctionne également, mesurée sur 1.15.4 :

terraform plan -var 'tags={equipe="prod"}'

Les guillemets simples autour de l'argument sont ce qui protège les guillemets doubles du shell.

Cumuler plusieurs fichiers

L'option -var-file s'emploie plusieurs fois, ce qui permet de superposer des valeurs communes et des valeurs d'environnement sans dépendre d'un chargement implicite :

terraform plan -var-file=commun.tfvars -var-file=envs/prod.tfvars

Le dernier gagne pour les clés que les deux fichiers déclarent, et rien n'interdit de passer explicitement un fichier déjà chargé automatiquement, comme -var-file=production.auto.tfvars.

Les pièges mesurés

Le mécanisme est en place. Voici ce qui casse en pratique, chaque cas ayant été rejoué sur 1.15.4.

-var ne surcharge pas « toute autre source »

C'est l'erreur la plus répandue, et elle est facile à démontrer. -var et -var-file sont au même rang : c'est l'ordre des arguments qui tranche, pas une priorité intrinsèque.

terraform plan -var 'disk_size_gb=16' -var-file=envs/prod.tfvars

Le plan retient 8, la valeur du fichier, parce qu'il est appliqué après. En inversant les deux options :

terraform plan -var-file=envs/prod.tfvars -var 'disk_size_gb=16'

Le plan retient 16. Le même couple d'options donne donc deux résultats, et rien ne le signale à l'écran.

L'ordre des *.auto.tfvars est lexical, pas alphabétique

« Ordre alphabétique » est un raccourci qui trompe dès qu'on mélange des chiffres ou des casses. L'ordre est lexical, il compare les octets. Mesuré avec deux fichiers auto chargés :

9-x.auto.tfvars     valeur = "NEUF"
10-x.auto.tfvars    valeur = "DIX"

C'est NEUF qui l'emporte, puisque "10-x" précède "9-x" en lexical, donc 9-x s'applique en dernier. Même effet entre B.auto.tfvars et a.auto.tfvars : c'est a qui gagne, là où un classement insensible à la casse aurait désigné B.

Une clé mal orthographiée ne fait pas échouer le plan

Trois comportements différents, selon l'endroit de la faute, et un seul arrête la commande :

Où se trouve la faute	Ce que fait Terraform
TF_VAR_variable_inexistante	rien du tout, en silence
dans un fichier .tfvars	Warning: Value for undeclared variable, la variable reste à son default
avec -var	Error: Value for undeclared variable, code de retour 1

Glissez pour voir

Un disk_size_go au lieu de disk_size_gb dans un fichier d'environnement produit donc un plan valide, avec la mauvaise taille, et un simple avertissement dans une sortie que personne ne relit.

Un -var-file qui pointe un fichier absent n'arrête rien

Celui-ci surprend, et il a été vérifié trois fois, dont une sans tube ni substitution. Terraform affiche une erreur :

Error: Failed to read variables file

Given variables file absent.tfvars does not exist.

Puis il poursuit le plan avec les valeurs par défaut, et sort en 0 :

Changes to Outputs:
  + valeur = "DEFAUT"

Une faute de frappe dans le chemin d'un -var-file ne fait donc pas échouer un pipeline qui teste le code de retour. Le contrôle utile est de relire la valeur retenue dans le JSON du plan.

sensitive masque l'affichage, il ne protège pas l'état

Un .tfvars de production est exactement le fichier où l'on est tenté de mettre un secret. Marquer la variable sensitive = true masque son affichage, et rien de plus. Mesuré, après un apply avec une variable sensible :

grep MOT-DE-PASSE-EN-CLAIR terraform.tfstate

Le secret est bien là, en clair, dans l'état. Et il figure aussi dans le plan enregistré, que terraform show -json restitue en clair. La documentation le dit sans détour : « Terraform still stores the values of sensitive variables in your state. »

Pour qu'une valeur ne rejoigne ni l'état ni les outputs, le mécanisme est ephemeral = true. Terraform devient alors mécaniquement contraignant :

Error: Ephemeral value not allowed

Un fichier de valeurs ne sépare pas les états

Le point à ne pas confondre, et c'est le plus structurant. Un -var-file change les valeurs, pas l'état. Un seul répertoire garde un état : appliquer dev.tfvars puis prod.tfvars ne crée pas deux environnements, le second remplace le premier. La séparation réelle passe par des racines distinctes, sujet traité dans séparer dev, staging et prod.

Dépannage

Symptôme	Cause probable	Correction
Error: No value for required variable	aucun fichier ni -var ne fournit la valeur	ajouter -var-file=envs/<env>.tfvars, ou exporter un TF_VAR_
une variable a une valeur inattendue	une source plus forte que celle attendue	lire terraform show -json tfplan | jq '.variables', puis remonter l'échelle
-var semble ignoré	un -var-file placé après l'écrase	inverser l'ordre des deux options
Warning: Value for undeclared variable	clé mal orthographiée dans un .tfvars	corriger la clé, jamais ajouter un default pour faire taire l'avertissement
Error: Value for undeclared variable	même faute, mais passée par -var	corriger le nom ; ici, au moins, la commande échoue
le plan tourne alors qu'aucun environnement n'est choisi	un terraform.tfvars auto chargé	le vider, le supprimer, ou assumer qu'il porte les valeurs par défaut
un -var-file sans effet et aucune erreur bloquante	chemin inexistant : le message s'affiche, le code reste 0	vérifier le chemin, et contrôler la valeur retenue
un secret se retrouve dans l'état	sensitive ne fait que masquer l'affichage	sortir la valeur du code, et regarder ephemeral

Glissez pour voir

Mettre en pratique

Le lab la valeur qui gagne remet une configuration servant trois environnements, avec un terraform.tfvars qui neutralise son propre garde-fou, deux types laissés à compléter et une clé mal orthographiée. Les tests ne lisent jamais vos fichiers : ils rejouent des plans et comparent la clé variables du JSON, ce qui prouve la précédence sans rien supposer. Ils vérifient aussi que l'ordre des options tranche, et que les *.auto.tfvars s'appliquent en ordre lexical. Il se joue hors ligne.

À retenir

• Un fichier par environnement paramètre un code unique, sélectionné par -var-file.
• Quatre noms sont chargés sans option : terraform.tfvars, terraform.tfvars.json et les *.auto.tfvars.
• L'échelle complète compte six rangs, et les TF_VAR_ en occupent un, juste au-dessus du default.
• Une variable d'environnement perd contre n'importe quel fichier de valeurs.
• -var ne gagne pas toujours : il partage son rang avec -var-file, et l'ordre des arguments décide.
• L'ordre des *.auto.tfvars est lexical : 9-x s'applique après 10-x.
• La valeur retenue se prouve par terraform show -json, jamais à l'écran.
• Une clé mal orthographiée dans un .tfvars ne produit qu'un avertissement, et laisse la variable à son default.
• Un -var-file inexistant affiche une erreur mais laisse le plan aboutir en code 0.
• sensitive masque l'affichage ; la valeur reste dans l'état.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui surprend en pratique : la source qui l'emporte contre toute attente, le fichier chargé sans qu'on l'ait demandé, et la faute de frappe qui ne casse rien.

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

Six rangs, du plus faible au plus fort : le default du bloc variable, les variables d'environnement TF_VAR_, terraform.tfvars, terraform.tfvars.json, les fichiers auto.tfvars en ordre lexical, puis les options -var et -var-file.

Le drapeau -var surcharge-t-il vraiment toutes les autres sources ?

Non. -var et -var-file occupent le même rang de précédence et s'appliquent dans l'ordre où ils apparaissent sur la ligne de commande. Un -var-file placé après un -var l'emporte donc, ce qui contredit l'idée reçue.

Quels fichiers Terraform charge-t-il automatiquement ?

Quatre : terraform.tfvars, terraform.tfvars.json, et tous les fichiers terminés par .auto.tfvars ou .auto.tfvars.json. Tout autre nom, comme envs/prod.tfvars, exige un -var-file explicite sur la ligne de commande.

Les variables d'environnement TF_VAR_ sont-elles prioritaires ?

Non, elles sont presque les plus faibles. Une TF_VAR_ bat seulement le default du bloc variable et perd contre n'importe quel fichier de valeurs, y compris un terraform.tfvars chargé automatiquement depuis le dépôt.

Que se passe-t-il si je me trompe dans le nom d'une variable ?

Trois comportements selon l'endroit. Une TF_VAR_ inconnue est ignorée en silence, une clé inconnue dans un .tfvars produit un simple avertissement et laisse la variable à son default, et un -var inconnu fait échouer la commande en code 1.

Comment savoir quelle valeur Terraform a réellement retenue ?

En lisant la clé variables de la représentation JSON du plan, obtenue par terraform plan -out=tfplan puis terraform show -json tfplan. C'est la seule preuve de précédence, et elle ne demande aucun apply.

Un -var-file qui pointe un fichier inexistant fait-il échouer Terraform ?

Non. Terraform affiche Error: Failed to read variables file, puis poursuit le plan avec les valeurs par défaut et sort en code 0. Une faute de frappe dans le chemin ne fait donc pas échouer un pipeline qui teste le code de retour.

Peut-on mettre un secret dans un fichier tfvars avec sensitive ?

Non. L'argument sensitive masque seulement l'affichage. La documentation le dit : Terraform conserve les valeurs des variables sensibles dans le state, et elles figurent aussi dans les plans enregistrés. Pour qu'une valeur n'atteigne pas l'état, il faut ephemeral.

Pour aller plus loin

• Monorepo vs un repo par stack : un seul dépôt ou un dépôt par périmètre, une fois les valeurs rangées.
• Quiz Organiser les environnements Terraform : un contrôle des acquis sur la section, précédence comprise.
• Les variables d'entrée : la référence officielle : l'ordre de précédence, les TF_VAR_ et les variables non déclarées.
• La commande plan : la référence officielle : -var, -var-file répétable et les options de planification.

×

📖 Voir la documentation →