skip to content

In Terragrunt, how do implicit stacks differ from explicit stacks defined in `terragrunt.stack.hcl`, and when is the generated form worth it?

level: middleimportance: nice to knowfreq 27%

answer

  1. a folder or a blueprint
  2. committed units versus generated units
  3. a hidden output directory
  4. values instead of inputs

basics

~20 s

An implicit Terragrunt stack is a directory tree of hand-written units. An explicit stack is a terragrunt.stack.hcl blueprint that generates its units into .terragrunt-stack. Explicit pays off when the same set of units repeats across environments.

solid answer

~40 s

An implicit stack is just a directory containing units: nothing to write, and `run --all` from that directory treats it as a stack. An explicit stack is a `terragrunt.stack.hcl` file with `unit` and `stack` blocks that point at definitions in a catalog repository; `terragrunt stack generate` writes the units into `.terragrunt-stack`, with `values` in `terragrunt.values.hcl`. Explicit is worth its extra file and generation step when you have several environments with many similar units differing only in values, and you want to version the whole pattern. For a small set of unique units, or when you want every unit readable in git, implicit is simpler. It also has no generation step to debug.

go deeper

for a junior

Recall the two forms: a directory of units is an implicit stack, and a terragrunt.stack.hcl file generating units is an explicit one. Note that this is not HCP Terraform's Stacks feature.

for a middle

Explain unit and stack blocks, where generate writes files, how values reach a unit, and how a dependency between generated units gets declared.

for a senior

Bring up the state-key trap when adopting: generated paths change path_relative_to_include(), and no_dot_terragrunt_stack keeps the old key. Also mention stale generated files and harder debugging.

for a principal

Decide whether a versioned pattern is worth reading generated code for. Explicit stacks suit a platform team publishing a catalog, while teams with few unique units may never earn that indirection back.

## Two meanings of stack In Terragrunt, a **stack** is a collection of related **units** (directories with a `terragrunt.hcl`) that you can manage together. This is Terragrunt's own word and has nothing to do with Terraform Stacks in HCP Terraform. Terragrunt offers two ways of defining one. ## Implicit stacks: the directory tree Any directory containing units already acts as a stack. There is no file to write and nothing to generate: `live/prod/us-east-1/` is a stack because units sit below it, and `terragrunt run --all apply` from there runs them. Stacks nest, so `live/prod` and `live` are stacks too, and the directory you stand in sets the scope. This has been the default for years, and most existing Terragrunt code works this way. Its limits are the ones you would expect: - Each unit has to be created and configured by hand. - A pattern of several units cannot easily be shared between environments. - Similar configuration is either duplicated or factored out with `include`. ## Explicit stacks: a generated blueprint A `terragrunt.stack.hcl` file is a **blueprint** that generates units. It has `unit` blocks for one component and `stack` blocks for a whole reusable pattern: ```hcl # live/prod/us-east-1/terragrunt.stack.hcl unit "vpc" { source = "git::[email protected]:example-org/catalog.git//units/vpc?ref=v1.0.0" path = "vpc" values = { cidr = "10.10.0.0/16" } } unit "app" { source = "git::[email protected]:example-org/catalog.git//units/app?ref=v1.0.0" path = "app" values = { vpc_path = "../vpc" } } ``` Here `source` points at a **unit definition** in a catalog repository, not a Terraform module. The commands are: 1. `terragrunt stack generate` writes each unit under `.terragrunt-stack`, with its `values` in a `terragrunt.values.hcl` beside the unit's `terragrunt.hcl`. 2. `terragrunt stack run apply` generates if needed, then runs across the generated units. 3. `terragrunt stack output` prints one aggregated object of every unit's outputs. 4. `terragrunt stack clean` removes `.terragrunt-stack`, which normally stays out of git. A generated unit reads values as `values.cidr`. ## How they compare | | Implicit stack | Explicit stack | |---|---|---| | Defined by | Directory layout | `terragrunt.stack.hcl` | | What is committed | Every unit's `terragrunt.hcl` | The blueprint; units are generated | | Reuse across environments | `include`, copy and edit | A versioned `stack` block with `values` | | Reading a diff | Direct | One step removed from the generated code | | Extra steps | None | Generation, and stale files to clean | Terragrunt's guidance matches this. Implicit suits a small number of unique units and teams that want maximum transparency. Explicit suits several environments, many similar units that differ only in values, and versioned patterns. Its docs suggest starting implicit and adding explicit stacks as things grow. ## Rules that catch people - **A directory is one or the other.** A unit containing `terragrunt.stack.hcl`, or a stack containing `terragrunt.hcl`, is an error. - **Stale generated files survive.** `stack generate` does not delete files it no longer produces, so use `terragrunt stack clean` or `--source-update` after removing a unit. - **A stack has no `dependency` block of its own.** A unit can depend on a stack, but a stack cannot declare dependencies. Declare them on each unit, either in the catalog through a path in `values` or in the stack file through an `autoinclude` block. - **Generation has a cost.** Deeply nested stacks can be slow because of network and file copying, and a generated file is harder to debug than a hand-written one. - **`include` means less here.** In a stack file it only adds `unit` and `stack` blocks from another file. It does not merge locals or values, and it cannot be nested. Nesting stacks is the way to share a whole pattern. - **`run --all` still works.** Running it above a directory holding a `terragrunt.stack.hcl` generates that stack and includes its units in the queue, so the two forms can live side by side in one repository while you migrate. ## Adopting one without moving state A root file usually builds the state key with `path_relative_to_include()`. Generating a unit under `.terragrunt-stack` changes its path, which changes its key, and Terraform would find an empty state. The migration guide's answer is `no_dot_terragrunt_stack = true` on the block, which generates the unit in the directory of the stack file. Paths and keys stay as they were, so you can check that generated files match the old ones, then remove the hand-written copies.

  • Why does moving units under `.terragrunt-stack` risk an empty state, and how do you avoid it?
    If the root file builds its `key` from `path_relative_to_include()`, a new path means a new key, so Terraform finds no state there. Setting `no_dot_terragrunt_stack = true` generates the unit in the stack file's directory, so its path and key stay unchanged during adoption.
  • How does one generated unit consume another's outputs in an explicit stack?
    Either the catalog unit declares a `dependency` whose `config_path` comes from `values`, such as `values.vpc_path`, or the stack file declares it in an `autoinclude` block on the `unit`, using `unit.vpc.path`. The second keeps the catalog generic, and Terragrunt merges the generated `terragrunt.autoinclude.hcl` into the unit.

  • An implicit stack needs a terragrunt.stack.hcl file at the top of the tree.
  • A directory can hold both terragrunt.hcl and terragrunt.stack.hcl.
  • A terragrunt.stack.hcl file can declare its own dependency block on another stack.
  • Terragrunt stacks are the same feature as Terraform Stacks in HCP Terraform.
  • The generated .terragrunt-stack directory must be committed for the stack to work.
  • Running stack generate removes any file it no longer produces.