Gruntwork Release Notes

🐛 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.

Dependency mock_outputs apply when the state bucket doesn't exist yet

When reading a dependency's outputs directly from remote state (--dependency-fetch-output-from-state), Terragrunt fell back to mock_outputs only when the state object was missing, not when the S3 bucket itself didn't exist. A dependency on an environment that hadn't been bootstrapped yet would fail instead of using its mocks.

A missing bucket is now treated the same as a missing state object, so commands like plan and validate can resolve mocks before the dependency's backend has been created.

Source permissions preserved on hidden directories copied by include_in_copy

With the fast-copy strict control enabled, a hidden directory that Terragrunt copied due to include_in_copy matching something within it took the permissions of the first file generated within it, instead of the permissions it had in the source.

Those directories now keep their source permissions, matching the copy Terragrunt performs with the control disabled.

Applied the positive half of a filter that begins with a negation

When a --filter query began with a negation, Terragrunt treated the whole query as an exclusion. The expressions chained after the negation stopped restricting the selection and only narrowed what got subtracted, so components matching none of them came back in the results. Those expressions are now applied.

$ terragrunt list
bar baz foo
$ terragrunt list --filter '!name=foo | name=bar'
bar baz foo
$ terragrunt list --filter '!name=foo | name=bar'
bar

This follows the left-to-right refinement that | has everywhere else: each expression narrows what the one before it selected. A query is only treated as an exclusion when every one of its expressions is negated, such as '!name=foo' or '!name=foo | !name=bar'.

See Combining Expressions for how negation, intersection and union interact.

Fixed a race condition that left cached provider archives in the working directory

With the provider cache server enabled via --provider-cache, a race let the server start responding to requests before it had finished preparing the directories it caches into. A provider requested in that window had its archive and lock file written relative to the working directory instead of into the cache, leaving zip files behind in your project.

That race condition has been fixed. Providers now always download into the cache directory.

Fixed a race condition between concurrent Terragrunt runs downloading providers

A race condition in the logic used to synchronize provider downloads meant that two Terragrunt runs on the same machine could interfere with each other while caching the same provider. Each run staged its downloads at the same path, so a run that finished first could delete an archive another run was still unpacking, failing that run with failed to open zip archive.

That race condition is now fixed. Two runs can cache the same provider at the same time.

Fixed space-delimited flag values in providers lock

The space-delimited form, providers lock -platform linux_amd64, now reaches OpenTofu and Terraform intact. Previously it was the attached form, -platform=linux_amd64, that worked: given the value as a separate argument, Terragrunt moved it to the end of the command, where it was read as a provider address and the run failed with Invalid provider type "linux_amd64".

-fs-mirror and -net-mirror were moved the same way, and now keep their values too.

With --provider-cache enabled, platforms are also split correctly across the per-platform providers lock runs used to warm the cache.

Fixed scaffold on units and stacks

terragrunt scaffold read every source as an OpenTofu/Terraform module. Given a unit or a stack, which are Terragrunt configurations rather than OpenTofu/Terraform modules, it exited successfully having written an invalid terragrunt.hcl file.

Units and stacks are now scaffolded the way the Catalog TUI scaffolds them: their files are copied into the working directory for you to edit in place, along with a terragrunt.values.hcl listing every values.* reference the configuration makes.

terragrunt scaffold 'github.com/gruntwork-io/terragrunt-scale-catalog//units/aws/oidc/iam-oidc-role'

Copying refuses to overwrite: a file that would land on an existing path stops the command before anything is written. Modules and templates are unaffected and are still scaffolded from their variables.

See Scaffold for what gets copied and how the values file is filled in.

Answered every prompt when input is piped in

A run that asks for confirmation more than once, such as terragrunt backend delete prompting for both the lock table entry and the state object, used to read only the first answer when the answers were piped in rather than typed. The remaining answers were discarded while reading ahead, and the next prompt failed with an end-of-input error. Every prompt in a run now reads from the same input, so piping yes for each one works.

Stack dependencies honor mock_outputs with --dependency-fetch-output-from-state

A dependency block that reads outputs from a stack (its config_path points at a terragrunt.stack.hcl directory) used to fail when a unit in that stack had no state yet, even when the dependency declared mock_outputs. This blocked commands like plan and validate against a stack that hadn't been applied.

Such a dependency now falls back to mock_outputs for the units that have no state yet. In a partially applied stack, applied units resolve to their real outputs while the rest use their mocks.

Mocks for a stack dependency are keyed by unit name, so mock_outputs has to be a map or object. Declaring it as any other type now reports that directly, instead of leaving the units it can't cover out of the stack outputs.

Fixed --config= being ignored by the tflint hook

The built-in tflint hook reads the configuration file out of the arguments you give it, then uses that path for tflint init and for the lint run. It only recognized the space-separated --config spelling, so a hook written as:

before_hook "tflint" {
  commands = ["plan"]
  execute = ["tflint", "--config=custom.tflint.hcl"]
}

was treated as though no configuration file had been named at all. Terragrunt searched the unit directory and its parents for a .tflint.hcl file instead, and either failed with a config-not-found error or ran tflint init against whatever unrelated configuration the search turned up. Terragrunt now recognizes --config , --config=, -c , and -c=.

The hook also builds --var arguments from the unit's inputs and from TF_VAR_ entries in extra_arguments blocks. Those arguments came out in a different order on every run, which made the logged command line, and anything comparing it between runs, needlessly unstable. They are now ordered by variable name.

🧪 Experiments Added

block-iteration experiment reserves the expansion block

The block-iteration experiment has been added as the gate for iterating a dependency, unit, or stack block over a count or for_each, declared through a nested expansion block, along with an enabled attribute on unit and stack blocks.

In this release the flag is reserved only, and enabling it has no behavioral effect. Writing an expansion block without the experiment now reports an error naming the flag, rather than leaving the block to be silently discarded:

the unit "app" block in /path/to/terragrunt.stack.hcl uses an expansion block, which requires the 'block-iteration' experiment; enable it with --experiment block-iteration

Track progress and share feedback in #4504.

bounded-discovery — Added a directory boundary for graph traversal

Filter expressions that traverse the dependency graph reach beyond the working directory: dependents (--filter '...{unit}') by walking up to the Git repository root, dependencies (--filter '{unit}...') by following declared paths. Either way, Terragrunt reads and parses every configuration it touches. In monorepos with isolated environments, that traversal can fail or do wasted work reading sibling environments.

Enable the new bounded-discovery experiment to set a boundary for that traversal. The --discovery-boundary flag (env: TG_DISCOVERY_BOUNDARY) replaces the Git repository root as the enclosure for a whole run:

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

The experiment also unlocks an inline (dir) boundary operand, which bounds a single expression and overrides the flag. It occupies the same slot as a traversal depth, so it bounds discovery by location the way a number bounds it by graph hops:

cd environments/staging
terragrunt run --all plan --experiment bounded-discovery --filter '(.)...{vpc}'

Any configuration that resolves outside the boundary, whether a dependent or a dependency, is not read, parsed, or returned: find does not list it and run --all does not run it. Configurations inside the boundary are discovered as usual.

The boundary must be an existing directory, and relative paths are resolved against the working directory. Dependent traversal searches upward from the working directory, so filters that use it also need the boundary to be the working directory or one of its parents. Dependency traversal follows declared paths from the units a filter matched, so dependency-only filters accept any directory, including one below the working directory:

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

Reserving ( and ) for the boundary operand changes how --filter reads those characters everywhere, not only when the experiment is enabled. An expression such as --filter '1...(foo | bar)' previously matched a unit literally named (foo or bar); it is now rejected as a malformed boundary. Wrap a name or path containing parentheses in braces (e.g. --filter '{./weird(name)}') to keep it literal.

browse-tui — Added an interactive browser for your estate

The new browse-tui experiment adds the terragrunt browse command. With the experiment enabled, terragrunt browse opens a three-column Terminal User Interface (TUI) browser of your infrastructure estate: the parent directory on the left, the current directory in the middle, and a detail pane on the right showing metadata for the highlighted unit, stack, or directory. The browser opens immediately and fills in metadata as discovery completes in the background.

Enable it with --experiment browse-tui or TG_EXPERIMENT=browse-tui. See the experiment documentation for the keybindings, search, and the criteria for stabilization.

mutable-generate — Deduplicated generate block output

The mutable-generate experiment has been added. With it enabled, the contents a generate block produces are stored in the Content Addressable Store (CAS), and the file written at path is a read-only link to that stored copy rather than a file of its own.

Since the stored copy is addressed by the hash of its contents, anything generating identical contents links to the same copy. A generate block inherited by several hundred units therefore costs one copy in .terragrunt-cache rather than several hundred.

The link is read-only because that copy is shared. Where a generated file does need to be edited in place, a new mutable attribute on the generate block gives it a writable file of its own:

generate "provider" {
  path = "provider.tf"
  if_exists = "overwrite"
  mutable = true
  contents = "..."
}

Setting mutable without the experiment enabled is an error, since earlier Terragrunt versions reject the attribute. The CAS is required, so --no-cas writes generated files directly and mutable has no effect.

For details, see the experiment documentation.

optional-dependency-outputs — Added --no-dependency-outputs flag to skip dependency output resolution

Added a --no-dependency-outputs flag that skips all dependency output resolution globally, mirroring the existing skip_outputs = true attribute on individual dependency blocks.

The feature is gated behind the optional-dependency-outputs experiment:

TG_EXPERIMENT=optional-dependency-outputs terragrunt run --no-dependency-outputs -- init

Using --no-dependency-outputs without enabling the optional-dependency-outputs experiment will return an error.

Thanks to @pjrm for contributing this feature!

🧪 Experiments Updated

catalog-format — Added reading the catalog as JSON Lines

The catalog command draws a terminal user interface, and refuses to start where there is no terminal to draw it on. With the catalog-format experiment enabled, --format=jsonl writes the same discovery to standard output instead, as one JSON object per line:

terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c '{kind, title, component_source}'

Entries are written as they are discovered rather than collected first, so output is readable while the remaining repositories are still loading, and a reader that stops early ends the command quietly:

terragrunt catalog --experiment=catalog-format --format=jsonl | head -5

Note

Closing the pipe

In this example, the head program exits after reading in five lines, and Terragrunt detects the SIGPIPE signal from the OS, and shuts down cleanly.

Entries appear in discovery order, which interleaves the repositories being loaded and differs between runs. Every entry carries the complete body of the component's README in the doc field. Combine usage of Terragrunt with other tools like jq to drop it.

terragrunt catalog --experiment=catalog-format --format=jsonl | jq -c 'del(.doc)'

Entries follow a published JSON schema. For the fields and their meanings, see Non-interactive catalog.

--format=tui is the default, and leaves the terminal user interface exactly as it was.

catalog-format — Added reading the catalog as Markdown

The catalog-format experiment gains a second non-interactive format. Where --format=jsonl writes a record per catalog entry for a program to parse, --format=md writes one Markdown document for a person or an agent to read:

terragrunt catalog --experiment=catalog-format --format=md > catalog.md

Each entry becomes a section holding the metadata the catalog user interface shows for it, the source the component is scaffolded from, and the component's README. Sections are written as entries are discovered, so the document is readable while the remaining repositories are still loading.

READMEs are reproduced inside fenced blocks, so the headings one carries are not read as sections of the catalog document. The document closes with a table naming every component it holds and a count of what was discovered, which is how a reader tells a complete document from one that was cut short by a consumer that stopped reading.

For the fields each section carries, see Non-interactive catalog.

oci — Added OCI sources for stack units and stacks

terragrunt.stack.hcl now accepts oci:// sources in unit and stack blocks, so a stack can pull its components straight from an OCI registry. Without the oci experiment enabled, such a source fails with a clear error instead of an unsupported-scheme failure.

oci — Added OpenTofu CLI-config credentials for OCI module sources

oci:// module downloads now read OpenTofu's CLI-config credentials, so one configuration serves both OpenTofu and Terragrunt.

Terragrunt honors the oci_credentials "[/]" blocks (username and password, OAuth tokens, or a docker_credentials_helper, which like tofu may only be set on a whole registry) and the oci_default_credentials fallback helper. A TF_CLI_CONFIG_FILE or TERRAFORM_CONFIG value selects the config file outright; otherwise Terragrunt reads the first of ~/.tofurc and ~/.terraformrc that exists, and merges the *.tfrc and *.tfrc.json files in OpenTofu's config directory.

Terragrunt picks the most specific matching source across CLI config and ambient Docker config; an explicit CLI-config entry wins when both match equally. Set discover_ambient_credentials = false in the oci_default_credentials block to use CLI config only.

⚙️ Process Updates

Go bumped to v1.26.5

The version of Golang used to compile the Terragrunt binary has been updated from v1.26.0 to v1.26.5.

Thanks to @apoiget for contributing this upgrade!

Pull Requests

✨ Features

• feat: Adding graph boundary via () syntax by @yhakbar in #6365
• feat: Adding --discovery-boundary flag by @yhakbar in #6355
• feat(getter): OpenTofu CLI-config credentials for oci:// sources by @denis256 in #6531
• feat: Adding browse by @yhakbar in #6219
• feat: Adding mutable attribute to the generate block by @yhakbar in #6563
• feat: Adding md format for catalog by @yhakbar in #6608
• feat: Add --skip-dependency-outputs flag to skip dependency output resolution by @pjrm in #6422

🐛 Bug Fixes

• fix(providercache): log -lockfile=readonly skip at debug level by @bryanhorstmann in #6577
• fix: Fixing handling of EOF in generate blocks by @yhakbar in #6592
• fix: Fixing the --config= form of flags used in the tflint hook by @yhakbar in #6591
• fix: Fixing fast-copy ancestor directory permissions by @yhakbar in #6593
• fix: Addressing providers lock -platform usage with space delimited values by @yhakbar in #6597
• fix: Fixing bug with negation | positive expression in the same query. by @yhakbar in #6598
• fix: Fixing provider cache server archive dir race by @yhakbar in #6620
• fix: Fixing scaffold on units and stacks by @yhakbar in #6607
• fix: Addressing feedback from #6565 and #6605 by @yhakbar in #6628
• fix: autoinclude values override for inputs by @denis256 in #6626
• fix: Fixing md format catalog escaping by @yhakbar in #6638
• fix: Plumbing through evalCtx for discovery boundary by @yhakbar in #6632
• fix: Fixing stack dependency mock outputs by @yhakbar in #6530
• fix: Fixing issue where dependency mock outputs aren't used when bootstrapping hasn't run yet. by @yhakbar in #6534

🏎️ Performance

• perf: Reducing allocations in tree parse by @yhakbar in #6648

📖 Documentation

• docs: Add call out for terragrunt scale in quick start by @yhakbar in #6583
• docs: document oci module sources, authentication, and caching by @denis256 in #6636
• docs: Cleaning up changelog for v1.1.3 by @yhakbar in #6669
• docs: Cleaning up experiment docs by @yhakbar in #6627
• docs: address review feedback on the oci and autoinclude docs by @denis256 in #6643

✅ Tests

• test(getter): integration tests against a local OCI distribution registry by @denis256 in #6614
• test: prove oci module portability between tofu and terragrunt by @denis256 in #6629
• test(git): add unit coverage for internal/git command wrappers and parsers by @denis256 in #6661

🧹 Chores

• chore: Pin exact provider versions for terralith to terragrunt guide by @yhakbar in #6578
• chore: Using vfs handle for ParseFromFile by @yhakbar in #6561
• chore: Walk in discovery with vfs by @yhakbar in #6564
• chore: Registring catalog-format experiment by @yhakbar in #6582
• chore(deps): update AWS, Azure, GCP SDKs by @denis256 in #6590
• chore: Continuing clean-up of go test ./... on a fresh clone of the repo by @yhakbar in #6553
• chore: Fixing usage of deprecated aws sdk by @yhakbar in #6600
• chore: Cleaning up profile tests per feedback in #6553 by @yhakbar in #6599
• chore: Clean-up by @yhakbar in #6584
• chore: Addressing feedback from #6365 and #6355 by @yhakbar in #6603
• chore: Register the block-iteration experiment by @yhakbar in #6562
• chore: address review feedback from #6531 by @denis256 in #6609
• chore: Addressing flake in TestCatalogJSONLFormatCleansUpOnEarlyExit by @yhakbar in #6613
• chore: updated TestDiscovery_GraphConcurrentConfigAccessWithRacing to use VFS by @denis256 in #6622
• chore: Adding expansion detection and internal expansion logic by @yhakbar in #6565
• chore: Adding expansion blocks to the configs that accept expansion by @yhakbar in #6605
• chore: Threading venv through getters and hcl fmt by @yhakbar in #6621
• chore: Addressing feedback from #6621 by @yhakbar in #6633
• chore: Fixing experiment tag in sidebar by @yhakbar in #6635
• chore: Updating mem exec so that it fails closed by @yhakbar in #6634
• chore: Gate real hg usage test behind the exec build flag by @yhakbar in #6637
• chore: Replacing aws provider with null provider in init-cache fixture by @yhakbar in #6639
• chore: Cleaning up NewParsingContext constructor by passing in venv as a param by @yhakbar in #6630
• chore: Addressing lint finding by @yhakbar in #6649
• chore: Refactoring markdown deps into internal/md by @yhakbar in #6640
• chore: Adding unit tests for internal packages by @denis256 in #6660
• chore: Bumping Go to 1.26.5 (#6664) by @apoiget in #6666
• chore: Dropping stale tree parse test case by @yhakbar in #6672

Original source

✨ 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()

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.

In micro-benchmarks, resolving the root configuration for 100 units nested eight directories deep went from 4.8ms to 0.49ms. Across the benchmarked shapes the lookups run between 7x and 10x faster, and the time saved grows with both the number of units and how deeply they sit below their root configuration.

🐛 Bug Fixes

Fixed roles assuming themselves for backend operations

A regression in v1.1.1 broke setups that provide static AWS credentials and configure a role via the iam_role attribute, the --iam-assume-role flag, or TG_IAM_ASSUME_ROLE.

In those setups, Terragrunt assumes the role once at the start of a run, and every later AWS call uses that role session. In v1.1.1, backend operations like bootstrapping the state bucket started performing an extra role assumption of their own. Since the run was already using the role session at that point, the role tried to assume itself, and AWS rejected the call with an AccessDenied error unless the role's trust policy happened to include the role itself.

Backend operations now reuse the role session from the start of the run, as they did before v1.1.1.

This does not affect the assume_role attribute of the remote_state block. Roles configured there are backend-specific and are still assumed on top of the supplied credentials, so the cross-account role assumption should continue to work as expected.

Local sources no longer re-init when uncopied files change

For units with a local source, Terragrunt decides whether the cached copy is stale by hashing the source directory. That hash previously covered every file in the directory, including hidden files and exclude_from_copy matches that are never copied into the cache. Creating or touching such a file (an editor swap file, a scratch note) changed the hash, forcing a needless re-copy and auto-init on the next run.

The hash now covers only the files a copy would deliver, honoring the default hidden-file rule along with include_in_copy and exclude_from_copy. Files that never reach the cache no longer trigger re-initialization.

Fixed width truncation of colored and multi-byte log content

The width option in a custom log format sizes a column to a fixed number of visible characters. When the content held color codes or multi-byte characters and was longer than the column, truncation cut the raw bytes: it could slice through the middle of a color code, leaving color bleeding into the rest of the line, or split a multi-byte character into invalid output, and it dropped more visible text than the configured width.

width now measures and cuts by visible characters. Color codes are preserved intact, multi-byte characters are never split, and the column keeps exactly the requested number of visible characters.

Provider cache downloads now require a secret URL

The Provider Cache Server now hardens the download endpoint that fetches provider archives on the caller's behalf. That endpoint attaches whatever registry credentials are configured for the upstream host, and it was the only one on the server that did not require the token generated for the run, so any other process on the machine could use a running cache server to pull artifacts from a private registry with the credentials of whoever started the run.

The download URLs handed to OpenTofu and Terraform now carry a secret path segment, generated fresh each time the cache server starts and redacted from the server's own logs. Requests that omit the segment get a 404.

Run report no longer mangles the names of paths that share a prefix with the working directory

When a run's path shared a string prefix with the working directory without being nested under it, the run report shortened its name by shearing off the prefix mid-segment. A working directory of /repo/project alongside a run at /repo/project-staging/unit produced the name -staging/unit.

The report now shortens a path only when it is genuinely nested under the working directory. Sibling paths keep their full name.

Feature flag defaults no longer leak between units in run --all

A feature block's default was recorded once per run and shared by every unit. During run --all, the first unit to be parsed set the value for a flag name, so a unit defining default = false could evaluate feature.toggle.value as true because a sibling unit was parsed first. Which unit won depended on parsing order, making the result vary between runs.

Defaults are now resolved per unit, including defaults inherited through include. Overrides passed with --feature or TG_FEATURE continue to apply to every unit in the run.

Thanks to @dhotcolorado for reporting and fixing this!

Fixed S3 source downloads under EKS Pod Identity

Downloading unit sources from private S3 buckets (s3::https://...) now works when EKS Pod Identity is the only credential source. Previously, the bundled aws-sdk-go v1 rejected the Pod Identity Agent endpoint (169.254.170.23) because it only allowed loopback hosts. Terragrunt now uses aws-sdk-go v1.55.6, which allows the EKS and ECS container credential endpoints.

🧪 Experiments Added

otel-logs experiment exports logs to OpenTelemetry

Terragrunt previously emitted only traces and metrics, so there was no way to ship its log output to an OpenTelemetry backend or correlate log lines with the spans of a failed run.

Enable the new otel-logs experiment to add an OpenTelemetry logs signal, configured with TG_TELEMETRY_LOGS_EXPORTER:

• none - no log exporting, the default.
• console - write log records to the console as JSON.
• otlpHttp - export logs to an OpenTelemetry collector over HTTP.
• otlpGrpc - export logs to an OpenTelemetry collector over gRPC.

TG_TELEMETRY_LOGS_EXPORTER=otlpHttp terragrunt run --all --experiment otel-logs -- apply

The OTLP exporters read the endpoint from the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable. Set TG_TELEMETRY_LOGS_EXPORTER_INSECURE_ENDPOINT=true to disable TLS when collecting locally. Records emitted while a span is active carry its trace and span IDs, so a failed unit's logs link to its span in the backend. Without the experiment enabled, the logs exporter stays inert regardless of TG_TELEMETRY_LOGS_EXPORTER.

profiling experiment adds pprof collection for Terragrunt runs

Enable the new profiling experiment to collect CPU profiles, memory (heap) profiles, and goroutine profiles (stack traces of all goroutines) using CLI flags. Profiling is intended for debugging the performance of Terragrunt itself, and for exploring ways to optimize Terragrunt as an application; it will not help with improving the performance of the infrastructure Terragrunt manages.

Example:

terragrunt --experiment=profiling --profile-cpu cpu.prof --profile-mem mem.prof --profile-goroutine goroutine.prof run -- plan

Use --profile-dir to collect all profiles into a single directory with conventional names (terragrunt_cpu.prof, terragrunt_mem.prof, terragrunt_goroutine.prof):

terragrunt --experiment=profiling --profile-dir /tmp/profiles run --all -- plan

The same behavior is available via environment variables when the profiling experiment is enabled:

• TG_PROFILE_CPU
• TG_PROFILE_MEM
• TG_PROFILE_GOROUTINE
• TG_PROFILE_DIR

When using --profile-dir or TG_PROFILE_DIR, Terragrunt also sets TOFU_CPU_PROFILE for each unit so downstream OpenTofu processes (OpenTofu 1.11 or later) write their own CPU profiles into unit-specific subdirectories. An explicitly set TOFU_CPU_PROFILE is never overridden.

🧪 Experiments Updated

azure-backend now manages Azure Storage remote state

The azure-backend experiment now enables functional Terragrunt support for the Azure Storage (azurerm) remote-state backend.

When the experiment is enabled, Terragrunt can bootstrap the resource group, storage account, and blob container used by remote_state { backend = "azurerm" }, detect whether the backend needs bootstrapping, converge blob versioning and soft-delete settings, delete state blobs or containers, and migrate state blobs within the same storage account.

Terragrunt-only settings such as location, the storage account SKU options, the skip_* flags, enable_soft_delete, soft_delete_retention_days, and msi_resource_id are consumed by Terragrunt and removed before it runs OpenTofu/Terraform with init -backend-config, so the underlying azurerm backend receives only keys it understands. msi_resource_id is not bootstrap-only: it also selects the managed identity used for delete and migrate.

This remains opt-in while the experiment is active:

terragrunt --experiment azure-backend run -- plan

Thanks to @omattsson for driving this support forward.

oci - Credential helpers for OCI module sources

oci:// module downloads now use the Docker credential helpers you already have configured, so registries like Amazon ECR authenticate automatically with no extra setup.

oci - Content-addressable caching for OCI module sources

oci:// module sources now integrate with Content Addressable Storage. When the oci experiment is enabled, downloads are cached by their manifest digest, so a repeated fetch of the same tag or digest is served from the local store instead of re-downloaded from the registry.

Mutable tags stay correct: every fetch re-resolves the tag to its current manifest digest at download time, so re-pushing a module under the same tag invalidates the cache and pulls the new content rather than serving a stale copy. A digest-pinned source (?digest=sha256:...) skips registry resolution and keys the cache directly.

oci - Downloading modules from OCI registries

The oci experiment now downloads source code (including OpenTofu modules) from OCI Distribution registries. When enabled, Terragrunt accepts oci:// source URLs in Terragrunt configurations (including terraform.source attributes). Specify either tag or digest; omitting both selects the latest tag. //subdir selectors are supported. Artifacts follow the same publishing contract OpenTofu 1.10 consumes natively.

Authentication covers static credentials via interim TG_TMP_OCI_* environment variables and read-only ambient discovery of Docker and containers auth files. Static credentials can be limited to one registry with TG_TMP_OCI_REGISTRY; without it, the configured token or username and password may be offered to any registry the process contacts. Credential helpers (such as ecr-login) are not invoked yet, so registries that need per-run token minting only work while an externally obtained login is present in an ambient file.

When the experiment is disabled, oci:// sources remain unsupported.

For setup steps, see the experiment documentation.

Pull Requests

✨ Features

feat(getter): implement OCIGetter.Get with fake-store unit tests by @denis256 in #6479
feat: Add otel-logs experiment by @yhakbar in #6279
feat(getter): add static and ambient OCI credential discovery by @denis256 in #6483
feat(getter): add WithOCI and gate oci sources behind the oci experiment by @denis256 in #6486
feat(getter): add OCI digest CAS resolver with tag re-resolution by @denis256 in #6503
feat: Adding earlier catalog bail by @yhakbar in #6493
feat(profiling): add automatic pprof collection by @denis256 in #5711
feat(getter): credential helpers for oci:// module sources by @denis256 in #6508
feat: add experimental azurerm remote state backend by @denis256 in #6428

🐛 Bug Fixes

fix: Fixing docs TF_TOKEN_* rendering by @yhakbar in #6509
fix: Preventing spurious re-inits by @yhakbar in #6504
fix: Fixing log truncation by @yhakbar in #6526
fix: support EKS Pod Identity for S3 source downloads by @denis256 in #6532
fix: Isolate feature defaults per unit in run --all by @dhotcolorado in #5995
fix: Adding random URL segment to download URI by @yhakbar in #6547
fix: Fixing report path prefix trim by @yhakbar in #6527
fix: Fixing self-chained role assumption by @yhakbar in #6521
fix: prevent auto-init env vars from leaking into main command by @yapret in #6576

🏎️ Performance

perf: Memoize find_in_parent_folders() by @yhakbar in #6545

📖 Documentation

docs: Adding CLI flag precedence rule by @yhakbar in #6524
docs: Adding changelog entry for #5995 by @yhakbar in #6548
docs: Re-organizing content related to the run queue out of stack documentation by @yhakbar in #6114
docs: Adding search telemetry by @yhakbar in #6555
docs: Improving docs by addressing frequently asked questions by @yhakbar in #6560

🧹 Chores

chore: Log Windows console mode retrieval failures at debug level (#6374) by @AgustinSabalza in #6376
chore: Fixing code fences on /reference/hcl/blocks/ by @yhakbar in #6485
chore: Avoid package-level module resolution for version attribute by @yhakbar in #6482
chore: AWS dependencies bump by @denis256 in #6502
chore: Running fd -tf -e go -x golines -w to avoid run-on lines by @yhakbar in #6484
chore: Adding some integration testing for the version attribute by @yhakbar in #6487
chore: Unify Venv struct by dropping cas.Venv by @yhakbar in #6488
chore: Adding vsops by @yhakbar in #6506
chore: speed up slowest tests with unit-level coverage and hermetic fixtures by @denis256 in #6436
chore: lint fixes by @denis256 in #6518
chore(deps): bump astro from 7.0.4 to 7.1.0 in /docs by @dependabot[bot] in #6515
chore: Fixing panic in Windows test by @yhakbar in #6536
chore: Update grpc, x/mod, go-shellwords deps by @denis256 in #6543
chore: Adding more tests for build metadata by @yhakbar in #6538
chore: Adding vhttp client to abstract away HTTP client connections by @yhakbar in #6121
chore: Cleaning up tests for #6547 by @yhakbar in #6549
chore: Refactor for network isolation in tests by @yhakbar in #6507
chore: fixed failed lint tests by @denis256 in #6550
chore: Fixing pprof venv access by @yhakbar in #6556
chore: Updating Kapa integration by @yhakbar in #6558
chore: coverage report fixes by @denis256 in #6557
chore: Reducing race in vexec testing by @yhakbar in #6551

Original source