terragrunt.stack.hcl

Reserves the expansion block, which will iterate a dependency, unit, or stack block over a count or for_each.

block-iteration - What it does

Terragrunt has no way to declare one block and have several components come out of it. Running the same unit in three environments means writing the unit block three times in terragrunt.stack.hcl, and depending on one unit per region means writing one dependency block per region.

This experiment gates an expansion block that will carry count and for_each, along with an enabled attribute on unit and stack blocks:

# terragrunt.stack.hcl
unit "app" {
  expansion {
    for_each = toset(["web", "api"])
  }

  source = "./modules/app"
  path   = "app"
}

The flag is reserved, and enabling it has no behavioral effect yet. An expansion block inside a unit or stack block is ignored during stack generation, one inside a dependency block is rejected by the HCL decoder as an unsupported block type, and the enabled attribute is ignored. The iteration behavior itself is still being built, so nothing here is safe to depend on.

Without the experiment, an expansion block in any of those three block types is an error that names the flag, so a configuration written for the finished feature fails instead of quietly doing nothing:

the unit "app" block in /path/to/terragrunt.stack.hcl uses an expansion block, which requires the 'block-iteration' experiment; enable it with --experiment block-iteration

block-iteration - How to enable it

# Via CLI flag
terragrunt --experiment block-iteration stack generate

# Via environment variable
export TG_EXPERIMENT=block-iteration
terragrunt stack generate

block-iteration - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4504.

block-iteration - Criteria for stabilization

To transition the block-iteration feature to a stable release, the following must be addressed:

• count and for_each expansion implemented for dependency, unit, and stack blocks.
• The enabled attribute implemented for unit and stack blocks.
• Naming rules for expanded components settled, so generated paths and the addresses that reference them stay predictable as an iteration source changes.
• A cap on how many components one block may expand into, so a mistaken expression cannot generate an unusable estate.
• References to an expanded dependency from inputs resolve the way users expect.
• Parity checks against the same configuration written out by hand, covering terragrunt stack generate and the run queue.
• Positive feedback from users replacing repeated blocks with iteration.