terragrunt block-iteration expands dependency, unit, and stack blocks
Introduced 2026-09-14 · score 0.94
HOW TO USE IT
When a stack configuration needs multiple units from one block, enable the `block-iteration` experiment and add an `expansion` block with `for_each` or `count`; give each unit a distinct path and address generated elements by key or index.
unit "aurora" {
expansion {
for_each = toset(["web", "api"])
}
source = "../units/app"
path = "aurora/${each.key}"
values = { role = each.key }
}WHY THIS HELPS
Generate multiple Terragrunt dependencies, units, or stacks from one block in a stack configuration.
REQUIREMENTS AND LIMITATIONS
- Version: v1.1.5
- Availability: The `expansion` blocks and `enabled` attributes on `unit` and `stack` require the `block-iteration` experiment.
- expansion.for_each: Set, map, or object to iterate; each instance exposes `each.key` and `each.value`. Set exactly one of `for_each` and `count`.
- expansion.count: Non-negative whole number of instances; each instance exposes zero-based `count.index`. Set exactly one of `count` and `for_each`.
- unit.path (required): Relative generated path; each expanded unit must have a distinct path.
- unit.enabled: Defaults to true; false skips the unit during stack generation and omits it from `terragrunt stack output`.
- Prerequisite: Enable the `block-iteration` experiment with `--experiment block-iteration` or `TG_EXPERIMENT=block-iteration`; `expansion` and `unit.enabled` are gated by the experiment.
- Adding an expansion changes the block's address; references and `stack output` scripts need updating by hand.
- Shrinking a `for_each` or lowering a `count` removes addresses; Terragrunt has no `moved` equivalent, so leftover state at a removed address has to be destroyed deliberately.
FIRST-PARTY EVIDENCE
- https://github.com/gruntwork-io/terragrunt/releases/tag/v1.1.5
- https://docs.terragrunt.com/reference/hcl/blocks/
Check the installed version and the source before using it. Entry JSON