Stack Dependencies

import Since from '@components/Since.astro'; import Before from '@components/Before.astro'; import { Aside } from '@astrojs/starlight/components';

Support for the autoinclude block in terragrunt.stack.hcl files, enabling dependency relationships and configuration overrides during stack generation.

stack-dependencies - What it does

When enabled, this experiment adds support for the autoinclude block nested inside unit and stack blocks in terragrunt.stack.hcl files. The autoinclude block allows users to define dependency blocks and arbitrary configuration that gets generated into an autoinclude file during stack generation. This file is automatically merged into the unit/stack configuration when parsed.

The generated filename depends on the component kind:

• Unit autoincludes are written as terragrunt.autoinclude.hcl next to the unit's terragrunt.hcl.
• Stack autoincludes are written as terragrunt.autoinclude.stack.hcl next to the nested stack's terragrunt.stack.hcl. The .stack.hcl suffix mirrors terragrunt.stack.hcl so tooling (LSP, read_terragrunt_config(), indexers) can identify the file's purpose from its name alone.

This experiment enables:

• unit.<name>.path and stack.<name>.path variables in terragrunt.stack.hcl for referencing sibling component paths
• stack.<name>.<unit_name>.path for referencing individual units within a nested stack (fine-grained dependency)
• dependency blocks targeting stack directories: aggregated outputs from all units in the stack (dependency.stack_name.outputs.unit_name.output_key)
• Automatic deep merge of terragrunt.autoinclude.hcl into unit configurations (autoinclude wins)
• Stack dependency expansion in the run queue: depending on a stack waits until all its units complete

Unit-to-unit dependencies within a stack

# terragrunt.stack.hcl
unit "vpc" {
  source = "../catalog/units/vpc"
  path   = "vpc"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "vpc" {
      config_path = unit.vpc.path
    }

    inputs = {
      vpc_id = dependency.vpc.outputs.vpc_id
    }
  }
}

Dependencies on units within a nested stack

# terragrunt.stack.hcl
stack "stack_w_outputs" {
  source = "../catalog/stacks/stack-w-outputs"
  path   = "stack-w-outputs"
}

unit "unit_w_inputs" {
  source = "../catalog/units/unit-w-inputs"
  path   = "unit-w-inputs"

  autoinclude {
    dependency "unit_w_outputs" {
      config_path = stack.stack_w_outputs.unit_w_outputs.path

      mock_outputs_allowed_terraform_commands = ["plan"]
      mock_outputs = {
        val = "fake-val"
      }
    }

    inputs = {
      val = dependency.unit_w_outputs.outputs.val
    }
  }
}

Dependencies on entire stacks

# terragrunt.stack.hcl
stack "infra" {
  source = "../catalog/stacks/infra"
  path   = "infra"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "infra" {
      config_path = stack.infra.path
    }

    inputs = {
      vpc_id = dependency.infra.outputs.vpc.vpc_id
    }
  }
}

terragrunt run --all --experiment stack-dependencies -- plan

stack-dependencies - How to provide feedback

Provide your feedback on the Stack Dependencies RFC GitHub Issue.

stack-dependencies - Implementation roadmap

• Phased parser for terragrunt.stack.hcl: parse the file body, evaluate locals and values, apply include merges, then decode unit/stack blocks and resolve autoinclude. This lets unit/stack blocks use local.*, values.*, and Terragrunt functions.
• terragrunt run --all discovery can scan generated nested stack files without evaluating the unit source.
• Unify strict and permissive parser into a single code path
• Add integration tests and test fixtures for end-to-end validation
• Add E2E validation with stack run apply and stack run destroy

• Catalog source preservation across stack copy: nested stack files copied into .terragrunt-stack/<name>/ get a .terragrunt-stack-origin marker file, so bare relative ../../units/... paths resolve against the original catalog, not the copy. Only applies to local stack sources; remote and CAS-fetched stacks are unchanged.
• PartialEval depth guard (maxPartialEvalDepth = 10000) and IsWhollyKnown / IsNull checks on the fast path and traversal/template/conditional/parens branches, preventing crashes on unknown values or pathological nesting.
• Typed errors with Unwrap() across the package (FileParseError, FileDecodeError, IncludeValidationError, LocalEvalError, MalformedDependencyError, AutoIncludeParserStageError) preserving hcl.Diagnostics for source positions.
• Deterministic cycle reports in LocalsCycleError.Names (DFS dep iteration sorted).
• resolveStackFilePath returns (string, bool): callers branch on isStackCandidate instead of a sentinel empty string. Backed by a two-arg fuzz that exercises raw/target independently.
• Same-name stack/unit pair (stack "foo" { unit "foo" { ... } }) addressable via stack.foo.foo.path and end-to-end covered by integration test.
• Removed Unicode from internal/hclparse source files (ASCII-only); intentional Unicode test fixtures remain.
• Community feedback on autoinclude syntax and merge behavior
• Integrate with CAS for generated files
• Validate performance at scale