Locals Terraform : valeurs locales et leurs pièges

Un bloc locals nomme des valeurs calculées, pour ne pas répéter la même expression à dix endroits. C'est simple en apparence, mais trois comportements surprennent et causent des bugs difficiles à diagnostiquer : plusieurs blocs locals fusionnent, un ternaire convertit ses types sans prévenir, et un local dérivé d'une ressource n'est pas connu au plan.

Ce guide part de la base, ce qu'est un local et ce qu'il peut référencer, puis traite ces trois pièges, plus la propagation de la sensibilité. Tous les comportements ont été vérifiés sur Terraform v1.15.4, la plupart dans terraform console, avec local et random.

Ce que vous allez apprendre

• Ce qu'un local peut référencer, et ce qui le distingue d'une variable
• Pourquoi plusieurs blocs locals fusionnent
• Le piège de conversion de type du ternaire
• Pourquoi un local peut être inconnu au plan
• Comment la sensibilité se propage à travers un local

Prérequis

• Variables et types (variables Terraform)
• Terraform 1.15.x, la série stable courante

Qu'est-ce qu'un local ?

Un local nomme une valeur calculée. Sa syntaxe se réduit à nom = expression. Il n'accepte ni type, ni description, ni sensitive, ni validation : c'est exactement ce qui le distingue d'une variable, qui, elle, peut être typée et documentée. Un local est une valeur interne, que rien ne surcharge depuis l'extérieur.

locals {
  ref = replace(lower(var.enseigne), "_", "-")
}

Un local peut référencer quatre choses, et la documentation les liste précisément : une variable, un attribut de ressource, la sortie d'une fonction, et un autre local. Beaucoup de guides n'illustrent que les variables et les autres locals, mais référencer un attribut de ressource est justement la source du deuxième piège.

Les blocs locals fusionnent

On peut écrire autant de blocs locals {} qu'on veut, dans un ou plusieurs fichiers. Terraform les fusionne : un local d'un bloc peut en référencer un autre déclaré ailleurs, tant qu'aucun cycle n'apparaît.

locals {
  ref = replace(lower(var.enseigne), "_", "-")
}

locals {
  etiquette = "${local.ref}-${var.palier}"
}

terraform console

> local.etiquette
"ma-boutique-gold"

local.etiquette, dans le second bloc, consomme local.ref du premier. La règle de style officielle : un local partagé entre plusieurs fichiers va dans locals.tf ; un local propre à un fichier se déclare en haut de ce fichier.

Le piège du ternaire : les types se convertissent en silence

C'est l'erreur la plus fréquente, et beaucoup de guides l'énoncent à l'envers. On croit souvent qu'un ternaire dont les deux branches n'ont pas le même type échoue. C'est faux : Terraform convertit vers un type commun sans broncher, et n'échoue que si aucune conversion n'est possible.

> type(true ? 20 : 5)
number

> type(true ? 20 : "5")
string

20 : "5" ne lève aucune erreur, il rend une chaîne. Un local censé porter un nombre se retrouve typé chaîne, et le bug se révèle bien plus loin, là où ce nombre est utilisé dans un calcul. La documentation officielle recommande d'ailleurs d'être explicite en cas de doute :

> true ? tostring(20) : "cinq"
"20"

La règle : ne mettez pas de guillemets autour d'un nombre, et si les branches diffèrent vraiment, convertissez-les avec une fonction (tostring, tonumber).

Vérifiez le type, pas seulement la valeur

Un ternaire qui a glissé vers une chaîne donne souvent la bonne valeur affichée, mais un mauvais type. Le bug n'apparaît qu'au calcul suivant. Vérifiez avec type() dans terraform console, ou le type JSON dans terraform output -json.

Un local dérivé d'une ressource est inconnu au plan

Un local se calcule pendant le plan, sauf s'il référence un attribut de ressource qui n'existe pas encore. Sa valeur est alors (known after apply), exactement comme l'attribut dont il dépend. Beaucoup de guides affirment à tort qu'un local est toujours résolu au plan.

resource "random_id" "tirage" {
  byte_length = 4
}

locals {
  empreinte = upper(random_id.tirage.hex)
}

Sur un plan à froid, un output exposant local.empreinte apparaît en inconnu : random_id.tirage.hex n'est produit qu'à l'apply. Le plan JSON le montre dans output_changes[].after_unknown. C'est aussi ce qui crée une dépendance implicite dans le graphe : le local dépend de la ressource.

terraform plan -out=tfplan
terraform show -json tfplan | jq '.output_changes.empreinte.after_unknown'

true

La sensibilité se propage à travers un local

Dernier piège, et il bloque l'apply. Terraform traite comme sensible toute expression qui utilise une valeur sensible. Un local qui assemble une chaîne à partir d'une variable sensitive = true devient donc lui-même sensible :

variable "mot_de_passe" {
  type      = string
  sensitive = true
}

locals {
  dsn = "postgres://app:${var.mot_de_passe}@localhost/base"
}

Un output qui expose local.dsn sans sensitive = true fait échouer Terraform, dès validate :

Error: Output refers to sensitive values

La correction est d'annoter la sortie sensitive = true. La sensibilité n'est pas une propriété qu'on choisit : elle se propage toute seule à travers les locals, et c'est le piège le plus courant du sous-objectif 2f.

Local, variable ou output ?

Les trois servent à des choses différentes. Le tableau les tranche par ce qu'ils acceptent et par leur portée.

	Peut être typé	Surchargeable de l'extérieur	Visible hors du module
variable	oui (type, validation)	oui (CLI, tfvars)	non
local	non (nom = expression)	non	non
output	non	non	oui

Glissez pour voir

Un point souvent mal compris : un local n'est pas lisible depuis un autre module. Pour transmettre une valeur calculée à un module enfant, on la passe en argument, pas en la lisant directement.

Quand utiliser un local

Dès qu'une expression est répétée ou assez complexe pour gêner la lecture d'une ressource : une expression for, un ternaire imbriqué, un assemblage de chaîne. La documentation met en garde contre l'abus : « Use local values sparingly, as overuse can make your code harder to understand. » Un local utilisé une seule fois et trivial n'apporte rien.

Dépannage

Ces symptômes viennent tous des particularités ci-dessus. Le tableau relie chacun à sa cause réelle.

Symptôme	Cause	Solution
Un calcul échoue sur un local censé être un nombre	Le ternaire a glissé vers une chaîne	Retirer les guillemets, ou convertir avec tonumber
Error: Output refers to sensitive values	Un local dérive d'une variable sensible	Marquer la sortie sensitive = true
Un output est (known after apply) de façon inattendue	Le local dérive d'un attribut de ressource	Normal : la valeur n'existe qu'à l'apply
Un local n'est pas visible dans un autre module	Les locals sont internes au module	Passer la valeur en argument du module enfant

Glissez pour voir

À retenir

1. Un local est un nom pour une expression : ni type, ni description, ni sensitive, contrairement à une variable.
2. Un local peut référencer une variable, un attribut de ressource, une fonction ou un autre local.
3. Plusieurs blocs locals fusionnent ; ils se référencent librement.
4. Le ternaire convertit ses types en silence : 20 : "5" rend une chaîne, pas une erreur.
5. Un local dérivé d'une ressource est inconnu au plan (known after apply).
6. La sensibilité se propage : une sortie dérivant d'une variable sensible doit être marquée sensitive.
7. Un local n'est pas lisible depuis un autre module : passer par un argument.

FAQ : questions fréquentes

Les questions ci-dessous portent sur les comportements qui surprennent le plus : la fusion des blocs, la conversion de type du ternaire, et la propagation de la sensibilité.

Quelle différence entre un local et une variable Terraform ?

Une variable peut être typée, documentée et surchargée depuis l'extérieur. Un local n'est qu'un nom pour une expression : il n'accepte ni type, ni description, ni sensitive, ni validation, et rien ne le surcharge. Ni l'un ni l'autre n'est lisible depuis un autre module.

Que peut référencer un local Terraform ?

Quatre choses, selon la documentation officielle : une variable, un attribut de ressource, la sortie d'une fonction, et un autre local. Référencer un attribut de ressource est ce qui rend un local inconnu au plan, un point que beaucoup de guides omettent.

Plusieurs blocs locals dans un projet, est-ce un problème ?

Non. On peut écrire autant de blocs locals que l'on veut, dans un ou plusieurs fichiers, et Terraform les fusionne. Un local d'un bloc peut en référencer un autre déclaré ailleurs, tant qu'aucune dépendance circulaire n'apparaît.

Pourquoi mon ternaire Terraform renvoie-t-il une chaîne au lieu d'un nombre ?

Parce qu'un ternaire dont les branches n'ont pas le même type ne lève pas d'erreur : Terraform convertit vers un type commun. Un mélange nombre et chaîne, comme 20 : cinq, produit une chaîne. Il faut retirer les guillemets autour des nombres, ou convertir explicitement.

Un local est-il toujours résolu pendant le terraform plan ?

Non. Un local se calcule au plan, sauf s'il référence un attribut de ressource qui n'existe pas encore. Sa valeur est alors known after apply, comme l'attribut dont il dépend. Le plan JSON le montre dans output_changes après_unknown.

Pourquoi Terraform refuse une sortie qui utilise un local ?

Parce que Terraform traite comme sensible toute expression qui utilise une valeur sensible. Un local assemblé à partir d'une variable sensitive devient sensible, et la sortie qui l'expose doit être marquée sensitive, faute de quoi Terraform lève Output refers to sensitive values.

Peut-on lire un local depuis un autre module Terraform ?

Non. Les locals sont internes au module où ils sont définis. Pour transmettre une valeur calculée à un module enfant, il faut la passer en argument du bloc module, jamais la lire directement depuis l'extérieur.

Pour aller plus loin

• Conditions et ternaires : Le ternaire et ses garde-fous, forme la plus fréquente dans un bloc locals.
• Expressions for Terraform : La transformation de collections qui justifie le plus souvent un local nommé.
• Le style guide Terraform : Les conventions officielles sur le placement et le nommage des valeurs locales.

×

📖 Voir la documentation →