v1.2.1
🏎️ Performance Improvements
Section titled 🏎️ Performance ImprovementsFaster parsing of shared configuration
Section titled Faster parsing of shared configurationRepositories where every unit includes a root.hcl that loads shared files with read_terragrunt_config now parse much faster.
- Each unit used to parse those shared files itself, so a
common.hclthat runsyamldecode(file(...))on a large YAML file decoded it once per unit. Terragrunt now parses each file once and gives every unit the same result, and parses it again only when the file, or a file it reads, changes during the command.run --allparses it a second time when the run starts, after discovering units. A file whose result can differ between units, like one that callsget_original_terragrunt_dir()or hasdependencyblocks, is still parsed per unit. The function reference lists every case. - Since v1.1.2, discovery parsed every included configuration twice, once for its feature flag defaults and once to merge it. It parses each include once again, and skips includes with
merge_strategy = "no_merge"that it would only have thrown away. - Locals and inputs went through a JSON encoding round trip on their way into Terragrunt. Terragrunt now converts them directly.
In benchmarks on an Apple M3 Max, discovering units and their dependencies in a generated repository whose units read a 48 KB YAML file through read_terragrunt_config:
| units | before | after |
|---|---|---|
| 100 | 819ms | 59ms |
| 500 | 3.60s | 201ms |
| 1,000 | 7.01s | 379ms |
| 5,000 | 34.2s | 1.88s |
Memory allocated during discovery dropped by about 95%.
Faster discovery with path filters
Section titled Faster discovery with path filtersTerragrunt now analyzes --filter expressions before discovery starts and uses them to narrow the filesystem walk it does during discovery. Filters that name specific paths let Terragrunt skip most of the walk, or walk only the directories those paths can match.
On a repository of 10,000 units, discovery with a filter like --filter './doublestar/glob/**', matching 1,250 of those units, took 27 ms instead of 224 ms. A filter like --filter './path/to/specific/unit', which names a single unit, took under 1 ms instead of 215 ms. Discovery selects the same units as before. It still walks the whole working directory when there is no filter, when every filter is negated, or when any filter can select a unit anywhere, such as name=vpc or ...vpc.
Units that share a run_cmd result run the command once
Section titled Units that share a run_cmd result run the command onceUnits share a run_cmd result when the call uses --terragrunt-global-cache, or when it is in a file they read with read_terragrunt_config. Discovery parses units concurrently, so several of them could start the command before any had cached its result, and run --all could run a shared command once per unit.
Units now wait for the first run and reuse its result. If that run fails, the next unit runs the command itself.
🔒 Strict Controls Added
Section titled 🔒 Strict Controls Addeddependency-config-path-file strict control
Section titled dependency-config-path-file strict controlA dependency block could set config_path to a configuration file instead of the directory of a unit or stack:
dependency "db" { config_path = "../db/terragrunt.hcl"}This was never documented, and Terragrunt supported it inconsistently. Existing support will be retained for v1.x for backwards compatibility, to obey the Terragrunt 1.0 guarantees.
Setting config_path to a file is now deprecated. Terragrunt warns when it finds one, then names each block once:
WARN Setting the `config_path` of a `dependency` block to a file is deprecated and will be removed in a future version of Terragrunt. Set it to the directory of the unit or stack instead.WARN /path/to/terragrunt.hcl: dependency db sets config_path to the file ../db/terragrunt.hcl; set it to the directory of the unit or stackWith the new dependency-config-path-file strict control enabled, each of those blocks is an error instead:
terragrunt run plan --strict-control dependency-config-path-file/path/to/terragrunt.hcl: dependency db sets config_path to the file ../db/terragrunt.hcl; set it to the directory of the unit or stackSet config_path to the directory of the configuration, e.g. ../db. The dependency-config-path-file control is also part of the deprecated-configs group.
🧪 Experiments Updated
Section titled 🧪 Experiments Updatediac-engine — Terragrunt and engines authenticate each other with mutual TLS
Section titled iac-engine — Terragrunt and engines authenticate each other with mutual TLSTerragrunt now starts each engine with a one-time client certificate in PLUGIN_CLIENT_CERT, and the engine replies with a one-time certificate of its own. The connection is encrypted, and each side accepts only the other’s certificate. Engines built on the hashicorp/go-plugin server, including terragrunt-engine-opentofu, need no changes. An engine that implements the handshake itself must support this, or its runs fail with:
rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: tls: first record does not look like a TLS handshake"📖 Documentation Updates
Section titled 📖 Documentation UpdatesAzure and GCP examples across the docs
Section titled Azure and GCP examples across the docsThe Overview now has Azure and GCP examples for every step. The Azure examples create a resource group and a virtual network in eastus and westus2, with state in an azurerm backend. The GCP examples create a VPC network and a Cloud Router in us-central1 and us-east1, with state in a gcs backend.
The code for each step is in test/fixtures/docs/02-overview-azure and test/fixtures/docs/02-overview-gcp. Integration tests apply and destroy each step in both directories.
These pages also have Azure and GCP examples now:
- Units shows an
env.hclthat generates the provider for every unit in an environment. - Includes shows a
root.hclthat configures the backend and generates the provider. - Importing shows how to import resources by resource ID.
backend bootstrap,backend migrate, andbackend deleteshow what each command creates, moves, or deletes for anazurermorgcsbackend.- In Patterns, the “Keep your backend configuration DRY” pattern sets an
azurermorgcsbackend once inroot.hcl.
Authentication now has a page for each cloud provider. The Azure page covers signing in with the Azure CLI, a service principal, OIDC, or a managed identity. The GCP page covers gcloud, a service account key, Workload Identity Federation, and an attached service account. Each lists the roles its state backend needs. The AWS content moved to the AWS page, and links to its old headings redirect there.
State Backend also has a page for each backend now: S3, GCS, and Azure Storage. Links to the old backend headings redirect to the new pages. The GCS page now covers what the Azure section already did: the order Terragrunt resolves credentials in, the settings Terragrunt reads without passing them to OpenTofu/Terraform, and the backend’s known limitations.
Pick a cloud provider in any example tab, and every tab on the page switches with it. Other pages open on the same provider when they have a tab for it, and show AWS when they don’t.
⚙️ Process Updates
Section titled ⚙️ Process UpdatesTerragrunt runs git, hg, and smbclient source downloads itself
Section titled Terragrunt runs git, hg, and smbclient source downloads itselfTerragrunt downloaded git::, hg::, and smb:// sources through the getters built into the go-getter library, which started git, hg, and smbclient on their own. Terragrunt now implements these getters itself and starts those programs the same way it runs every other command.
Downloads should behave as they did before. If you find any functional difference, open an issue.
Because the downloads now go through Terragrunt’s own command handling, Terragrunt’s tests can cover them without a real git, hg, or smbclient install or a remote server, which makes regressions in source downloads easier to catch.
Go bumped to v1.27.3 for a security fix
Section titled Go bumped to v1.27.3 for a security fixThe version of Golang used to compile the Terragrunt binary has been updated from v1.27.2 to v1.27.3.
Go v1.27.3 is a security release. It fixes CVE-2026-111943 in crypto/x509: certificate verification now rejects chains that contain a small set of untrusted intermediate certificates. Terragrunt uses this verification for every HTTPS connection it makes, including source downloads, provider registry lookups, and remote state backends. We recommend upgrading.
🐛 Bug Fixes
Section titled 🐛 Bug FixesReading a unit’s outputs no longer collides with that unit’s own run
Section titled Reading a unit’s outputs no longer collides with that unit’s own runIn run --all, a unit could run at the same time as another unit reading its outputs, e.g. with --queue-ignore-dag-order, or when a Git filter plans the destroy of a removed unit while its dependents plan. Both ran OpenTofu/Terraform in the unit’s .terragrunt-cache directory, so one could reinstall providers while the other used them, and the run failed with errors such as:
Error: Required plugins are not installed - registry.opentofu.org/hashicorp/null: the cached package for registry.opentofu.org/hashicorp/null 3.2.4 (in .terraform/providers) does not match any of the checksums recorded in the dependency lock fileTerragrunt now waits for a unit’s run to finish before reading its outputs, and waits for a read in progress before running the unit.
-detailed-exitcode no longer hides failures without an exit code
Section titled -detailed-exitcode no longer hides failures without an exit codeWith -detailed-exitcode, e.g. terragrunt run --all -- plan -detailed-exitcode, a failure that came with no exit code from OpenTofu/Terraform, such as the binary failing to start, was recorded as exit code 0. Terragrunt dropped the error and reported the unit as successful.
Terragrunt now records exit code 1 for these failures and returns the error.
exclude blocks that reference dependency outputs fail with a clear error
Section titled exclude blocks that reference dependency outputs fail with a clear errorAn exclude block whose attributes referenced a dependency output, such as if = dependency.vpc.outputs.skip, never worked with run --all. Terragrunt evaluates the block while it builds the run queue, before any dependency has run, so it ignored the block with a warning and ran the unit anyway. Single unit runs read the output, so the same config behaved differently depending on the command.
Terragrunt now rejects the config on every command:
exclude block in /live/app/terragrunt.hcl cannot reference dependency outputs; exclude blocks are evaluated before dependencies runBase the exclusion on a feature flag or a local instead.
hcl validate errors point at the code that caused them
Section titled hcl validate errors point at the code that caused themterragrunt hcl validate printed each error in a box, with the absolute path of the file and the whole source line:
╷│ Error: Unsupported argument││ on /path/to/live/app/terragrunt.hcl line 1:│ 1: foo = 1││ An argument named "foo" is not expected here.╵It now prints the path relative to the working directory, with the line and column, and underlines the part of the line the error is about:
error: Unsupported argument --> app/terragrunt.hcl:1:1 |1 | foo = 1 | ^^^ An argument named "foo" is not expected here.A dependency block whose config_path names a directory that does not exist is reported the same way, pointing at the config_path:
error: Missing dependency --> app/terragrunt.hcl:2:17 |2 | config_path = "../nonexistent" | ^^^^^^^^^^^^^^^^ This directory does not exist.Scripts that read hcl validate output should use --json, whose fields have not changed.
--out-dir keeps a plan for each Git reference that selects a unit
Section titled --out-dir keeps a plan for each Git reference that selects a unitrun --all with --out-dir or --json-out-dir mirrors each unit under the output directory. Two Git filters that selected the same unit at different references, e.g. --filter '[HEAD~2...HEAD~1]' --filter '[HEAD~1...HEAD]', mirrored both to the same path. Each run overwrote the other’s plan file, so the plan saved for one reference held the other’s changes.
A unit that a Git filter selects at a reference now goes under a directory named for the reference, with @ in front and characters other than letters, digits, -, and _ replaced by _:
<out-dir>/@HEAD_1/env/app/tfplan.tfplan<out-dir>/@HEAD/env/app/tfplan.tfplanA unit found by walking the working directory keeps its path, and planning and applying with the same --filter still find the same files.
read_terragrunt_config no longer leaks the reading unit’s locals into the file it reads
Section titled read_terragrunt_config no longer leaks the reading unit’s locals into the file it readsA file read with read_terragrunt_config evaluated its include and feature blocks with the reading unit’s local and feature values still in scope, so a feature block in the file could reference a local the file never defined, and parse or fail depending on which unit read it. The file now evaluates those blocks with only its own values in scope, as it always did for the rest of its contents.
A file that referenced the reader’s values this way fails with:
Unsupported attribute; This object does not have an attribute named "region".Define the value in the file being read, or move it to the unit and reference it there. To build a path from the reading unit’s directory, call get_original_terragrunt_dir() in the file.
run_cmd results are cached per environment and exact arguments
Section titled run_cmd results are cached per environment and exact argumentsA run_cmd call in a file shared via read_terragrunt_config returned the first unit’s output to every unit, even when --auth-provider-cmd gave each unit different credentials. run_cmd("printf", "%s|", "x y") and run_cmd("printf", "%s|", "x", "y") also shared one cached result.
Terragrunt now caches each result per environment and exact arguments, so every unit gets the output its own credentials produce.
use_path_style applies to Terragrunt’s own S3 requests
Section titled use_path_style applies to Terragrunt’s own S3 requestsOpenTofu deprecates the s3 backend’s force_path_style setting in favor of use_path_style, but Terragrunt only read force_path_style. With use_path_style = true in remote_state, OpenTofu used path-style URLs while Terragrunt’s backend bootstrap and dependency output reads did not. Against an S3-compatible object store, bootstrap then failed with errors such as:
operation error S3: HeadBucket, https response error StatusCode: 501, RequestID: , HostID: , api error NotImplemented: Not ImplementedTerragrunt now reads use_path_style as well as force_path_style. See S3-compatible object stores for a working configuration.