sensitive en Terraform : masquer, propager, et ses pièges

L'argument sensitive = true masque une valeur dans l'affichage de Terraform. C'est utile contre les fuites dans les logs, mais dangereux si on le prend pour une protection : la valeur reste en clair dans le state et le plan. Et le marquage a des effets de bord qu'on ne soupçonne pas : il se propage (y compris des modules enfants vers le parent), et il interdit certaines constructions comme for_each.

Ce guide traite ce que sensitive masque et ce qu'il ne masque pas, sa propagation dans les deux sens, la fuite dans le state et le plan, ses effets de bord, les fonctions sensitive() / nonsensitive(), et ephemeral comme vraie exclusion. Tous les comportements ont été vérifiés sur Terraform v1.15.4.

Ce que vous allez apprendre

• Ce que sensitive masque, et ce qu'il ne masque pas
• La propagation, y compris remontante à travers les modules
• La valeur en clair dans le state ET le plan
• L'effet de bord qui casse for_each
• sensitive() / nonsensitive(), et ephemeral comme vraie exclusion

Prérequis

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

Ce que sensitive masque, et ce qu'il ne masque pas

sensitive = true masque la valeur dans la sortie humaine de plan, apply et terraform output :

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

Mais la valeur reste en clair là où on ne la regarde pas. Deux commandes lèvent la redaction, et il faut le savoir :

terraform output -json   # secret en clair
terraform output -raw db_dsn   # secret en clair

Vérifié en 1.15.4 : terraform output -raw rend admin:S3cr3t@db:5432 sans aucun masquage. sensitive est un filtre d'affichage, pas un chiffrement.

La propagation, dans les deux sens

Terraform traite comme sensible toute expression qui utilise une valeur sensible. La contagion descend dans les locals, les attributs de ressources et les outputs. Mais elle remonte aussi : c'est le point le plus mal compris.

Un output marqué sensitive dans un module enfant contamine le module appelant. Un output racine qui l'expose sans être marqué fait échouer le plan :

# module ./enfant
output "child_out" {
  value     = "secret"
  sensitive = true
}

# module racine
output "root_out" {
  value = module.m.child_out # herite du sensible
}

Error: Output refers to sensitive values

La sensibilité remonte des modules

Un guide répandu affirme que le sensible « ne remonte pas vers les blocs parents ». C'est faux, vérifié en 1.15.4. Le caractère sensible d'un output de module enfant remonte bien vers le parent : l'output racine doit être marqué sensitive, ou le plan échoue.

La fuite : state ET plan

sensitive n'enlève rien du fichier d'état. La documentation nomme deux fichiers : « Terraform stores values with the sensitive argument in both state and plan files ». Un terraform.tfstate contient la valeur en clair, et un plan enregistré par -out aussi :

terraform plan -out=tf.plan
terraform show -json tf.plan | jq '.variables.db_password.value'   # en clair

Un plan archivé comme artefact de CI est donc une fuite au même titre que le state. Chiffrez le state (backend distant), restreignez son accès, et ne publiez jamais un fichier de plan.

L'effet de bord qui casse for_each

Voici le piège Professional le plus net, et il casse une configuration qui marchait. Une valeur sensible ne peut pas servir d'argument à for_each :

variable "noms" {
  type      = set(string)
  sensitive = true
}

resource "local_file" "f" {
  for_each = var.noms # interdit
}

Error: Invalid for_each argument

Le message précise « var.noms has a sensitive value ». La raison est logique : Terraform utilise la valeur de for_each comme identifiant d'instance et l'affiche toujours dans l'UI, ce qui divulguerait le secret. Marquer une variable sensitive peut donc casser un for_each existant : le marquage n'est pas sans effet de bord.

sensitive() et nonsensitive()

Deux fonctions dédiées, disponibles depuis la v0.15 :

• sensitive(v) marque une valeur comme sensible dans une expression. La doc la présente comme un pis-aller : « we recommend marking variables and outputs as sensitive directly, which is more reliable ».
• nonsensitive(v) retire la marque, pour publier une valeur dérivée sûre (une empreinte sha256 d'un secret, par exemple) sans désarmer le secret lui-même.

output "empreinte" {
  value = nonsensitive(sha256(var.db_password))
}

nonsensitive() engage votre responsabilité

La doc avertit : « it's your responsibility to ensure that the expression passed as its argument will remove all sensitive content ». Un sha256 est un bon candidat, un substr du secret non. À noter : nonsensitive("plain") sur une valeur déjà non sensible ne lève pas d'erreur en 1.15.4 et rend la valeur telle quelle, malgré ce qu'annonce la page officielle.

Auditer ce qui a été contaminé

Pour savoir ce que la propagation a réellement marqué, terraform show -json expose un objet sensitive_values par ressource :

terraform show -json | jq '.values.root_module.resources[] | {address, sensitive_values}'

Un attribut de ressource alimenté par une valeur sensible y apparaît, et le plan l'affiche content = (sensitive value). C'est la trace exploitable pour auditer la contamination.

La vraie exclusion : ephemeral

Si le besoin est qu'une valeur ne touche jamais le state ni le plan, sensitive ne suffit pas : c'est ephemeral. L'argument ephemeral = true sur un bloc variable ou output (Terraform 1.10) omet la valeur du state et du plan. Les ressources éphémères datent aussi de 1.10 ; seuls les arguments write-only sont arrivés en 1.11.

variable "jeton" {
  type      = string
  ephemeral = true
}

Dépannage

Ces symptômes viennent tous de la propagation ou de la limite d'affichage.

Symptôme	Cause	Solution
Output refers to sensitive values	Un output (racine ou héritant d'un module) expose du sensible non marqué	Ajouter sensitive = true, ou nonsensitive() si la valeur ne divulgue rien
Invalid for_each argument (has a sensitive value)	Une valeur sensible sert de clé for_each	Ne pas utiliser de secret comme clé ; réorganiser la configuration
Un secret apparaît en clair en CI	output -json, -raw ou un plan -out archivé	Chiffrer le state, ne pas publier le plan, ou ephemeral
Marquer une variable sensitive casse le plan	Effet de bord (for_each, contexte d'affichage)	Isoler le secret des clés et des index

Glissez pour voir

À retenir

1. sensitive masque l'affichage, pas le state ni le plan ; -json et -raw rendent la valeur en clair.
2. La sensibilité se propage, y compris des modules enfants vers le parent.
3. La valeur est en clair dans le state ET les fichiers de plan -out.
4. Une valeur sensible ne peut pas servir de clé for_each : Invalid for_each argument.
5. nonsensitive() publie une valeur dérivée sûre ; sensitive() reste un pis-aller.
6. Pour exclure réellement du state, c'est ephemeral (variable/output en 1.10), pas sensitive.

FAQ : questions fréquentes

Les questions ci-dessous reprennent les confusions les plus fréquentes sur sensitive : la propagation, la fuite dans le state, et l'effet de bord sur for_each.

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

Non. sensitive masque la valeur dans l'affichage humain, mais elle reste en clair dans le state ET dans les fichiers de plan -out. terraform output -json et -raw la rendent aussi en clair. La vraie protection est un state chiffré, ou ephemeral pour exclure la valeur.

La sensibilité remonte-t-elle des modules enfants vers le parent ?

Oui. Un output marqué sensitive dans un module enfant contamine le module appelant : un output racine qui l'expose sans être marqué fait échouer le plan avec Output refers to sensitive values. Contrairement à une idée répandue, le sensible remonte bien vers le parent.

Peut-on utiliser une valeur sensible dans un for_each Terraform ?

Non. Une valeur sensible ne peut pas servir d'argument à for_each : le plan échoue avec Invalid for_each argument, has a sensitive value. Terraform utilise la valeur comme identifiant d'instance et l'affiche toujours. Marquer une variable sensitive peut donc casser un for_each existant.

Quelle différence entre sensitive() et nonsensitive() en Terraform ?

sensitive() marque une valeur comme sensible dans une expression, mais reste un pis-aller : la doc recommande de marquer directement les variables et outputs. nonsensitive() retire la marque, pour publier une valeur dérivée sûre comme un hash, sous votre responsabilité qu'elle ne divulgue rien.

Un fichier de plan Terraform contient-il les valeurs sensibles ?

Oui, en clair. La documentation nomme deux fichiers : Terraform stocke les valeurs sensibles dans le state ET dans les fichiers de plan. Un plan enregistré par -out et archivé comme artefact de CI est donc une fuite au même titre que le state.

Comment savoir quels attributs Terraform a marqués sensibles ?

En lisant l'objet sensitive_values que terraform show -json expose pour chaque ressource. Un attribut alimenté par une valeur sensible y apparaît, et le plan l'affiche content = sensitive value. C'est la trace exploitable pour auditer ce que la propagation a réellement contaminé.

Faut-il utiliser sensitive ou ephemeral pour un secret Terraform ?

sensitive masque l'affichage mais laisse la valeur dans le state et le plan. ephemeral exclut réellement la valeur du state et du plan : sur une variable ou un output, l'argument ephemeral = true (Terraform 1.10) l'omet. Pour un secret qui ne doit jamais toucher le disque, c'est ephemeral.

Pour aller plus loin

• Les arguments write-only : L'argument qui n'est jamais enregistré, là où sensitive se contente de masquer.
• Quiz Écrire du code Terraform : Un contrôle des acquis sur les variables, les outputs et le traitement des secrets.
• Comprendre le state Terraform : L'endroit exact où les valeurs marquées sensitive restent écrites en clair.

×

📖 Voir la documentation →