Gérer les variables par environnement avec Terraform

Pour paramétrer différents environnements sans modifier le code Terraform, créez un fichier .tfvars par environnement et sélectionnez-le avec terraform apply -var-file=envs/prod.tfvars. Le code reste identique, seules les valeurs changent. C’est la manière la plus simple de faire varier les paramètres d’un environnement à l’autre avec un seul répertoire Terraform, mais ce n’est pas une stratégie d’isolation du state à elle seule.

Analogie

Les fichiers .tfvars, c’est comme des profils de cuisson sur un four : le four est le même, mais selon le profil choisi (pain, pizza, gâteau), la température et la durée changent. Vous ne reconstruisez pas un four pour chaque plat.

Prérequis : savoir utiliser les variables Terraform (variable, type, default). Avoir lu Organiser un dépôt Terraform pour comprendre la structuration des fichiers.

Ce que vous allez apprendre

• Créer des fichiers .tfvars pour chaque environnement
• Sélectionner le bon fichier avec -var-file
• Comprendre l’ordre de précédence des variables
• Surcharger une valeur ponctuellement avec -var
• Distinguer terraform.tfvars (auto-chargé) des fichiers explicites

La structure cible

mon-projet/
├── versions.tf
├── variables.tf       ← Déclare les variables (sans valeurs par défaut)
├── main.tf            ← Utilise var.env_name, var.disk_size_gb, etc.
├── outputs.tf
└── envs/
    ├── dev.tfvars     ← env_name = "dev", disk_size_gb = 4
    ├── staging.tfvars ← env_name = "staging", disk_size_gb = 4
    └── prod.tfvars    ← env_name = "prod", disk_size_gb = 8

Le code est strictement le même pour tous les environnements. Seul le fichier .tfvars passé en argument change le comportement.

Déclarer des variables sans valeurs par défaut

La clé de cette approche : les variables dans variables.tf n’ont pas de default. Cela force à toujours fournir un fichier .tfvars :

variables.tf

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

variable "network_address" {
  description = "Adresse réseau (ex: 10.10.90.1)"
  type        = string
}

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

Sans fichier de variables, Terraform refuse de planifier :

terraform plan -input=false

Error: No value for required variable

  on variables.tf line 1:
   1: variable "env_name" {

The root module input variable "env_name" is not set, and has no default
value. Use a -var or -var-file command line argument to provide a value
for this variable.

C’est un garde-fou volontaire : impossible de déployer sans préciser l’environnement.

Créer les fichiers .tfvars

Chaque fichier .tfvars contient les valeurs adaptées à un environnement :

envs/dev.tfvars

env_name        = "dev"
network_address = "10.10.90.1"
dhcp_start      = "10.10.90.10"
dhcp_end        = "10.10.90.100"
disk_size_gb    = 4
base_image_path = "/chemin/vers/image.qcow2"

envs/prod.tfvars

env_name        = "prod"
network_address = "10.10.92.1"
dhcp_start      = "10.10.92.10"
dhcp_end        = "10.10.92.100"
disk_size_gb    = 8
base_image_path = "/chemin/vers/image.qcow2"

La syntaxe est simple : nom_variable = valeur, une par ligne, sans mot-clé variable.

Convention de nommage

Nommez les fichiers selon l’environnement : dev.tfvars, staging.tfvars, prod.tfvars. Placez-les dans un sous-répertoire envs/ pour ne pas encombrer la racine du projet.

Déployer avec -var-file

La commande -var-file indique à Terraform quel fichier de variables utiliser :

1. Déployer l’environnement dev

   terraform apply -var-file=envs/dev.tfvars -auto-approve

   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
   
   Outputs:
   
   network_name = "dev-network"
   volume_name = "dev-disk.qcow2"
   disk_size = 4294967296

   Les ressources portent le préfixe dev-, le volume fait 4 Go.

2. Basculer vers la prod

   Détruisez d’abord les ressources dev, puis déployez avec le fichier prod :

   terraform destroy -var-file=envs/dev.tfvars -auto-approve
   terraform apply -var-file=envs/prod.tfvars -auto-approve

   Plan: 2 to add, 0 to change, 0 to destroy.
   
   Apply complete! Resources: 2 added, 0 changed, 0 destroyed.
   
   Outputs:
   
   network_name = "prod-network"
   volume_name = "prod-disk.qcow2"
   disk_size = 8589934592

   Le même code produit un réseau prod-network avec un volume de 8 Go.

Même state, attention

Avec un seul répertoire et -var-file, tous les environnements partagent le même state. Déployer avec dev.tfvars puis avec prod.tfvars ne crée pas deux environnements séparés — le second écrase le premier. Pour une vraie isolation, combinez avec des répertoires séparés, ou configurez un backend différent par environnement.

Surcharger une variable avec -var

Le flag -var en ligne de commande surcharge toute autre source de la même variable :

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

  ~ capacity      = 8589934592 -> 17179869184

Le fichier prod.tfvars définit disk_size_gb = 8, mais -var='disk_size_gb=16' le surcharge à 16 Go. C’est utile pour un test ponctuel sans modifier le fichier.

L’ordre de précédence des variables

Terraform applique les variables dans un ordre strict. La dernière source gagne :

Priorité	Source	Chargement
1 (plus faible)	default dans variable {}	Automatique
2	terraform.tfvars	Automatique si présent
3	*.auto.tfvars (ordre alphabétique)	Automatique si présent
4	-var-file=...	Explicite
5 (plus forte)	-var='...'	Explicite

Glissez pour voir

terraform.tfvars : le fichier auto-chargé

Un fichier nommé exactement terraform.tfvars à la racine du projet est chargé automatiquement à chaque commande, sans -var-file :

# terraform.tfvars — chargé automatiquement
env_name        = "auto"
network_address = "10.10.99.1"
disk_size_gb    = 2

terraform plan

Les valeurs de terraform.tfvars (auto, 2 Go, .99.x) sont utilisées.

Mais si vous ajoutez -var-file, celui-ci prend le dessus :

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

No changes. Your infrastructure matches the configuration.

Les valeurs de prod.tfvars (prod, 8 Go, .92.x) remplacent celles de terraform.tfvars.

Piège courant

Si un terraform.tfvars existe à la racine et que vous utilisez -var-file, les variables définies dans les deux fichiers suivent la précédence : -var-file gagne. Mais les variables présentes uniquement dans terraform.tfvars restent actives. Cela peut créer des mélanges involontaires.

Exemple :

terraform.tfvars

env_name        = "default"
disk_size_gb    = 2
base_image_path = "/images/commun.qcow2"

envs/prod.tfvars

env_name     = "prod"
disk_size_gb = 8

Avec terraform plan -var-file=envs/prod.tfvars, Terraform utilisera :

• env_name = "prod" depuis prod.tfvars
• disk_size_gb = 8 depuis prod.tfvars
• base_image_path = "/images/commun.qcow2" depuis terraform.tfvars

Le résultat peut être valide techniquement, mais inattendu si vous pensiez que prod.tfvars remplaçait tout le contexte.

*.auto.tfvars : chargement par suffixe

Tout fichier se terminant par .auto.tfvars est aussi chargé automatiquement, par ordre alphabétique :

common.auto.tfvars    ← chargé en premier
region.auto.tfvars    ← chargé en second (surcharge si même variable)

Ce mécanisme est utile pour des valeurs communes (comme base_image_path) partagées entre tous les environnements, combinées avec un -var-file pour les valeurs spécifiques.

Combiner tfvars et répertoires séparés

La combinaison la plus robuste pour un projet professionnel :

mon-projet/
├── modules/
│   └── infra/
│       ├── ...
├── envs/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── backend.tf      ← Backend local ou distant propre à dev
│   │   └── dev.tfvars      ← Valeurs dev
│   └── prod/
│       ├── main.tf
│       ├── backend.tf      ← Backend local ou distant propre à prod
│       └── prod.tfvars      ← Valeurs prod

Chaque environnement a son propre répertoire et son propre .tfvars. En backend local, cela suffit pour séparer les fichiers de state. En backend distant, il faut aussi séparer la configuration de backend (backend.tf ou -backend-config) pour éviter de réutiliser la même key. La commande de déploiement devient :

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

Dépannage

Symptôme	Cause probable	Solution
Error: No value for required variable	Pas de -var-file et pas de default	Ajouter -var-file=envs/xxx.tfvars à la commande
Variable a une valeur inattendue	Conflit entre terraform.tfvars et -var-file	Vérifier l’ordre de précédence, supprimer terraform.tfvars si non voulu
Error: Invalid value for variable	Type incompatible dans le .tfvars	Vérifier que la valeur correspond au type déclaré (number vs string)
-var-file ignoré	Chemin relatif incorrect	Vérifier le chemin depuis le répertoire courant
Variables sensibles visibles dans le plan	sensitive = true absent	Ajouter sensitive = true sur les variables contenant des secrets

Glissez pour voir

À retenir

• Un fichier .tfvars par environnement contient les valeurs spécifiques (noms, adresses, tailles)
• -var-file=envs/prod.tfvars sélectionne l’environnement au moment du plan ou de l’apply
• Sans default, les variables obligent à fournir un .tfvars — c’est un garde-fou volontaire
• terraform.tfvars est chargé automatiquement, mais -var-file le surcharge
• -var='...' en ligne de commande surcharge toute autre source — utile pour les tests ponctuels
• Les fichiers .tfvars changent les valeurs, pas le state ; pour une vraie isolation, combinez-les avec des répertoires séparés et, si besoin, un backend distinct

Prochaines étapes

Séparer dev, staging et prod Combiner les tfvars avec des répertoires pour une isolation complète.

Organiser un dépôt Terraform Conventions de fichiers et structure standard d'un projet.

Monorepo vs un repo par stack Quand regrouper et quand séparer les projets Terraform.

×

📖 Voir la documentation →