Blocs dynamiques Terraform : générer des blocs imbriqués

Un bloc dynamic génère des blocs imbriqués à partir d'une collection, là où le schéma du provider expose un bloc répétable (ingress, setting, source, part). C'est l'outil quand le nombre de ces blocs dépend d'une variable plutôt que d'une écriture à la main.

Ce guide part de la base, écrire un dynamic et lire ce qu'il produit, puis couvre les formes avancées (iterator, imbrication) et le mur que tout le monde rencontre un jour : un dynamic ne peut pas générer un bloc de méta-arguments comme lifecycle. Les exemples exécutables ont été vérifiés sur Terraform v1.15.4 avec le provider local hashicorp/archive, sans cloud.

Ce que vous allez apprendre

• Ce qu'est un bloc dynamic et quand il est justifié
• L'écrire : for_each, content, et la variable d'itération
• Filtrer dans le for_each, jamais dans le content
• Renommer la variable avec iterator, et pourquoi c'est parfois obligatoire
• Le piège de .key sur un set
• Imbriquer un dynamic dans un autre
• Le mur des méta-arguments : lifecycle et provisioner ne se génèrent pas

Prérequis

• Le meta-argument for_each (for_each Terraform)
• Les expressions for (expressions for Terraform)
• Terraform 1.15.x, la série stable courante

Qu'est-ce qu'un bloc dynamic ?

Un bloc dynamic remplace plusieurs blocs imbriqués identiques par un seul bloc qui les génère. Là où vous écririez trois blocs ingress à la main, un dynamic "ingress" les produit depuis une liste de règles. Il ne s'applique qu'aux blocs répétables du provider : un attribut ou un bloc de méta-arguments ne se génèrent pas ainsi.

Un dynamic a trois parties : son label, qui nomme le bloc à produire ; sa for_each, la collection à parcourir ; son bloc content, qui décrit un bloc généré. Une variable d'itération, nommée par défaut comme le label, donne accès à l'élément courant.

Écrire un bloc dynamic

Voici un dynamic "source" sur une data source archive_file, dont le bloc source est répétable :

locals {
  entrees = {
    "config.yaml" = "cle: valeur\n"
    "notes.txt"   = "rien a signaler\n"
  }
}

data "archive_file" "bundle" {
  type        = "zip"
  output_path = "${path.module}/bundle.zip"

  dynamic "source" {
    for_each = local.entrees
    content {
      filename = source.key
      content  = source.value
    }
  }
}

output "nb_fichiers" {
  value = length(data.archive_file.bundle.source)
}

Le bloc génère autant de blocs source que la map compte d'entrées. La variable source porte le nom du label et expose source.key et source.value. Après apply :

terraform output nb_fichiers

2

Deux entrées, deux blocs générés.

Filtrer dans le for_each, jamais dans le content

C'est l'erreur la plus fréquente. Pour n'inclure qu'une partie des éléments, on filtre la collection, dans le for_each, avec une expression for :

dynamic "source" {
  for_each = { for k, v in local.entrees : k => v if length(v) > 0 }
  content {
    filename = source.key
    content  = source.value
  }
}

Un if dans le content n'aurait aucun effet : à ce stade, le bloc est déjà décidé. Le nombre de blocs se règle en amont, sur la collection passée à for_each.

Renommer la variable avec iterator

Par défaut, la variable d'itération porte le nom du label. L'argument iterator la renomme :

dynamic "source" {
  for_each = local.entrees
  iterator = fichier
  content {
    filename = fichier.key
    content  = fichier.value
  }
}

Ce n'est pas qu'un confort. C'est obligatoire quand un dynamic en contient un autre du même nom : sans iterator, les deux variables porteraient le même label et la référence serait ambiguë. La documentation officielle en fait la solution recommandée dans ce cas.

Le piège de key sur un set

for_each accepte une map ou un set. Sur un set, une subtilité documentée : key est identique à value, et ne devrait pas être utilisé.

locals {
  lignes = toset(["alpha", "bravo"])
}

dynamic "source" {
  for_each = local.lignes
  content {
    filename = "${source.key}.txt"
    content  = source.value
  }
}

["alpha.txt", "bravo.txt"]

source.key vaut ici "alpha" puis "bravo", exactement comme source.value. Réservez source.key aux maps, où la clé porte une information propre ; sur un set, tenez-vous-en à source.value.

Imbriquer un dynamic dans un autre

Quand un bloc répétable contient lui-même un bloc répétable, on imbrique deux dynamic. Le bloc content du premier héberge le second. C'est là que iterator devient indispensable, pour distinguer les deux niveaux :

dynamic "origin_group" {
  for_each = var.groupes
  iterator = groupe
  content {
    name = groupe.key

    dynamic "origin" {
      for_each = groupe.value.origines
      iterator = origine
      content {
        hostname = origine.value
      }
    }
  }
}

Le second for_each parcourt une valeur du premier (groupe.value.origines). Sans les deux iterator, les variables origin_group et origin seraient confondues.

Exemple non exécuté ici

Ce motif d'imbrication vient d'une ressource cloud (type CDN) à deux niveaux de blocs. Il illustre la syntaxe ; les exemples exécutables de ce guide restent sur le provider local archive, qui n'expose qu'un niveau de bloc répétable.

Le mur : dynamic ne génère pas un méta-argument

Un dynamic répète un bloc du provider. Il ne peut pas générer un bloc de méta-arguments comme lifecycle ou provisioner. La raison est documentée : « It is not possible to generate meta-argument blocks such as lifecycle and provisioner blocks, since Terraform must process these before it is safe to evaluate expressions. » Ces blocs sont traités avant l'évaluation des expressions, donc avant qu'un dynamic puisse produire quoi que ce soit.

Si vous tentez un dynamic sur un bloc que le contexte n'attend pas, le message d'erreur nomme le label visé, jamais le mot dynamic :

dynamic "reglage" {
  for_each = [1]
  content { option = reglage.value }
}

Error: Unsupported block type
Blocks of type "reglage" are not expected here.

Le même message apparaît pour un dynamic "lifecycle" : Blocks of type "lifecycle" are not expected here. Un bloc lifecycle s'écrit toujours littéralement.

L'argument labels

Certains blocs répétables portent un label (comme setting chez un provider). L'argument labels d'un dynamic fournit ces labels, dans l'ordre, et peut utiliser la variable d'itération :

dynamic "setting" {
  for_each = var.reglages
  labels   = [setting.key]
  content {
    value = setting.value
  }
}

C'est le seul moyen de générer des blocs qui exigent un label, que le bloc content seul ne saurait poser.

À utiliser avec parcimonie

Un dynamic rend la configuration plus difficile à lire qu'une suite de blocs littéraux, et la documentation le déconseille pour les cas simples : « Overuse of dynamic blocks can make configuration hard to read and maintain. » Réservez-le aux blocs dont le nombre dépend vraiment d'une variable. Un bloc qui ne varie jamais, comme un en-tête commun, reste littéral, y compris au milieu d'un ensemble par ailleurs dynamique.

Dépannage

Ces messages ont été relevés au mot près sur Terraform v1.15.4. Le premier est le plus trompeur : il nomme le bloc visé, pas le mot dynamic.

Message	Cause	Solution
Unsupported block type / Blocks of type "X" are not expected here.	Un dynamic sur un bloc absent du schéma, ou sur un méta-argument (lifecycle)	Vérifier que le provider expose bien un bloc X répétable ; écrire les méta-arguments littéralement
Missing item separator / Expected a comma to mark the beginning of the next item.	Une liste mal formée passée à for_each, souvent une virgule oubliée	Corriger la syntaxe de la collection
Un bloc généré de trop, ou de moins	Un if posé dans le content au lieu du for_each	Filtrer la collection dans le for_each
Deux niveaux de dynamic qui se mélangent	Variables d'itération homonymes	Nommer chaque niveau avec iterator

Glissez pour voir

À retenir

1. Un dynamic génère des blocs répétables du provider, jamais un attribut ni un bloc de méta-arguments.
2. Sa for_each fournit la collection, son content décrit un bloc, la variable d'itération porte le nom du label par défaut.
3. On filtre dans le for_each, avec une expression for ; un if dans le content n'a aucun effet.
4. iterator renomme la variable, et devient obligatoire pour imbriquer deux dynamic.
5. Sur un set, key égale value : n'utilisez key que sur une map.
6. lifecycle et provisioner ne se génèrent pas : Terraform les traite avant d'évaluer les expressions. Le message d'erreur nomme le label du bloc.
7. labels fournit les labels des blocs qui en exigent.
8. À réserver aux blocs dont le nombre varie ; sinon, du littéral, plus lisible.

FAQ : questions fréquentes

Les questions ci-dessous portent sur ce qui coince le plus : les blocs qu'un dynamic ne peut pas générer, l'endroit où filtrer, et le message d'erreur qui pointe le label du bloc. Chaque réponse donne la vérification correspondante.

À quoi sert un bloc dynamic en Terraform ?

À générer plusieurs blocs imbriqués identiques à partir d'une collection, quand leur nombre dépend d'une variable. Il ne s'applique qu'aux blocs répétables exposés par le schéma du provider, comme ingress ou setting.

Pourquoi mon dynamic lifecycle échoue-t-il ?

Parce qu'un bloc de méta-arguments ne se génère pas : Terraform les traite avant d'évaluer les expressions. Le message est Blocks of type lifecycle are not expected here. Le bloc lifecycle doit être écrit littéralement.

Comment filtrer les blocs générés par un dynamic ?

Dans le for_each, avec une expression for et une clause if qui écarte les éléments non voulus. Un if placé dans le bloc content n'a aucun effet, car le bloc est déjà décidé à ce stade.

Quand faut-il l'argument iterator dans un bloc dynamic ?

Pour renommer la variable d'itération, et obligatoirement quand un dynamic en contient un autre. Sans iterator, les deux variables porteraient le même label, celui du bloc, et deviendraient impossibles à distinguer.

Que valent .key et .value sur un set dans un dynamic ?

La même chose : sur un set, key est identique à value. La distinction n'a de sens que sur une map, où key porte la clé et value la valeur. Sur un set, il faut utiliser value et ignorer key.

Quel message d'erreur si le provider n'a pas le bloc que je génère ?

Le message est Unsupported block type, Blocks of type X are not expected here, où X est le label de votre dynamic, jamais le mot dynamic lui-même. C'est ce qui permet d'identifier le bloc fautif.

Faut-il tout passer en bloc dynamic ?

Non. La documentation le déconseille pour les cas simples, car un dynamic est moins lisible qu'une suite de blocs littéraux. Il se réserve aux blocs dont le nombre dépend vraiment d'une variable ou d'une collection.

Pour aller plus loin

• Le bloc lifecycle : Détaille les sept règles du bloc, qui s'écrit toujours littéralement.
• Le style guide Terraform : Fixe les conventions d'écriture qui gardent un dynamic lisible.
• Structure d'un module : Range les blocs générés dans un module, là où dynamic sert le plus.

×

📖 Voir la documentation →