generate

Usage

Generate a stack of units based on configurations in a terragrunt.stack.hcl file.

Examples

Generate stacks of units using the configurations in all terragrunt.stack.hcl files found, starting in the current directory.

terragrunt stack generate

Generating a stack

terragrunt.stack.hcl

unit "mother" {
  source = "units/chicken"
  path   = "mother"
}

unit "father" {
  source = "./units/chicken"
  path   = "father"
}

unit "chick_1" {
  source = "./units/chick"
  path   = "chicks/chick-1"
}

unit "chick_2" {
  source = "units/chick"
  path   = "chicks/chick-2"
}

Running the following:

terragrunt stack generate

Generates the following stack:

• terragrunt.stack.hcl
• Directory.terragrunt-stack

  • Directorymother

    • terragrunt.hcl
  • Directoryfather

    • terragrunt.hcl
  • Directorychicks

    • Directorychick-1

      • terragrunt.hcl
    • Directorychick-2

      • terragrunt.hcl

Note

Parallel Execution: Stack generation runs concurrently to improve performance. The number of parallel tasks is determined by the GOMAXPROCS environment variable and can be explicitly controlled using the --parallelism flag:

terragrunt stack generate --parallelism 4

Automatic Discovery: The command automatically discovers all terragrunt.stack.hcl files within the directory structure and generates them in parallel.

Validation of Units and Stacks: During the stack generation, the system will validate that each unit and stack’s target directory contains the appropriate configuration file (terragrunt.hcl for units and terragrunt.stack.hcl for stacks). This ensures the directories are correctly structured before proceeding with the stack generation. To skip this validation, you can use the --no-stack-validate flag:

terragrunt stack generate --no-stack-validate

Caution

Path Restrictions: If an absolute path is provided as an argument, generate will throw an error. Only relative paths within the working directory are supported.

Caution

Recreating the stack directory and cleaning stale files: By default, terragrunt stack generate does not delete files in .terragrunt-stack that are no longer produced by the current terragrunt.stack.hcl. If you removed or changed values or units and still see old files (e.g., a lingering terragrunt.values.hcl), regenerate from a clean state by either refreshing sources or cleaning the directory first:

# Refresh sources and regenerate from a clean copy
terragrunt stack generate --source-update

# Or explicitly remove the generated directory first
terragrunt stack clean && terragrunt stack generate

You can also pass --source-update when running commands via stack run:

terragrunt stack run plan --source-update

Flags

--filter

Filter configurations using a flexible query language

Filter Behavior for Stack Generate

The --filter flag works differently for stack generate compared to other commands. It requires that you explicitly target stacks using the type=stack attribute.

Examples:

# Filter by name
terragrunt stack generate --filter 'name=prod | type=stack'

Attribute-Based Filtering

Match stacks by their configuration attributes:

# Filter by name
terragrunt stack generate --filter 'prod | type=stack'

# Filter by type
terragrunt stack generate --filter 'type=stack'

# Filter by path
terragrunt stack generate --filter './envs/prod/** | type=stack'

Negation

Exclude paths using the ! prefix:

# Exclude by path
terragrunt stack generate --filter '!./prod/** | type=stack'

Union (Multiple Filters)

Specify multiple --filter flags to combine results using OR logic:

# Generate the dev and prod stacks
terragrunt stack generate --filter 'dev | type=stack' --filter 'prod | type=stack'

Type: list(string)

--discovery-boundary

Directory that encloses graph discovery for filters, instead of the git repository root

Experimental

This flag is gated behind the bounded-discovery experiment. Enable it with --experiment=bounded-discovery (or TG_EXPERIMENT=bounded-discovery); otherwise setting --discovery-boundary returns an error. The flag’s behavior may change while the experiment is in progress.

Filter expressions that traverse the dependency graph reach beyond the working directory. Dependents (...{unit}) can live anywhere, so Terragrunt searches from the working directory up to the git repository root; dependencies ({unit}...) are declared by path and can point anywhere.

The --discovery-boundary flag is a single enclosure for that traversal: it replaces the git repository root as the outer limit, and a configuration that traversal reaches outside it is not returned, so find does not list it and run --all does not run it. Configurations inside the boundary are discovered as usual.

The boundary decides which configurations a command acts on, not which ones Terragrunt may read. A unit inside the boundary can declare a dependency outside it, and that dependency is still read and parsed: Terragrunt needs its configuration to fetch the outputs the dependent unit consumes, and it needs the dependency edge to order the units that do run. What the boundary withholds is the unit itself, which is left for a separate run to apply, the same way a dependency outside the working directory is treated today.

This matters in monorepos where environments are isolated from each other. When sibling environments cannot be parsed independently, the default search fails or wastes work reaching into them:

environments/
  staging/
  production/
  test/
  root.hcl

Bounding the traversal to the current environment keeps discovery inside it:

cd environments/staging
terragrunt find --experiment bounded-discovery --filter '...{vpc}' --discovery-boundary .

Usage

# Enclose discovery within the working directory
terragrunt find --filter '...{vpc}' --discovery-boundary .

# Enclose discovery within a parent directory
terragrunt run --all plan --filter '...{vpc}' --discovery-boundary ..

# Equivalent, via environment variable
TG_DISCOVERY_BOUNDARY=. terragrunt find --filter '...{vpc}'

# From the repository root, keep app's dependencies within prod
terragrunt find --filter '{./prod/app}...' --discovery-boundary ./prod

The boundary must be an existing directory. Relative paths are resolved against the working directory.

The boundary applies to what traversal reaches, so a command that names no filter keeps every configuration under the working directory even when the boundary sits below it. Narrow the working directory itself, with --working-dir, to change where discovery starts.

Where the boundary may sit depends on the directions the filters traverse. Dependent traversal searches upward from the working directory, so a boundary that excludes the working directory could never take effect; filters that traverse dependents require the boundary to be the working directory or one of its parents. Dependency traversal follows declared paths outward from the units a filter matched and never consults the working directory, so filters that traverse only dependencies accept any directory, including one below the working directory. That is the same rule the inline (dir) operand follows.

Type: string

Environment Variables:

• TG_DISCOVERY_BOUNDARY

--no-cas

Disable the CAS (Content Addressable Storage) feature.

When this flag is set, Terragrunt skips all CAS operations and clones sources directly.

Generation or runs error when update_source_with_cas = true is set on any unit, stack, or terraform block reachable from the current invocation, since relative sources rewritten by CAS cannot be resolved without it.

Type: bool

Environment Variables:

• TG_NO_CAS

--cas-clone-depth

When using CAS, pass this value to git clone --depth (default 1; -1 clones full history).

This flag has no effect when the CAS is disabled with --no-cas.

Controls the --depth value the CAS (Content Addressable Storage) uses when cloning a Git source. The default of 1 performs a shallow clone of the latest commit. Negative values clone the full history by omitting --depth entirely; zero is rejected because Git requires a positive depth.

When passing a negative value, use the --cas-clone-depth=-1 form so the leading dash isn’t parsed as a flag.

This flag sets the depth for all CAS Git clones. A depth query parameter on a source URL (for example ...vpc.git?depth=1) is stripped before Terragrunt invokes git, and never changes the depth, which always comes from this flag.

Type: integer

Default: 1

Environment Variables:

• TG_CAS_CLONE_DEPTH

--cas-offline

When using CAS, never contact a remote; resolve every source from the local store and fail on anything missing.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-offline returns an error.

Forbids the CAS from contacting any remote. Each source is resolved locally instead: a source pinned to a specific revision that the store already holds is looked up there, and everything else is answered from the most recent probe the probe cache recorded for it, however old that result is. The content is then linked from the store as usual.

A source with no recorded answer, or whose content is not in the store, fails with an error naming it instead of being fetched. Run once without this flag to populate the store, then rerun with it.

Any other CAS failure on a source, such as a store file that cannot be read, also fails the run. Without this flag Terragrunt falls back to the standard downloader, which fetches from the remote.

terragrunt run --all --cas-offline -- plan

Every source the CAS resolves through a cheap probe is covered: Git, HTTP and HTTPS, S3, GCS, OCI, the OpenTofu/Terraform registry, and Mercurial. A source with no cheap probe, such as an SMB share, has nothing recorded and is still fetched. Local paths are copied as usual. The flag has no effect when the CAS is disabled with --no-cas, and it cannot be combined with --cas-refresh.

Type: bool

Environment Variables:

• TG_CAS_OFFLINE

--cas-refresh

When using CAS, ignore recorded probe results and ask every remote again.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-refresh returns an error.

Skips the probe cache for this run, so every source is resolved with a fresh probe. Units that resolve the same source at the same time still share one probe; a unit that starts later asks the remote again. The fresh results are recorded for later runs.

A source pinned to a specific revision, such as a semantic version tag or an S3 object version, is trusted for 24 hours by default, so a tag that has been moved keeps resolving to its previous revision until that window passes. This flag picks up the new one right away.

terragrunt run --all --cas-refresh -- plan

The flag has no effect when the CAS is disabled with --no-cas, and it cannot be combined with --cas-offline.

Type: bool

Environment Variables:

• TG_CAS_REFRESH

--cas-probe-ttl

When using CAS, trust a recorded probe of a source that can change upstream for this long before asking the remote again.

Experimental

This flag is gated behind the offline-cas experiment. Enable it with --experiment=offline-cas or TG_EXPERIMENT=offline-cas; otherwise setting --cas-probe-ttl returns an error.

Sets how long the CAS serves a recorded probe of a source that can change upstream in place of a fresh one. That covers a Git branch or HEAD, a Git tag that is not a semantic version, an HTTP endpoint, a GCS object, an OCI tag, and a Mercurial branch name. The value is a duration such as 30s, 10m, or 1h. Negative values are rejected.

The default of 0 probes these sources on every run, so a push or an upload followed by a run sees the new revision. Raise it when a burst of runs against the same sources should not each pay for a probe, accepting that a change made inside the window is not seen until it passes.

terragrunt run --all --cas-probe-ttl 10m -- plan

A source pinned to a specific revision is trusted for 24 hours regardless of this flag; see Recorded probes for which sources count as pinned. Use --cas-refresh to bypass every recorded result for one run.

Type: string

Default: 0

Environment Variables:

• TG_CAS_PROBE_TTL