In Terraform, what is the iterator argument of a dynamic block for, and what do key and value hold when for_each is a list versus a set?

## The default is the label A dynamic block introduces one temporary variable, visible only inside its `content` block, that represents the current element. Its name defaults to the dynamic block's label. This is a small but frequently-missed detail: people reach for `each.value` out of habit, because that is what a resource-level `for_each` provides, and get an error saying there is no such variable. ```hcl dynamic "ingress" { for_each = var.ports content { from_port = ingress.value # named after the label to_port = ingress.value } } ``` ## What iterator changes `iterator` sets that variable's name explicitly: ```hcl dynamic "ingress" { for_each = var.ports iterator = port content { from_port = port.value to_port = port.value } } ``` Nothing else changes — it is purely a naming argument. Two reasons to use it: 1. **Nesting.** A dynamic block can appear inside another dynamic block's `content`, generating a nested block inside a generated block. Both iterators are in scope inside the inner content, and if the same block type nests inside itself the default names would collide. Renaming one of them keeps the two levels distinguishable. 2. **Readability.** Provider block labels are often generic (`setting`, `rule`, `statement`). `iterator = target_group` in the middle of a forty-line content body says more than `statement.value` does. ## Key and value by collection type The temporary variable always exposes exactly two attributes, `.key` and `.value`, but what they mean follows the collection: | for_each | .key | .value | | --- | --- | --- | | list | element index (0, 1, 2…) | the element | | map | the map key | the map value | | set | identical to .value | the element | The set row is the trap. Terraform's documentation states that with a set, `key` is identical to `value` and should not be used. It exists only so the shape of the variable is uniform. Anyone who writes `ingress.key` expecting a stable name while feeding a `set(string)` is really just re-reading the value. A further consequence: with a **map**, elements come out sorted by key, since Terraform maps are ordered lexically. With a **list**, the configuration order is preserved. This matters when the block type being generated is order-sensitive. Note also that a dynamic block's `for_each` accepts a list, which a resource's `for_each` does not — a resource needs a map or a set of strings because it must derive stable instance keys for state. Generated blocks have no state addresses of their own, so an index-keyed list is acceptable here. ## Nesting in practice A nested dynamic block is how you generate a block that itself contains repeated blocks — for example a set of lifecycle rules where each rule carries its own list of storage transitions: ```hcl dynamic "rule" { for_each = var.lifecycle_rules iterator = lc content { id = lc.key status = "Enabled" dynamic "transition" { for_each = lc.value.transitions content { days = transition.value.days storage_class = transition.value.storage_class } } } } ``` The inner `for_each` reads `lc.value.transitions` — the outer iterator remains in scope, which is the whole point of nesting rather than flattening. Note that this only works because the outer element is an object carrying its own inner collection; if your data is flat, a `for` expression that groups it first is usually clearer than a second level of nesting. ## Where nesting stops being worth it Two levels of generation is roughly where a reviewer loses the thread: they can no longer tell from the source what the applied resource looks like, and must read a plan to find out. HashiCorp's own guidance warns that multi-level block structures produced by nested dynamic blocks are hard to read and maintain. If you find yourself at three levels, the honest options are to restructure the input data so one level suffices, or to write the blocks out literally.