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 ou plus récent (comportements vérifiés sur la v1.15.4)

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, si bien qu'un local d'apparence anodine peut rendre sensible une sortie qui ne l'était pas.

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

Mettre en pratique

Vous centralisez des expressions dans des blocs locals : normalisation par des fonctions HCL, ternaire typé, liste produite par une expression for. Le cas instructif est le dernier, et il donne son titre au lab : un local dérivé d'un attribut de ressource reste inconnu au plan, ce qui change ce que Terraform peut vous montrer avant l'apply.

Lab guidé Pratique

Apprendre à faire

Le local qui ne se calcule pas au plan

$ dsoxlab run write-code-locals

Environnement : Shell·Durée : ~45 min

Vérification : la sortie produite est comparée au résultat attendu.

Première fois ? Qu'est-ce que DSOXLab et comment l'installer

DSOXLab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Il faut Python 3.11 ou plus récent, uv ou pipx, et git. Le guide d'installation détaille ces prérequis ; sous Windows, ou sur un Mac sans Python, passez plutôt par l'appliance.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/terraform-dsoxlab-training

Avant de lancer le lab, vérifiez :

• DSOXLab installé
• catalogue disponible
• environnement compatible (shell isolé ou VM)

Pour le vérifier, rien n'est sondé depuis cette page : lancez dsoxlab doctor. Lire le diagnostic

Lancer ce lab, puis valider votre travail :

dsoxlab run write-code-locals
dsoxlab check write-code-locals

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille le calcul du score et les pièges.

À 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.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

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 ?

Que peut référencer un local Terraform ?

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

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

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

Pourquoi Terraform refuse une sortie qui utilise un local ?

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

×

📖 Voir la documentation →