Valeurs éphémères Terraform : le secret hors du state

Une valeur éphémère existe pendant une opération Terraform, puis disparaît : elle n'est jamais écrite dans le state ni dans le plan. C'est la seule réponse réelle au problème que sensitive ne résout pas, puisque sensitive laisse la valeur en clair dans l'état. Le déclarer est simple ; les pièges sont dans la règle d'or (jamais dans un attribut persisté) et dans les deux erreurs que le module racine renvoie.

Ce guide part de la base, le bloc ephemeral, puis traite les contextes autorisés, ephemeralasnull(), les variables éphémères et la preuve. L'éphémère est arrivé en Terraform 1.10, et tout ce guide tourne dès cette version, sur 1.15.4 (vérifié) avec random >= 3.7 pour ephemeral "random_password".

Ce que vous allez apprendre

• Déclarer une valeur éphémère avec le bloc ephemeral
• La règle d'or : jamais dans un attribut persisté
• Les contextes autorisés, et les deux erreurs du module racine
• ephemeralasnull() pour exposer sans fuiter
• Les variables et outputs éphémères, et comment le prouver

Prérequis

• Les données sensibles (sensitive en Terraform)
• Terraform 1.10 ou plus (1.15.x recommandé), et random >= 3.7

Déclarer une valeur éphémère

Un bloc ephemeral produit une valeur générée à la volée, jamais persistée. On la référence par ephemeral.<TYPE>.<NOM>.<ATTR> :

ephemeral "random_password" "session" {
  length = 24
}

ephemeral.random_password.session.result est disponible pendant le run, mais n'apparaît nulle part dans le state. Contrairement à un random_password ordinaire, dont le result est stocké en clair dans l'état, l'éphémère ne laisse aucune trace sur le disque. Son cycle de vie se déroule en open / renew / close pendant l'opération, invisible dans l'état.

La règle d'or : jamais dans un attribut persisté

Une valeur éphémère ne peut aller que dans des contextes éphémères. La lui faire toucher un attribut persisté lève une erreur nette :

resource "local_file" "fuite" {
  content = ephemeral.random_password.session.result # interdit
}

Error: Invalid use of ephemeral value

Le détail du message est explicite : « Ephemeral values are not valid for "content", because it is not a write-only attribute and must be persisted to state. » Les contextes autorisés, au nombre de sept, sont : un argument write-only d'une ressource, un autre bloc ephemeral, un local consommé uniquement en contexte éphémère, une variable ephemeral = true, une configuration de provider, un provisioner (et sa configuration de connexion), et un output éphémère de module enfant.

Les deux erreurs du module racine

Au niveau racine, un output ne peut pas porter d'éphémère, et cela se manifeste de deux façons distinctes, à ne pas confondre :

• déclarer un output ephemeral = true à la racine renvoie Ephemeral output not allowed : « Ephemeral outputs are not allowed in context of a root module » ;
• exposer dans un output racine ordinaire une valeur dérivée d'un éphémère, même sa simple longueur, renvoie Ephemeral value not allowed.

C'est ce second cas que l'on rencontre en premier, dès qu'on essaie d'afficher un éphémère « pour voir ». La sensibilité éphémère se propage : length(ephemeral...) est encore éphémère.

ephemeralasnull() : exposer sans fuiter

Comment, alors, exposer quelque chose au root sans casser le run ? La fonction ephemeralasnull() rend null toute valeur éphémère hors contexte éphémère :

output "session_masquee" {
  value = ephemeralasnull(ephemeral.random_password.session.result)
}

L'output vaut null. Ce n'est pas un affichage du secret, c'est sa neutre mise à l'écart : la valeur éphémère ne franchit pas la frontière du state. Sur une valeur non éphémère, ephemeralasnull() renvoie la valeur telle quelle, ce qui en fait aussi un bon révélateur : un null prouve que l'entrée était bien éphémère.

Variables et outputs éphémères

Depuis Terraform 1.10, une variable peut être ephemeral = true : sa valeur alimente le run mais n'est jamais persistée. Un output de module enfant peut l'être aussi, pour faire remonter un éphémère vers le module appelant sans jamais l'écrire.

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

1.10, pas 1.11

Les variables et outputs éphémères datent de Terraform 1.10 (« Input variables and outputs can now be defined as ephemeral »), pas de 1.11. La 1.11 apporte les arguments write-only, un sujet distinct. Ne posez pas un required_version = ">= 1.11.0" pour du contenu qui tourne dès la 1.10.

Comment le prouver

La preuve utile ne se lit pas dans les seuls values.outputs : une valeur éphémère ne peut de toute façon jamais s'y trouver, donc le contrôle passerait même sans rien avoir fait d'éphémère. La bonne preuve porte sur l'intégralité du state et sur le plan converti en JSON :

terraform show -json | jq '[.values.root_module.resources[].address]'

L'éphémère n'apparaît nulle part dans cette liste, là où un random_password ordinaire y figure avec son result en clair. C'est le contraste qui prouve qu'une valeur a bien été tenue hors du state.

Dépannage

Ces symptômes viennent tous de la frontière entre éphémère et persisté.

Symptôme	Cause	Solution
Invalid use of ephemeral value	Un éphémère dans un attribut persisté	Le déplacer vers un contexte éphémère (write-only, provider, local éphémère)
Ephemeral value not allowed	Un output racine dérive d'un éphémère	L'envelopper dans ephemeralasnull(), ou ne pas l'exposer
Ephemeral output not allowed	Un output racine déclaré ephemeral = true	Réserver les outputs éphémères aux modules enfants
ephemeral "random_password" inconnu	Provider random trop ancien	Exiger random >= 3.7.0
Un secret apparaît dans le state	Une ressource ordinaire au lieu d'éphémère	Passer le bloc en ephemeral

Glissez pour voir

À retenir

1. Une valeur éphémère n'est jamais écrite dans le state ni le plan.
2. Elle ne va que dans un contexte éphémère ; ailleurs, Invalid use of ephemeral value.
3. Le module racine renvoie deux erreurs distinctes : Ephemeral output not allowed et Ephemeral value not allowed.
4. ephemeralasnull() expose une valeur éphémère en null, sans la fuiter.
5. Variables et outputs éphémères datent de 1.10 ; ephemeral "random_password" demande random >= 3.7.
6. La preuve porte sur tout le state, pas sur les seuls outputs.

FAQ : questions fréquentes

Les questions ci-dessous reprennent les confusions les plus fréquentes sur les valeurs éphémères : la différence avec sensitive, la règle d'or, et ephemeralasnull().

Quelle différence entre ephemeral et sensitive en Terraform ?

sensitive masque la valeur dans l'affichage humain mais la conserve en clair dans le state et le plan. ephemeral exclut réellement la valeur : elle est générée pendant l'opération et n'est jamais écrite dans le state ni le plan. Pour un secret qui ne doit jamais toucher le disque, c'est ephemeral.

Comment déclarer une valeur éphémère en Terraform ?

Avec un bloc ephemeral, référencé par ephemeral.TYPE.NOM.ATTR. La ressource ephemeral random_password demande le provider random 3.7 ou plus. Les variables et outputs éphémères, eux, existent depuis Terraform 1.10 via l'argument ephemeral = true.

Pourquoi ai-je l'erreur Invalid use of ephemeral value ?

Parce qu'une valeur éphémère a été placée dans un attribut persisté, qui doit être écrit dans le state. Une valeur éphémère ne peut aller que dans un contexte éphémère : argument write-only, autre bloc ephemeral, config de provider, provisioner, local ou variable éphémère.

Comment exposer une valeur éphémère dans un output Terraform ?

Au niveau racine, on ne peut pas exposer directement un éphémère : cela lève Ephemeral value not allowed. Il faut l'envelopper dans ephemeralasnull(), qui rend null toute valeur éphémère hors contexte éphémère. Un output ephemeral = true est réservé aux modules enfants.

Les variables éphémères datent-elles de Terraform 1.11 ?

Non, de Terraform 1.10 : le CHANGELOG de la 1.10.0 indique que les variables et outputs peuvent être définis comme éphémères. La 1.11 apporte les arguments write-only, un sujet distinct. Poser required_version >= 1.11 pour du contenu éphémère est plus strict que nécessaire.

Comment prouver qu'une valeur n'est pas dans le state Terraform ?

En lisant l'intégralité du state avec terraform show -json, pas seulement values.outputs. Une valeur éphémère ne peut de toute façon jamais figurer dans un output racine, donc ce contrôle passerait même sans rien d'éphémère. La preuve porte sur toutes les ressources du state.

Quel provider faut-il pour ephemeral random_password ?

Le provider hashicorp/random en version 3.7.0 ou plus : la ressource éphémère random_password y a été ajoutée le 25 février 2025. Avec une contrainte plus ancienne, l'init échoue ou le bloc ephemeral random_password est inconnu.

Pour aller plus loin

• Comprendre le state Terraform : Détaille ce que le state enregistre en clair, et pourquoi un secret n'y a pas sa place.
• Les backends Terraform : Compare les backends et leur chiffrement au repos, seconde ligne de défense.
• Quiz Écrire du code Terraform : Vérifie les acquis de la section, gestion des données sensibles comprise.

×

📖 Voir la documentation →