Gruntwork Release Notes

🎉 v1.2.0 Release Candidate

This is the second release candidate for Terragrunt v1.2.

It completes the same eleven experiments as v1.2.0-rc1, and adds bug fixes found since then, most of them in the CAS, the catalog, the Provider Cache Server, and exclude blocks.

Future release candidates for v1.2.0 will include bug fixes related to these experiments or other urgent bug fixes as necessary, and documentation improvements.

Please try out this release candidate in lower environments and share your feedback in the associated GitHub discussion.

🛠️ Breaking Changes

base64gzip() uses the current Go encoder

Go 1.27 changed the compressed output of its gzip encoder. Terragrunt v1.1.5 kept base64gzip() on the older output and warned once per run that this was legacy behavior. base64gzip() now returns what the Go 1.27 encoder produces. …

🎉 v1.2.0 Release Candidate

This is the first release candidate for Terragrunt v1.2.

This release completes the following experiments:

• block-iteration
• oci
• bounded-discovery
• catalog-format
• mutable-generate
• optional-dependency-outputs
• optional-hooks
• azure-backend
• version-attribute
• profiling
• dependency-fetch-output-from-state

Future release candidates for v1.2.0 will include bug fixes related to these experiments or other urgent bug fixes as necessary, and documentation improvements.

Please try out this release candidate in lower environments and share your feedback in the Associated GitHub discussion.

🛠️ Breaking Changes

base64gzip() uses the Go 1.27 encoder

Go 1.27 changed the compressed output of its gzip encoder. Terragrunt v1.1.5 kept base64gzip() on the older output and warned once per run that this was legacy behavior. base64gzip() now returns what the Go 1.27 encoder produces. …

Terratest v2.0.0 is the first stable release of v2. All 16 modules are tagged at v2.0.0 in lockstep, and each one installs on its own.

TL;DR: Terratest is now 16 Go modules under /v2 import paths, so a test pulls in only the SDKs of the modules it imports. Most of the upgrade from v1 is rewriting imports, and the compiler finds every other change except two Kubernetes behavior changes, listed below. v1 gets security fixes only, for 12 months after this release.

Upgrading from v1

The v2 migration guide walks through the whole move. What changes for a v1 user:

• Import paths: every module moves to github.com/gruntwork-io/terratest/modules/<name>/v2. The rewriting imports page has the sed commands, and the cases a blind find and replace gets wrong.
• Utility packages: random, files, logger, shell, retry and testing now live in core/v2.
• Package names: http-helper, dns-helper and test-structure become httphelper, dnshelper and teststructure, in the import path and in the identifier.
• Deprecated helpers removed: code still calling terraform.Apply calls terraform.ApplyContext(t, ctx, ...) instead, which is the replacement the v1 deprecation warnings already named. …

🐛 Bug Fixes

Git filters find nested units on Windows again

On Windows, find, list and browse returned nothing for a Git-based filter such as --filter '[main...HEAD]' when the diff changed only unit configurations in nested directories, like nested\path\terragrunt.hcl.

The worktree optimization in v1.1.5 checks out only the directories of changed units for these commands. On Windows, it spelled those directories with \ separators and looked them up in Git's file listing, which uses /. None matched, so it checked out nothing. Terragrunt now uses / separators for those directories on every platform.

✨ New Features

duplicate-dependency-labels also catches a shared config_path

Two dependency blocks with different labels can point at the same config_path. Both parse, so the same unit is declared twice, and the two blocks drift apart as soon as one gains a mock_outputs or skip_outputs the other lacks:

dependency "vpc" {
  config_path = "../vpc"
}

dependency "network" {
  config_path = "../vpc"
}

Terragrunt now warns when it finds this, alongside the existing warning for two blocks sharing a label. With the duplicate-dependency-labels strict control enabled, the warning becomes an error naming both addresses and the path they share:

/path/to/terragrunt.hcl: dependencies vpc and network both point at ../vpc; declare that dependency once and reference it under one name

🏎️ Performance Improvements

Fewer remote probes for sources shared across units

run --all asked the remote what a source resolved to once per unit, so a hundred units sharing one module made a hundred requests. Each of them then read the same commit out of the store for itself.

Units that resolve the same source at the same time now share one probe, and units that need the same Git commit share the work of reading it into the CAS. …

✨ New Features

duplicate-dependency-labels strict control

Declaring two dependency blocks with the same label in one terragrunt.hcl configuration file parsed without error, and then quietly resolved every reference to that label to whichever block came last. The blocks before it were silently overridden:

dependency "vpc" {
  config_path = "../vpc-us-east-1"
}

dependency "vpc" {
  config_path = "../vpc-us-west-2"
}

inputs = {
  # Reads ../vpc-us-west-2.
  vpc_id = dependency.vpc.outputs.vpc_id
}

Terragrunt now warns when it finds this. With the new duplicate-dependency-labels strict control enabled, the warning becomes an error naming the address the blocks share:

terragrunt run plan --strict-control duplicate-dependency-labels

/path/to/terragrunt.hcl: dependency vpc is declared more than once; every dependency needs an address of its own

Give each block a label of its own. A configuration that was relying on the shadowing to pick the last block should keep only that block.

scaffold asks for values interactively …

🐛 Bug Fixes

Fixed Unsupported attribute errors for values.* inputs that autoinclude overrides

A unit input referencing a values.* key that the unit's values file doesn't define no longer fails with Unsupported attribute when an autoinclude block supplies that input. The autoinclude value is applied as intended.

# stacks/terragrunt.stack.hcl
unit "subnet" {
  source = "../units/subnet"
  path   = "subnet"

  autoinclude {
    dependency "vpc" {
      config_path  = unit.vpc.path
      mock_outputs = { vpc_id = "mock" }
    }

    inputs = {
      vpc_id = dependency.vpc.outputs.vpc_id
    }
  }

  values = {
    cidr_block = "10.0.0.0/24"
  }
}

# units/subnet/terragrunt.hcl
inputs = {
  vpc_id     = values.vpc_id      # supplied by autoinclude, not the values file
  cidr_block = values.cidr_block  # still resolves from values file
}

Fixed overwrite_terragrunt and remove_terragrunt on files with no trailing newline

generate blocks using if_exists = "overwrite_terragrunt" or if_disabled = "remove_terragrunt" failed to properly handle existing files when the file at the target path had no newline after its first line, empty files included.

Terragrunt now properly handles files like this, so a file carrying the Terragrunt signature is overwritten or removed as configured, and a file without it produces the usual error naming the path Terragrunt would not touch. …

Terratest v2 lockstep release. All 16 submodules are tagged at v2.0.0-beta.2.

Breaking changes

Eight functions moved to the module that owns the type they operate on, so teststructure no longer pulls in aws, k8s, packer and ssh (#1877). Signatures and on-disk filenames are unchanged, so every call site is a compile error and go build ./... finds all of them.

beta.1	beta.2
teststructure.{Save,Load}Ec2KeyPair	aws.{Save,Load}Ec2KeyPair
teststructure.{Save,Load}KubectlOptions	k8s.{Save,Load}KubectlOptions
teststructure.{Save,Load}PackerOptions	packer.{Save,Load}PackerOptions
teststructure.{Save,Load}SSHKeyPair	ssh.{Save,Load}SSHKeyPair

Nothing else moved. RunTestStage, the Terraform helpers, SaveString/LoadString and the generic SaveTestData/LoadTestData all stay put.

Smaller dependency graph

This closes #1875, which reported that the v2 split was undercut by teststructure requiring seven modules and k8s requiring aws for a single call.

module	beta.1	beta.2
teststructure	301	104
k8s	259	160
helm	316	219

go.sum lines. k8s and helm no longer carry any aws-sdk-go-v2 entries; importing teststructure for RunTestStage no longer pulls in the AWS SDK or client-go.

Behavior changes …

✨ New Features

Scaffold straight from the catalog README view with ctrl+d

In the terragrunt catalog TUI, pressing ctrl+d while reading a component's README now scaffolds it immediately, skipping the interactive form. Module and template inputs are written as # TODO placeholders, and unit/stack copies get a fully placeholder terragrunt.values.hcl. The hint bar at the bottom of the README view advertises the new key.

🏎️ Performance Improvements

Fewer filesystem checks when resolving find_in_parent_folders()

<img width="2320" height="1780" alt="626834110-d04de8b8-cc1b-4426-ab1f-d1760601dd12" src="https://github.com/user-attachments/assets/1198dc75-21fa-4a55-9534-ec0680a5836f" />

find_in_parent_folders() walks up from a unit toward the filesystem root, checking each directory for the configuration file it was asked to find. Even when the call named a file, as in find_in_parent_folders("root.hcl"), each directory along the way was also checked for the default configuration filenames. Units sharing a parent chain then repeated every check their siblings had already made.

Terragrunt now checks only the filename the call names, and reuses what it already learned about a directory for the rest of the command. Deeply nested estates benefit most, since every level between a unit and its root configuration used to be re-checked once per unit. …

This is the first beta of Terratest v2. It splits the library into 16 independent Go modules under /v2 import paths and completes the v2 API cutdown. This is a prerelease published for soak testing ahead of v2.0.0.

This release covers all 16 v2 modules. It is anchored to the core tag, but every module listed under Install below is tagged at v2.0.0-beta.1 and independently installable. This is not a core-only release.

✨ Highlights

• Modularization into 16 independent modules. Every domain is now its own Go module at github.com/gruntwork-io/terratest/modules/<name>/v2. Consumers fetch and version each module independently and pull only its dependency closure. (addresses #445 and #1492)
• Smaller dependency and CVE surface. A consumer that only uses the AWS helpers drops from a 332-line go.sum to 72, a 78% reduction, with zero Kubernetes, Azure, or GCP SDKs in the build. If you do not import modules/k8s/v2, the Kubernetes client and its CVEs (#1071, #1072, #1391) are simply not present.
• API cutdown. Removed the cmd/ binaries, the collections / environment / git core utilities, version-checker, slack, and every v1 // Deprecated: alias.
• Idiomatic package names. http-helper becomes httphelper, dns-helper becomes dnshelper, test-structure becomes teststructure.
• Minimum Go 1.26.

⚠️ Breaking Changes

/v2 import paths (every module) …

🐛 Bug Fixes

Chained role assumption for the S3 backend

When AWS credentials were supplied through --auth-provider-cmd or environment variables, Terragrunt ignored the assume_role attribute of the remote_state block for its own backend operations, such as bootstrapping the state bucket. In cross-account setups this caused access errors, even though OpenTofu/Terraform itself assumed the role correctly during runs.

Terragrunt now uses the supplied credentials as the source identity and assumes the configured role on top of them. The same applies to roles configured via the iam_role attribute or the --iam-assume-role flag, and to fetching dependency outputs directly from S3 state.

Safer temporary clone directories for terragrunt catalog

Terragrunt now creates a fresh temporary clone directory for each catalog load, rejects symlinked clone roots, and removes catalog clones when the TUI session exits.

Resolve dependency outputs for units that reference a dependency in a hook, extra_arguments, or remote_state block

Resolving a unit's dependency outputs for a downstream unit no longer fails when that unit references its own dependency in:

• a before_hook, after_hook, or error_hook
• an extra_arguments block
• a remote_state block

Previously these raised There is no variable named "dependency" on the downstream unit, and a remote_state reference could crash Terragrunt. …