--- schema_version: 1 route: /t/terragrunt.md tool: "terragrunt" --- # sincecutoff.com /t/terragrunt — Terragrunt - name: Terragrunt - kind: cli - children: none - homepage: Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows. Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json). To stay current, read the changes feed: [`/v1/changes.md?tool=terragrunt`](https://sincecutoff.com/v1/changes.md?tool=terragrunt) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt). ### terragrunt azure-backend assigns Azure blob data role during bootstrap (2026-09-14) - slug: terragrunt-azure-backend-assigns-azure-blob-data-role-during-bootstrap-4b5e0b82acd6 - score: 0.94 How to use it: When bootstrapping an Azure `azurerm` backend with Azure AD authentication, enable the `azure-backend` experiment and set `assign_blob_data_role = true` to grant Storage Blob Data Contributor to Terragrunt’s authenticated identity. Set `principal_id` to grant the role to a different identity. Examples: ``` terragrunt --experiment azure-backend backend bootstrap ``` ``` remote_state { backend = "azurerm" config = { storage_account_name = "" container_name = "" key = "" resource_group_name = "" use_azuread_auth = true assign_blob_data_role = true # Optional: principal_id = "" } } ``` - why_it_matters: Bootstrap an Azure remote state backend with an Azure AD identity that needs access to the state blobs. - before: An identity could bootstrap the backend, then require someone to grant the blob data-plane role manually before it could read state. - sources: , - gotchas: "Version: v1.1.5"; "Availability: Requires the `azure-backend` experiment."; "--experiment azure-backend (required): Enables Terragrunt’s experimental Azure backend bootstrap support."; "backend = \"azurerm\" (required): Selects the Azure Storage backend."; "storage_account_name (required): Names the Azure storage account for state."; "container_name (required): Names the blob container for state."; "key (required): Specifies the state blob key."; "resource_group_name (required): Names the resource group for the storage account."; "use_azuread_auth (required): Enables Azure AD authentication for the backend."; "assign_blob_data_role (required): When `true`, bootstrap assigns Storage Blob Data Contributor on the storage account. Opt-in; assignment creation requires `Microsoft.Authorization/roleAssignments/write`."; "principal_id: Microsoft Entra object ID receiving the role when `assign_blob_data_role` is true; defaults to the caller resolved from the access token."; "Prerequisite: Use the `azure-backend` experiment for Azure backend bootstrap."; "Prerequisite: Role assignment creation requires `Microsoft.Authorization/roleAssignments/write`; the documented roles with this permission are Owner and User Access Administrator, not Contributor."; "Prerequisite: With Azure AD authentication, reading and writing state requires Storage Blob Data Contributor on the storage account."; "The setting is opt-in."; "Creating a role assignment requires `Microsoft.Authorization/roleAssignments/write`, which Contributor does not include."; "Reruns need only read permission on role assignments."; "The authenticated identity is resolved from the access token Terragrunt already holds; it works for identities that cannot read Microsoft Entra." ### terragrunt block-iteration expands dependency, unit, and stack blocks (2026-09-14) - slug: terragrunt-block-iteration-expands-dependency-unit-and-stack-blocks-90536fca80f9 - score: 0.94 How to use it: When a stack configuration needs multiple units from one block, enable the `block-iteration` experiment and add an `expansion` block with `for_each` or `count`; give each unit a distinct path and address generated elements by key or index. Examples: ``` unit "aurora" { expansion { for_each = toset(["web", "api"]) } source = "../units/app" path = "aurora/${each.key}" values = { role = each.key } } ``` - why_it_matters: Generate multiple Terragrunt dependencies, units, or stacks from one block in a stack configuration. - sources: , - gotchas: "Version: v1.1.5"; "Availability: The `expansion` blocks and `enabled` attributes on `unit` and `stack` require the `block-iteration` experiment."; "expansion.for_each: Set, map, or object to iterate; each instance exposes `each.key` and `each.value`. Set exactly one of `for_each` and `count`."; "expansion.count: Non-negative whole number of instances; each instance exposes zero-based `count.index`. Set exactly one of `count` and `for_each`."; "unit.path (required): Relative generated path; each expanded unit must have a distinct path."; "unit.enabled: Defaults to true; false skips the unit during stack generation and omits it from `terragrunt stack output`."; "Prerequisite: Enable the `block-iteration` experiment with `--experiment block-iteration` or `TG_EXPERIMENT=block-iteration`; `expansion` and `unit.enabled` are gated by the experiment."; "Adding an expansion changes the block's address; references and `stack output` scripts need updating by hand."; "Shrinking a `for_each` or lowering a `count` removes addresses; Terragrunt has no `moved` equivalent, so leftover state at a removed address has to be destroyed deliberately." ### terragrunt bounded-discovery constrains filter graph traversal (2026-08-13) - slug: terragrunt-bounded-discovery-constrains-filter-graph-traversal-393ec84e8052 - score: 0.98 How to use it: When dependency-filter traversal in an isolated monorepo could reach sibling environments, enable `bounded-discovery` and constrain the graph search to the intended environment. Use `--discovery-boundary` for the command or an inline `(dir)` operand for one filter expression; the directory must exist. Examples: ``` cd terragrunt run --all plan --experiment bounded-discovery --filter '...{}' --discovery-boundary . ``` ``` cd terragrunt run --all plan --experiment bounded-discovery --filter '(.)...{}' ``` ``` terragrunt find --experiment bounded-discovery --filter '{}...' --discovery-boundary ``` - why_it_matters: When traversing dependency filters in a monorepo with isolated environments, bound discovery to the intended environment so sibling configurations are not read or run. - before: Without bounded discovery, dependent filters searched up to the Git repository root and dependency filters followed declared paths; Terragrunt read and parsed configurations it touched. - sources: , - gotchas: "Version: v1.1.3"; "Availability: Experiment"; "--experiment bounded-discovery (required): Enables the bounded-discovery experiment in v1.1.3."; "--filter (required): Filter expression for the units to traverse; `...{unit}` selects dependents and `{unit}...` selects dependencies."; "--discovery-boundary: Sets the directory boundary for traversal across filter expressions in the command. It must be an existing directory; relative paths resolve against the working directory. Dependent traversal requires the boundary to be the working directory or one of its parents; dependency-only traversal permits any directory, including one below the working directory."; "TG_DISCOVERY_BOUNDARY: Environment-variable alternative to `--discovery-boundary` for setting the run’s directory boundary."; "(dir) inline boundary operand: Bounds one filter expression and overrides the command boundary for that expression; the directory must exist. Parentheses are reserved for this operand, so wrap literal names or paths containing parentheses in braces."; "--all: Runs the command across discovered units."; "Prerequisite: Use Terragrunt v1.1.3 or later with the `bounded-discovery` experiment enabled using `--experiment bounded-discovery`."; "Prerequisite: The boundary must be an existing directory. Relative boundary paths resolve against the working directory."; "Boundary must be an existing directory."; "Relative boundary paths resolve against the working directory."; "Dependent traversal searches upward from the working directory; filters using it require the boundary to be the working directory or one of its parents."; "Dependency traversal follows declared paths from matched units; dependency-only filters accept any directory, including one below the working directory."; "Any configuration resolving outside the boundary, whether dependent or dependency, is not read, parsed, or returned; `find` does not list it and `run --all` does not run it."; "Reserving `(` and `)` for the boundary operand changes how `--filter` reads those characters even when the experiment is disabled; an expression such as `1...(foo | bar)` is now rejected as a malformed boundary. Wrap names or paths containing parentheses in braces to keep them literal."; "Docs conflict: Current official experiment documentation describes behavior after the experiment completed: the experiment flag is no longer needed. It also says the boundary limits discovery traversal rather than filtering results, and that dependencies outside the boundary can still be read and parsed. These statements differ from the v1.1.3 release note; use the release-note behavior for v1.1.3. https://docs.terragrunt.com/reference/experiments/active/" ### terragrunt catalog supports non-interactive JSONL and Markdown output (2026-08-13) - slug: terragrunt-catalog-supports-non-interactive-jsonl-and-markdown-output-72bb8dfa88b2 - score: 0.96 How to use it: When catalog results must be read without a terminal or saved for review, enable the `catalog-format` experiment and run `terragrunt catalog --experiment=catalog-format --format=jsonl` for JSON Lines or `--format=md` for Markdown; use `jq` to project or remove JSONL fields and check Markdown’s closing table and count for completeness. Examples: ``` terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c '{kind, title, component_source}' ``` ``` terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c 'del(.doc)' ``` ``` terragrunt catalog --experiment=catalog-format --format=md > catalog.md ``` - why_it_matters: When inspecting catalog results without a terminal or saving them for review, enable `catalog-format` and select JSON Lines for processing or Markdown for reading. - before: The catalog command used a terminal UI and required a terminal; it could not be read in a non-terminal environment. - sources: , - gotchas: "Version: v1.1.3"; "Availability: Experiment"; "--experiment=catalog-format (required): Enables the experiment gating `--format` in v1.1.3. It can also be enabled with `TG_EXPERIMENT=catalog-format`."; "--format=jsonl (required): Writes one JSON object per catalog entry to standard output."; "--format=md (required): Writes one Markdown document with a section per entry; the final table and discovered count indicate completeness."; "jq projection `{kind, title, component_source}`: Selects those fields from each JSONL entry."; "jq deletion `del(.doc)`: Drops the README body from each JSONL entry; `doc` can contain substantial data."; "Prerequisite: Terragrunt `catalog` command available; `--format` requires the `catalog-format` experiment in v1.1.3."; "Prerequisite: Install `jq` to run the documented JSONL filtering examples."; "`--format=tui` remains the default and leaves the terminal user interface as it was."; "JSONL emits one object per line in discovery order, which interleaves repositories and differs between runs."; "Entries stream as discovered; a reader stopping early ends the JSONL command quietly."; "Every JSONL entry includes the complete component README in the `doc` field."; "Markdown entries stream as discovered; READMEs are fenced, and the closing table and count indicate what was discovered and whether the document was cut short."; "Docs conflict: Current active-experiments documentation describes behavior after the experiment completed in v1.2.0: `--format` is available by default and piping `catalog` defaults to JSONL. That newer behavior does not apply to the v1.1.3 instructions." ### terragrunt run can skip dependency output resolution (2026-08-13) - slug: terragrunt-run-can-skip-dependency-output-resolution-91c0c53a0e8a - score: 0.91 How to use it: When you need to initialize without resolving dependency outputs, set `TG_EXPERIMENT=optional-dependency-outputs` and run `terragrunt run --no-dependency-outputs -- init`. The flag requires the experiment; without it, the command returns an error. Examples: ``` TG_EXPERIMENT=optional-dependency-outputs terragrunt run --no-dependency-outputs -- init ``` - why_it_matters: When running initialization without resolving dependency outputs, enable the experiment and skip output resolution for the run. - before: Use `skip_outputs = true` on individual `dependency` blocks to skip their output resolution. - sources: - gotchas: "Version: v1.1.3"; "Availability: Experiment"; "TG_EXPERIMENT=optional-dependency-outputs (required): Enables the experiment required for `--no-dependency-outputs`."; "--no-dependency-outputs (required): Skips all dependency output resolution globally."; "init (required): Command passed through to run after `--`."; "Using `--no-dependency-outputs` without enabling the experiment returns an error." ### terragrunt azure-backend experiment manages azurerm remote state (2026-07-29) - slug: terragrunt-azure-backend-experiment-manages-azurerm-remote-state-55d6a75f59d0 - score: 0.93 How to use it: When an Azure Storage remote-state configuration uses `azurerm`, enable the `azure-backend` experiment and run `terragrunt --experiment azure-backend run -- plan` to manage backend resources and state blobs. [Release v1.1.2](https://github.com/gruntwork-io/terragrunt/releases/tag/v1.1.2) Examples: ``` terragrunt --experiment azure-backend run -- plan ``` - why_it_matters: When maintaining a Terragrunt configuration that uses Azure Storage remote state, enable Terragrunt management of its backend resources and state blobs. - sources: - gotchas: "Version: v1.1.2"; "Availability: opt-in while the experiment is active"; "--experiment azure-backend (required): Enables the Azure Storage (`azurerm`) remote-state experiment."; "run -- plan (required): Runs the underlying `plan` command through Terragrunt."; "location: Terragrunt-only Azure backend setting; release notes do not document its value semantics."; "storage account SKU options: Terragrunt-only settings; specific option names and semantics are not documented in the release notes."; "skip_* flags: Terragrunt-only flags; specific names and semantics are not documented in the release notes."; "enable_soft_delete: Terragrunt-only Azure backend setting; release notes do not document allowed values or details."; "soft_delete_retention_days: Terragrunt-only Azure backend setting; release notes do not document allowed values or range."; "msi_resource_id: Terragrunt-only setting that also selects the managed identity used for delete and migrate operations."; "Prerequisite: Enable the `azure-backend` experiment for this feature."; "Prerequisite: Use an Azure Storage `azurerm` remote-state backend."; "The `azure-backend` experiment must be enabled."; "State blob migration is within the same storage account." ### terragrunt oci experiment downloads modules from OCI registries (2026-07-29) - slug: terragrunt-oci-experiment-downloads-modules-from-oci-registries-cbbfa977386f - score: 0.95 How to use it: When using Terragrunt v1.1.2 to fetch an OpenTofu module from an OCI registry, enable the `oci` experiment and set `terraform.source` to an `oci://` URL. Pin it with `tag` or `digest`; omitting both selects `latest`. Examples: ``` terraform { source = "oci:////?tag=" } ``` ``` terragrunt --experiment oci run -- init ``` - why_it_matters: When configuring an OpenTofu module from an OCI registry, set its OCI source in the Terragrunt configuration and fetch it with the `oci` experiment enabled. - sources: , - gotchas: "Version: v1.1.2"; "Availability: experiment"; "`--experiment oci` (required): Enables the OCI experiment; v1.1.2 leaves `oci://` sources unsupported when it is disabled."; "`terraform.source` (required): Accepts an `oci://` source URL."; "`tag`: Pins the artifact to a tag. Use `tag` or `digest`; the release note does not say they may be combined."; "`digest`: Pins the artifact to a digest. Use `tag` or `digest`; the release note does not say they may be combined."; "`//subdir` selector: Selects a subdirectory within the artifact."; "`TG_TMP_OCI_*`: Interim environment-variable family for static OCI credentials; the release note does not document individual variable names or values."; "`TG_TMP_OCI_REGISTRY`: Limits static credentials to one registry; without it, configured credentials may be offered to any registry contacted by the process."; "Prerequisite: Use Terragrunt v1.1.2 or later for the described change; enable the `oci` experiment for the source to work."; "Prerequisite: For authentication, v1.1.2 supports static credentials through interim environment variables and read-only discovery of Docker and containers auth files. Credential helpers are not invoked; a registry needing per-run token minting requires an externally obtained login in an ambient file."; "When the experiment is disabled, `oci://` sources remain unsupported."; "Static credentials can be limited to one registry with `TG_TMP_OCI_REGISTRY`; without it, configured credentials may be offered to any registry the process contacts."; "Credential helpers are not invoked yet; registries that need per-run token minting only work while an externally obtained login is present in an ambient file."; "Artifacts follow the publishing contract OpenTofu 1.10 consumes natively."; "Docs conflict: Current active-experiment docs describe later behavior: OCI sources work by default, and configured credential helpers may be invoked. Those statements differ from v1.1.2; the release-specific behavior above follows the v1.1.2 release note." ### terragrunt `terraform.version` resolves `tfr://` modules from a constraint (2026-07-14) - slug: terragrunt-terraform-version-resolves-tfr-modules-from-a-constraint-f3a065c959c3 - score: 0.93 How to use it: For a `tfr://` registry module in Terragrunt v1.1.1, enable the `version-attribute` experiment and set `version` to a constraint; Terragrunt resolves the highest published match before downloading. Do not also set `?version=` on that source. Examples: ``` terraform { source = "tfr://registry.opentofu.org/terraform-aws-modules/vpc/aws" version = "~> 3.3" } ``` ``` terragrunt --experiment version-attribute run -- init ``` - why_it_matters: Pin a registry module in a Terragrunt configuration using a version constraint. - sources: , - gotchas: "Version: v1.1.1"; "Availability: Experimental; gated by the `version-attribute` experiment."; "--experiment version-attribute (required): Enables the `version` attribute experiment in v1.1.1."; "terraform.source (required): The module source; the `version` attribute applies only to `tfr://` sources."; "terraform.version (required): A version constraint for resolving a `tfr://` module. Do not combine it with inline `?version=` on the same source; the docs say this combination is an error."; "Prerequisite: Use Terragrunt v1.1.1 or later; in v1.1.1 the `version-attribute` experiment must be enabled with `--experiment version-attribute` or `TG_EXPERIMENT=version-attribute`."; "The `version` attribute applies to `tfr://` sources only."; "It cannot be combined with an inline `?version=` on the same source."; "Docs conflict: The currently published docs describe later behavior: they say the experiment is no longer needed by default and is scheduled to complete in v1.2.0. The v1.1.1 release note says the flag is required, so use the release-note behavior for v1.1.1." ### terragrunt CAS deduplicates sources and controls generated and cached content (2026-07-01) - slug: terragrunt-cas-deduplicates-sources-and-controls-generated-and-cached-content-b102e36ebf82 - score: 0.92 How to use it: When generating stacks from a catalog with relative source paths, set `update_source_with_cas = true` on the relevant `unit`, `stack`, or `terraform` block; `terragrunt stack generate` rewrites the path to a CAS reference. To edit fetched CAS content in `.terragrunt-cache`, set `mutable = true` on the applicable block; otherwise CAS materializes content read-only. Examples: ``` terragrunt run --all --no-cas -- plan ``` ``` unit "" {\n source = ""\n path = ""\n update_source_with_cas = true\n}\n\nterragrunt stack generate ``` ``` terraform {\n source = ""\n mutable = true\n} ``` - why_it_matters: Generate portable stacks from relative sources or make cached source files editable while reusing downloaded content across configurations. - before: Before Terragrunt 1.1, catalog units used remote Git URLs with a `?ref=` even for modules in the same repository; plain relative paths did not resolve from generated locations. - sources: , , , - gotchas: "Version: v1.1.0"; "--no-cas: Disables CAS for the run; incompatible with `update_source_with_cas = true`."; "TG_NO_CAS: Set to `true` to opt out of CAS for a run, as stated in the v1.1.0 release note."; "update_source_with_cas: On a `unit`, `stack`, or `terraform` block, rewrites a relative literal source to a CAS reference during stack generation; requires CAS enabled."; "mutable: On a `terraform` block, copies CAS-fetched content into an editable working tree. Defaults to `false`; takes effect only for CAS-fetched sources."; "source (required): The source to fetch. For `update_source_with_cas`, it must be a relative literal string; interpolation, function calls, and references cause stack generation to fail."; "Prerequisite: The card’s relative-source stack-generation task requires Terragrunt 1.1 or newer."; "`update_source_with_cas` applies to relative sources on a `unit`, `stack`, or `terraform` block."; "`mutable = true` uses extra I/O and disk space; default CAS hard links are read-only." ### terragrunt catalog discovers and scaffolds catalog components in a TUI (2026-07-01) - slug: terragrunt-catalog-discovers-and-scaffolds-catalog-components-in-a-tui-54568cc48ac5 - score: 0.93 How to use it: When you want to browse catalog components and scaffold one into a repository, run `terragrunt catalog`, select the component, and press `s` to open the interactive form. The form collects values and scaffolds the component into the working directory. Examples: ``` terragrunt catalog ``` ``` # In the catalog TUI: select a component, then press s ``` - why_it_matters: Browse catalog components and scaffold a selected component into a repository. - before: The redesigned catalog was previously gated behind the `catalog-redesign` experiment; the release note says the redesign is now the default. - sources: , , - gotchas: "Version: v1.1.0"; "s: Opens the scaffolding form for the selected component in the catalog TUI."; "Scaffolding is interactive."; "Docs conflict: The current catalog feature page says to press uppercase `S` on a selected module, while the v1.1.0 release note specifies lowercase `s` for a component. Follow the release note's lowercase key." ### terragrunt run can skip auth-provider commands during discovery (2026-07-01) - slug: terragrunt-run-can-skip-auth-provider-commands-during-discovery-a6c6c1c4df5e - score: 0.91 How to use it: When configuration parsing resolves without credentials, run the change-based selection with `--no-discovery-auth-provider-cmd` to skip auth-provider invocations during discovery; auth still runs for executing units. Do not enable it if discovery parsing needs credentials, and `--experiment opt-out-auth` is not required in v1.1.0. Examples: ``` terragrunt run --all --no-discovery-auth-provider-cmd --queue-include-units-reading=./changed-file.txt -- plan ``` - why_it_matters: Run a change-based unit selection when parsing configuration does not need credentials. - before: Terragrunt invoked `--auth-provider-cmd` once for every discovered unit by default. The flag was previously gated behind the `opt-out-auth` experiment. - sources: , - gotchas: "Version: v1.1.0"; "--all (required): Run the command against all discovered units, subject to selection options."; "--no-discovery-auth-provider-cmd: Skip `--auth-provider-cmd` invocations during discovery; `TG_NO_DISCOVERY_AUTH_PROVIDER_CMD` is the corresponding environment variable."; "--queue-include-units-reading (required): Limit `run --all` to units that read the specified file via an HCL function or include. Takes a string; `TG_QUEUE_INCLUDE_UNITS_READING` is the corresponding environment variable."; "-- (required): Separates Terragrunt arguments from the underlying command and its arguments; `plan` is the command passed through here."; "Prerequisite: Use the discovery skip only when parsing resolves without credentials; credential-dependent parsing, such as via `get_aws_account_id()`, can fail when enabled."; "Use only when parsing resolves without credentials; configuration that depends on values from `--auth-provider-cmd` during discovery will fail to parse when enabled." ### terragrunt stack dependencies and autoinclude are enabled by default (2026-07-01) - slug: terragrunt-stack-dependencies-and-autoinclude-are-enabled-by-default-da8a525d02bc - score: 0.96 How to use it: When a stack’s units need dependencies or shared parent-folder configuration, declare unit dependencies in `autoinclude` using generated component paths, and add an `include` block to `terragrunt.stack.hcl`. In Terragrunt v1.1.0, these features are enabled by default; no experiment flag is required. Examples: ``` unit "vpc" { source = "/units/vpc" path = "vpc" } unit "app" { source = "/units/app" path = "app" autoinclude { dependency "vpc" { config_path = unit.vpc.path } inputs = { vpc_id = dependency.vpc.outputs.vpc_id } } } ``` ``` include "shared" { path = "../shared.stack.hcl" } unit "app" { source = "/units/app" path = "app" } ``` - why_it_matters: Wire units in a generated stack to their dependencies and add shared configuration to stack definitions. - before: Before stack dependencies, users defined dependency blocks in catalog units and passed dependency paths through `values`. - sources: , - gotchas: "Version: v1.1.0"; "unit..source (required): Source for the unit configuration."; "unit..path (required): Relative generated path for the unit; exposed as `unit..path` to sibling component references."; "autoinclude: Unlabeled block inside a unit or stack; its body is injected into that generated component’s configuration. It takes no arguments. For unit dependencies, declare `dependency` and `inputs` here."; "dependency \"\".config_path (required): Path to the dependency unit or stack. It can reference a sibling’s generated path, such as `unit.vpc.path` or `stack.network.path`."; "inputs: Map of inputs; the example reads a dependency output with `dependency.vpc.outputs.vpc_id`."; "include \"