What's the difference between a unit and a stack?
Unit
A unit is a single instance of infrastructure that Terragrunt manages: one VPC, one database, one cluster. A directory containing a terragrunt.hcl file is a unit, and each unit gets its own state file. Units are the target of a single run, so terragrunt apply inside a unit directory applies exactly that unit.
Stack
A stack is a collection of units managed together, such as every unit that makes up one environment or one region. Units in a stack can depend on each other, and Terragrunt orders them using the DAG built from their dependency blocks. A unit can also depend on a whole stack and read the outputs of every unit in it.
Stacks come in two forms:
- Implicit stacks are just a directory tree of units. Nothing declares the stack; it is the set of units Terragrunt discovers under the directory you run from.
- Explicit stacks are declared in a
terragrunt.stack.hclfile, which generates units into a.terragrunt-stackdirectory from sources you point at. This lets you define a pattern once and instantiate it repeatedly with differentvalues.
A single directory cannot be both. Putting a terragrunt.hcl and a terragrunt.stack.hcl side by side in the same directory is an error.
Which commands apply to which
| Command | Operates on |
|---|---|
terragrunt plan, terragrunt apply |
The unit in the current directory |
terragrunt run --all <cmd> |
Every unit discovered under the working directory |
terragrunt stack generate |
The terragrunt.stack.hcl in the current directory |
terragrunt stack run <cmd> |
The units generated by that terragrunt.stack.hcl |
terragrunt stack output |
Outputs of the units in the generated stack |
Both run --all and stack run generate explicit stacks before they run, so you do not need a separate stack generate step. Pass --no-stack-generate to skip it.