Terragrunt Tightens Cache Races, Plan Outputs and Discovery Speed

Terragrunt, the Terraform wrapper that most IaC pipelines either love or tolerate, landed 34 commits on main this week. The headline theme is correctness under concurrency: a unit cache directory race on down runs, plan file collisions across Git references, and faster discovery walks all touch the paths that bite people in large repos. If you run stacks with hundreds of units, this week is worth a read.

The most operator relevant fix of the week is the unit cache directory race. On down (destroy) runs and on flat directory layouts, units could collide while writing or reading their per unit cache directories during concurrent execution. That is exactly the kind of bug that shows up as an intermittent, unreproducible failure on a big stack run and then vanishes on retry.

The fix landed in the cache dir race commit. If you have seen flaky parallel destroy runs that pass when rerun serially, this is a candidate root cause. Worth upgrading for on its own.

A related fix keeps plan files separate per Git reference when using --out-dir. Previously, two units pointing at the same module source via different refs (main and a feature branch, say) could share a plan file path and overwrite each other. The plan per Git reference fix removes that ambiguity for anyone templating modules off branches.

terragrunt has long produced dependency output errors that were either too generic or pointed at the wrong thing. A fix this week makes dependency outputs errors show properly, touching pkg/config/dependency.go which saw four commits in the window. The file is central to dependency resolution, so expect more churn here.

On the same axis, hcl validate got better diagnostics. The improvement to hcl validate error messages went into internal/cli/commands/hcl/validate/dependency_diagnostics.go and validate.go, files that saw two commits each. For CI pipelines that gate plans on validation, better diagnostics mean less time digging through logs to find which dependency chain broke.

One more discovery fix: combining the symlink experiment with discovery broke things, and it was fixed this week. If you experiment with symlinked unit layouts, retest after picking this up.

Two performance commits landed together:

  • Discovery walk narrowing, commit 1b6ed36e, prunes the directory walk during unit discovery instead of enumerating everything.
  • find --json performance, commit 23e13e1e, speeds the JSON output path of the find command.

Neither commit cites numbers in its subject, so treat this as “faster, unquantified”. The interesting detail is that these ship alongside internal/discovery/benchmark_live_layout_test.go, a live layout benchmark added in the same window. That suggests the discovery performance work is now being measured against real repo shapes rather than synthetic fixtures. Good practice, and watch for the benchmark numbers in future activity.

The tradeoff with walk narrowing is always the same: prune too aggressively and you stop discovering units in unusual layouts. If your repo relies on non standard directory structures, this is the change to test explicitly on your layout.

The one feature commit of the week adds engine auto mTLS: engine auto mTLS in d437ab09. Terragrunt engines are external processes that run Terraform logic, and until now mTLS configuration between the CLI and the engine was manual. Automatic mTLS removes a whole class of misconfigured local engine setups. If you have not adopted engines yet, this is one less setup step between you and trying them.

Less visible but meaningful: Getters are now routed through vexec, the routing commit b8b0b12d. This is mostly internal refactor. It consolidates how external command execution happens, which makes it easier to apply consistent logging, timeouts, and sandboxing to download and fetch operations later. Also in the plumbing bucket, the toolchain bumped to Go v1.27.3 and linters were added with corresponding lint cleanup commits.

For Windows users on older environments: Terragrunt keeps supporting SMB getters, and internal/getter/smb.go saw two commits this week. If you are still pulling modules off an SMB share on a 2016 era file server, note that this code path is actively maintained even as the project modernizes elsewhere.

Docs are a large share of the diff volume this week, 535 files changed overall, much of it from the v1.2.1 documentation cleanup and multi cloud examples. Azure and GCP getting started guides landed, including Azure samples with synced stateful tabs and a GCP guide. The HCL reference for blocks was the most touched file at six commits, indicating the docs caught up with newer HCL features like exclude blocks and functions.

On CI, security scanning learned to suppress findings via a config file, and a noisy transitive CVE in the docs toolchain (CVE-2026-93687 in braces, only reachable through docs/bun.lock) was suppressed in 70130c90. The weekly security scan workflow is the one to copy patterns from if you run similar scans in your own org.

  • The discovery performance work appears to be mid flight. Watch for follow up commits around internal/discovery and the newly added live layout benchmark.
  • Engines with auto mTLS is new. If you run engines in CI, check what certificate lifecycle assumptions the automation makes before adopting it.
  • The symlink experiment interaction with discovery was just fixed. If you use symlinks, keep this combination on your regression checklist until the experiment graduates.

The project lives at gruntwork-io/terragrunt on the main branch.