Variables Terraform : types, validation, nullable et précédence

Une variable Terraform paramètre une configuration : au lieu de coder une valeur en dur, on la déclare une fois et on l'alimente depuis l'extérieur. Déclarer une variable est simple. Ce qui fait échouer, ce sont quatre comportements rarement enseignés : le type par défaut qui laisse tout passer, le null explicite qui écrase un default, le sensitive pris pour une protection alors qu'il ne masque que l'affichage, et l'ordre de précédence des sources.

Ce guide part de la base, la déclaration et le typage, puis traite les types complexes, la validation, le piège nullable, la vraie portée de sensitive, et la précédence des sources. Tous les comportements ont été vérifiés sur Terraform v1.15.4.

Ce que vous allez apprendre

• Déclarer une variable, et pourquoi l'absence de type vaut any
• Les types complexes : object({...}), optional(), map, set, tuple
• La validation qui rejette une valeur au plan, avant tout provider
• Le piège du null qui écrase un default, et nullable = false
• Pourquoi sensitive ne protège pas le secret, et ce qui le protège
• L'ordre de précédence exact des sources de valeurs

Prérequis

• Un projet Terraform initialisé (installer Terraform)
• Terraform 1.15.x, la série stable courante

Déclarer une variable, et le type any

Un bloc variable porte un nom, et des arguments qui vont bien au-delà du trio description / type / default. Il accepte aussi validation, sensitive, nullable (défaut true), ephemeral (1.10+) et, depuis 1.15, deprecated.

variable "region" {
  type    = string
  default = "eu-west-3"
}

Sans contrainte de type, une variable vaut any : elle accepte n'importe quoi, et l'erreur n'apparaît qu'à l'usage, souvent loin de la déclaration. Typez toujours vos variables. Quelques noms sont réservés et interdits : source, version, providers, count, for_each, lifecycle, depends_on, locals.

Les types complexes : object et optional()

Le sujet ne s'arrête pas à list(string) et map(string). Le type le plus utile en pratique est object({...}), souvent dans une map, avec des attributs optional() porteurs d'un défaut :

variable "nodes" {
  type = map(object({
    size     = string
    replicas = optional(number, 1)
    public   = optional(bool, false)
  }))
}

Fournissez une entrée incomplète, et Terraform la complète avec les défauts des optional() :

nodes = {
  web = { size = "small" }   # replicas = 1, public = false ajoutes par Terraform
}

Le second argument d'optional() est le défaut ; sans lui, l'attribut absent vaut null. Les types set(...), tuple([...]) et les objets imbriqués suivent la même logique.

La validation rejette avant tout provider

Un bloc validation vérifie une condition et échoue au plan, avant le moindre appel de provider. C'est la barrière la moins chère contre une valeur absurde :

variable "env" {
  type = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.env)
    error_message = "env doit valoir dev, staging ou prod."
  }
}

terraform plan -var env=chaos

Error: Invalid value for variable

Aucune ressource n'est sollicitée : l'erreur tombe à la validation, ce qui en fait un garde-fou gratuit sur les entrées.

Le piège du null : nullable

Voici le piège le plus rentable du sujet, et il attrape même des profils avancés. Une variable a un default, on se croit donc protégé. Mais passer explicitement null (souvent depuis un fichier de valeurs généré) écrase le default et propage null :

variable "retention_days" {
  type    = number
  default = 7
}

Avec retention_days = null dans un terraform.tfvars, la variable vaut null, pas 7. Pour forcer le retour au défaut, on pose nullable = false :

variable "retention_days" {
  type     = number
  default  = 7
  nullable = false
}

Désormais, un null explicite retombe sur 7. C'est le comportement attendu d'une variable qui ne doit jamais valoir null.

sensitive masque l'affichage, pas le state

Voici l'erreur la plus dangereuse, parce qu'elle donne un faux sentiment de sécurité. sensitive = true ne protège pas le secret. Il masque la valeur dans la sortie humaine de plan, apply et terraform output, rien de plus. La documentation est explicite :

Terraform still records sensitive values in the state, so anyone who can access your state data can access your sensitive values.

Concrètement, terraform show -json et terraform output -json rendent la valeur en clair, et le fichier d'état la stocke telle quelle. Un sensitive = true sur une variable de mot de passe n'empêche personne ayant le state de le lire.

sensitive n'est pas du chiffrement

Pour exclure réellement une valeur du plan et du state, c'est ephemeral = true (Terraform 1.10+), pas sensitive. sensitive reste utile contre les fuites dans les logs et la console, mais ne remplace jamais un state chiffré et à accès restreint. Ne stockez pas un secret durable dans une variable ordinaire en croyant que sensitive le met à l'abri.

L'ordre de précédence des sources

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

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 et -var-file, dans l'ordre fourni

Glissez pour voir

Deux surprises fréquentes, et ce sont elles que l'examen interroge. D'abord, un *.auto.tfvars l'emporte sur un TF_VAR_ exporté : beaucoup croient l'inverse. Ensuite, entre deux *.auto.tfvars, c'est l'ordre alphabétique des noms de fichiers qui tranche, pas l'ordre d'écriture : zz-override.auto.tfvars gagne sur a-defaults.auto.tfvars. La ligne de commande, elle, gagne toujours.

Nouveautés utiles depuis 1.10

Deux arguments récents complètent le tableau, et tombent sous le sous-objectif données sensibles :

• ephemeral = true (1.10+) : la valeur existe pendant l'opération mais n'est ni écrite dans le state, ni dans le plan. C'est la vraie réponse au besoin que sensitive ne couvre pas.
• deprecated = "message" (1.15+) sur une variable ou un output : Terraform émet un avertissement au validate quand quelqu'un l'utilise encore. Pratique pour retirer une variable d'un module sans casser ses appelants du jour au lendemain.

Dépannage

Ces symptômes viennent presque tous d'un des quatre pièges ci-dessus. Le tableau associe chacun à sa cause et à sa correction.

Symptôme	Cause	Solution
Une variable accepte une valeur d'un type inattendu	Pas de type : elle vaut any	Ajouter une contrainte de type
Une variable à default vaut quand même null	Un null explicite a écrasé le défaut	Poser nullable = false
Un secret apparaît en clair dans le state	sensitive ne masque que l'affichage	Chiffrer le state, restreindre son accès, ou ephemeral = true
Invalid value for variable au plan	Un bloc validation a rejeté la valeur	Corriger la valeur, elle est hors des bornes autorisées
Une valeur d'*.auto.tfvars gagne sur un TF_VAR_	Ordre de précédence normal	Utiliser -var pour forcer, il est au-dessus de tout

Glissez pour voir

À retenir

1. Sans type, une variable vaut any : typez toujours.
2. object({...}) avec optional(x, defaut) complète les entrées partielles.
3. Un bloc validation rejette au plan, avant tout provider.
4. Un null explicite écrase un default ; nullable = false le fait retomber sur le défaut.
5. sensitive masque l'affichage, pas le state : la valeur y reste en clair. ephemeral = true l'exclut réellement.
6. Précédence : default < TF_VAR_ < terraform.tfvars < *.auto.tfvars (ordre lexical) < -var.
7. Certains noms sont réservés et ne peuvent pas nommer une variable.

FAQ : questions fréquentes

Les questions ci-dessous reprennent les confusions les plus fréquentes sur les variables : le piège du null, la vraie portée de sensitive, et l'ordre de précédence des sources.

sensitive = true protège-t-il vraiment un secret dans Terraform ?

Non. sensitive masque la valeur dans l'affichage humain de plan, apply et terraform output, mais Terraform l'enregistre en clair dans le state. terraform show -json et output -json la rendent en clair. Pour l'exclure du state, il faut ephemeral = true.

Pourquoi ma variable Terraform vaut-elle null malgré un default ?

Parce qu'une valeur null passée explicitement, souvent depuis un fichier tfvars, écrase le default et se propage. Poser nullable = false force le retour au default quand la valeur reçue est null. C'est le piège nullable, vérifié sur Terraform 1.15.4.

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

Du plus faible au plus fort : le default du bloc, puis TF_VAR_, puis terraform.tfvars, puis terraform.tfvars.json, puis les *.auto.tfvars en ordre lexical, puis les options -var et -var-file. Un auto.tfvars l'emporte donc sur un TF_VAR_ exporté.

Comment donner un type complexe à une variable Terraform ?

Avec object({...}), souvent dans une map ou un set, et des attributs optional(nom, defaut) pour les champs facultatifs. Une entrée incomplète du fichier de valeurs est alors complétée par Terraform avec ces defauts. set, tuple et objets imbriqués suivent la même logique.

Que se passe-t-il si une variable Terraform n'a pas de type ?

Sans contrainte de type, la variable vaut any : elle accepte n'importe quelle valeur, et l'erreur n'apparaît qu'à l'usage, souvent loin de la déclaration. La bonne pratique est de toujours typer une variable pour attraper les erreurs au plan.

Comment valider la valeur d'une variable Terraform ?

Avec un bloc validation contenant une condition et un error_message. Terraform évalue la condition au plan, avant tout appel de provider : une valeur invalide fait échouer le plan immédiatement, sans consommer de ressource. C'est un garde-fou gratuit sur les entrées.

Quelle différence entre sensitive et ephemeral sur une variable ?

sensitive masque la valeur dans l'affichage humain mais la conserve en clair dans le state et le plan. ephemeral, depuis Terraform 1.10, exclut réellement la valeur du state et du plan : elle n'existe que pendant l'opération. Pour un secret durable, c'est ephemeral, pas sensitive.

Pour aller plus loin

• Les outputs Terraform : Expose une valeur calculée, symétrique des variables d'entrée.
• Les valeurs locales : Nomme une valeur intermédiaire au lieu de la répéter.
• Conditions personnalisées : Étend la validation des variables aux precondition et au bloc check.

×

📖 Voir la documentation →