Expressions for Terraform : filtrer, regrouper, aplatir une collection

Une expression for en HCL transforme une collection en une autre : filtrer une liste, pivoter une map, regrouper par clé, croiser deux niveaux. Elle ne crée aucune ressource, c'est le rôle de for_each ; elle dérive une valeur à partir d'une collection existante, et on la trouve surtout dans les locals et les outputs.

Ce guide part de la base, la syntaxe et la distinction tuple / object, puis couvre les formes avancées et les deux pièges qui coûtent le plus cher : le splat sur une map, qui ne lève aucune erreur, et le regroupement par ellipsis, mal connu. Tous les exemples ont été vérifiés sur Terraform v1.15.4 dans terraform console, avec le seul provider local.

Ce que vous allez apprendre

• Pourquoi [ ] produit un tuple et { } un object, sans confusion possible
• Filtrer avec une clause if, sur la clé comme sur la valeur
• Regrouper les valeurs d'une clé partagée avec l'ellipsis ...
• Croiser deux niveaux avec des boucles imbriquées et flatten
• Le piège du splat [*] appliqué à une map
• Ce qu'une expression for ne peut pas faire, et quand passer à dynamic

Prérequis

• Types et collections (déclarer des ressources Terraform)
• Le meta-argument for_each (for_each Terraform)
• Terraform 1.15.x, la série stable courante

Tester une expression sans écrire de ressource

terraform console évalue une expression en trois secondes, sans apply ni ressource. C'est l'outil pour éprouver un for avant de le poser dans un local. Toutes les sorties de ce guide en proviennent, avec cette donnée de travail :

locals {
  equipes = {
    alpha = { pole = "produit", effectif = 4, competences = ["go", "k8s"] }
    bravo = { pole = "produit", effectif = 6, competences = ["go"] }
    delta = { pole = "data", effectif = 3, competences = [] }
  }
}

terraform console

Tuple ou object : la forme des délimiteurs décide

C'est la distinction fondatrice du sujet. Des crochets [ ] produisent un tuple, des accolades { } produisent un object. Terraform ne confond jamais les deux, et la fonction type() le prouve :

> type([for k, v in local.equipes : k])
tuple([string, string, string])

> type({for k, v in local.equipes : k => v.effectif})
object({alpha: number, bravo: number, delta: number})

La forme object porte une flèche clé => valeur que le tuple n'a pas. Cette distinction n'est pas cosmétique : for_each exige une map ou un set, jamais un tuple, et c'est la source d'erreur numéro un quand on alimente un for_each depuis un for.

Filtrer avec une clause if

La forme la plus courante extrait une sous-liste. On itère la map et on ne garde que ce qu'une clause if, placée après l'expression, laisse passer :

> [for k, v in local.equipes : k if v.pole == "produit"]
[
  "alpha",
  "bravo",
]

Deux points à retenir. L'ordre de sortie n'est pas aléatoire : une expression for sur une map itère les clés triées lexicalement, inutile de réordonner. Et la condition voit les deux variables d'itération, la clé comme la valeur, on peut donc filtrer sur la clé :

> [for k, v in local.equipes : k if k != "delta"]
[
  "alpha",
  "bravo",
]

Construire une map

Avec des accolades et une flèche, la même itération produit un object. La clé et la valeur sont libres :

> {for k, v in local.equipes : k => v.effectif}
{
  "alpha" = 4
  "bravo" = 6
  "delta" = 3
}

Regrouper avec l'ellipsis

Que se passe-t-il quand deux entrées produisent la même clé ? Par défaut, Terraform refuse. alpha et bravo appartiennent toutes deux au pôle produit :

> {for k, v in local.equipes : v.pole => k}

Error: Duplicate object key

Two different items produced the key "produit" in this 'for' expression. If
duplicates are expected, use the ellipsis (...) after the value expression to
enable grouping by key.

Le message d'erreur donne lui-même la solution : l'ellipsis ... après l'expression de valeur active le mode groupement. Chaque clé porte alors la liste des valeurs correspondantes :

> {for k, v in local.equipes : v.pole => k...}
{
  "data" = [
    "delta",
  ]
  "produit" = [
    "alpha",
    "bravo",
  ]
}

L'ellipsis n'existe qu'avec des accolades. L'appliquer à un tuple échoue :

> [for k, v in local.equipes : k...]

Error: Invalid 'for' expression
Grouping ellipsis (...) cannot be used when building a tuple.

C'est logique : grouper n'a de sens que par clé, donc dans un object.

Croiser deux niveaux : boucles imbriquées et flatten

Dès qu'il faut combiner deux dimensions, chaque équipe et chacune de ses compétences, on imbrique deux for. Le résultat est une liste de listes, qu'on aplatit avec flatten :

> flatten([for k, v in local.equipes : [for comp in v.competences : "${k}:${comp}"]])
[
  "alpha:go",
  "alpha:k8s",
  "bravo:go",
]

Notez delta : sa liste de compétences est vide, la boucle interne ne produit rien, et flatten l'absorbe. Aucune entrée delta: dans le résultat, sans une seule clause if pour l'exclure. C'est le motif standard pour dérouler des paires (serveurs × tags, régions × sous-réseaux) vers un for_each.

Le splat, et son piège sur une map

Terraform propose une forme courte, le splat [*], qui remplace un for simple sur une liste : var.liste[*].id équivaut à [for o in var.liste : o.id]. Pratique, mais réservé aux listes.

Sur une map, le splat devient un piège, parce qu'il ne lève aucune erreur. Il enveloppe la map entière dans un tuple d'un seul élément :

> length(local.equipes[*])
1

1, et non 3. La configuration continue de valider, puis casse plus loin, là où on attendait trois entrées. Une ressource pilotée par for_each étant elle-même une map, le splat lui est tout aussi inadapté.

Sur une map, jamais de splat

Le splat [*] sur une map ne produit pas d'erreur : il renvoie un tuple d'un seul élément contenant la map. Utilisez toujours une expression for explicite pour parcourir une map ou une ressource for_each.

Valider une collection entière

Combinée à alltrue, une expression for vérifie une propriété sur chaque élément d'une collection, ce qu'une comparaison simple ne sait pas faire :

> alltrue([for k, v in local.equipes : v.effectif > 0])
true

C'est le motif pour valider une variable de type complexe : alltrue rend true seulement si la condition tient pour toutes les entrées. Son pendant anytrue teste l'existence d'au moins un élément conforme.

Alimenter un for_each depuis un for

C'est le cas d'usage qui relie ce guide à for_each. Comme for_each exige une map ou un set de chaînes, on lui passe une expression for filtrée :

resource "local_file" "fiche" {
  for_each = { for k, v in local.equipes : k => v if v.effectif >= 4 }

  filename = "${path.module}/${each.key}.txt"
  content  = each.value.pole
}

Deux erreurs classiques ici. Passer un tuple ([for ...]) échoue : for_each répond « the for_each argument must be a map, or set of strings ». Passer un toset de nombres échoue aussi : « for_each supports maps and sets of strings, but you have provided a set containing type number ». La restriction aux chaînes est réelle.

Ce qu'une expression for ne sait pas faire

Une expression for ne génère que des valeurs de collection. Elle ne peut pas produire des blocs de configuration imbriqués. Pour répéter un bloc ingress, setting ou network_interface à l'intérieur d'une ressource, c'est un bloc dynamic qu'il faut, pas un for. La documentation officielle est explicite : « For expressions can only generate collection values, and cannot generate nested configuration blocks. Use dynamic blocks instead. » Confondre les deux est une impasse fréquente.

Dépannage

Ces erreurs se lisent toutes au moment du plan ou dans terraform console. Le tableau donne le message exact relevé sur v1.15.4, sa cause, puis la correction.

Message	Cause	Solution
Error: Duplicate object key	Deux entrées produisent la même clé dans un { for ... }	Ajouter l'ellipsis ... après la valeur pour grouper
Grouping ellipsis (...) cannot be used when building a tuple	Un ... dans un [ for ... ]	Le groupement n'existe qu'avec des accolades
the "for_each" argument must be a map, or set of strings	Un tuple ou une liste passés à for_each	Produire une map { for ... } ou un toset() de chaînes
"for_each" supports maps and sets of strings, but you have provided a set containing type number	Un toset([1,2,3])	Convertir en chaînes, ou utiliser une map
Une longueur inattendue de 1	Un splat [*] appliqué à une map	Remplacer par une expression for explicite

Glissez pour voir

À retenir

1. Crochets [ ] produisent un tuple, accolades { } un object. La forme des délimiteurs dicte le type de sortie.
2. La clause if se place après l'expression et voit la clé comme la valeur.
3. Une expression for sur une map trie les clés lexicalement.
4. Deux entrées produisant la même clé exigent l'ellipsis ..., qui groupe les valeurs en listes ; sinon Terraform lève Duplicate object key.
5. Deux for imbriqués plus flatten croisent deux niveaux ; les entrées à liste vide disparaissent d'elles-mêmes.
6. Le splat [*] sur une map ne lève pas d'erreur et renvoie un tuple d'un seul élément : sur une map, toujours une expression for.
7. for_each veut une map ou un set de chaînes, jamais un tuple.
8. Une expression for ne génère pas de blocs de configuration : pour cela, un bloc dynamic.

FAQ : questions fréquentes

Les questions ci-dessous portent sur les points où la syntaxe surprend : le type produit selon le délimiteur, le splat qui ne parcourt pas une map, et ce que for_each accepte en sortie. Chaque réponse donne la commande de vérification à rejouer dans terraform console.

Quelle différence entre [for ...] et {for ...} en Terraform ?

Les crochets produisent un tuple, une suite ordonnée de valeurs. Les accolades produisent un object, des clés associées à des valeurs, et la forme s'écrit alors clé => valeur. Le type résultant se vérifie avec la fonction type().

Comment regrouper plusieurs valeurs sous une même clé avec une expression for ?

Avec l'ellipsis, trois points placés après l'expression de valeur. Chaque clé porte alors la liste des valeurs qui lui correspondent. Sans l'ellipsis, deux entrées produisant la même clé provoquent l'erreur Duplicate object key.

Pourquoi mon splat [*] sur une map renvoie-t-il une longueur de 1 ?

Parce que le splat est conçu pour les listes et les tuples. Appliqué à une map, il l'enveloppe entière dans un tuple d'un seul élément au lieu de lever une erreur. La parade est une expression for explicite sur la map.

Comment croiser deux collections imbriquées avec une expression for ?

En imbriquant deux expressions for dans des crochets, puis en aplatissant le résultat avec flatten. Les entrées dont la liste interne est vide disparaissent naturellement, sans traitement particulier.

Une expression for peut-elle générer un bloc dynamic ou ingress ?

Non. Une expression for ne produit que des valeurs de collection, tuple ou object. Pour répéter un bloc de configuration imbriqué comme ingress, il faut un bloc dynamic, qui est un mécanisme distinct.

Peut-on filtrer une expression for sur la clé plutôt que sur la valeur ?

Oui. La clause if d'une expression for voit les deux variables d'itération, la clé et la valeur. Il est donc possible de filtrer sur la clé, sur la valeur, ou sur une combinaison des deux.

for_each accepte-t-il le résultat d'une expression for ?

Oui, à condition que le résultat soit une map ou un set de chaînes. Un tuple issu de la forme crochets est refusé, comme un set de nombres. Il faut produire une map avec la forme accolades.

Pour aller plus loin

• Le bloc lifecycle Terraform : Le contrôle de la recréation des ressources produites par une expression for.
• Le style guide Terraform : Les conventions qui gardent lisible une compréhension for imbriquée.
• Quiz Écrire du code Terraform : Un contrôle des acquis sur variables, expressions et transformations de collections.

×

📖 Voir la documentation →