Active Experiments

The following experiments are available for opt-in. See the experiments overview for how to enable them.

---

azure-backend

Experimental support for the Azure Storage (azurerm) remote state backend.

azure-backend - What it does

Terragrunt already recognizes backend = "azurerm" in remote_state blocks regardless of whether this experiment is enabled, and currently falls through to the native OpenTofu/Terraform azurerm backend. This experiment reserves the flag for the long-term goal of having Terragrunt manage Azure Storage accounts, blob containers, and state blobs in the same way it already manages S3 buckets and GCS buckets: automatic bootstrap, delete, migrate, and direct state reads for dependency-fetch-output-from-state.

In its current form (initial registration) the experiment only:

• Reserves the azure-backend experiment name.
• Reserves the azurerm backend slot in Terragrunt’s remote state layer.

The flag itself currently has no behavioral effect: there is no Azure SDK code, authentication logic, or storage account management yet, and the backend is not gated on the flag. Functional behavior will land in subsequent releases.

azure-backend - How to enable it

# Via CLI flag
terragrunt --experiment azure-backend run -- plan

# Via environment variable
export TG_EXPERIMENT=azure-backend
terragrunt run -- plan

azure-backend - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4307. When reporting issues or providing feedback, please include:

• The Azure authentication method you are using (Azure AD, MSI, service principal, SAS, access key).
• The cloud environment (public, government, china).
• Any errors encountered during init, plan, or backend bootstrap.

azure-backend - Criteria for stabilization

To transition the azure-backend feature to a stable release, the following must be addressed, at a minimum:

• internal/azurehelper package wrapping the Azure SDK with a builder pattern matching awshelper/gcphelper.
• Bootstrap of storage accounts and blob containers, including versioning and optional RBAC role assignment for use_azuread_auth.
• Delete and migrate operations for state blobs and containers with confirmation prompts.
• Direct state file reads from Azure blobs for --dependency-fetch-output-from-state.
• Documentation covering authentication methods, configuration keys, and troubleshooting.
• Integration test coverage gated behind a build tag.
• Community feedback on real-world usage.

---

deep-merge

Support for the deep_merge HCL function.

deep-merge - What it does

When enabled, Terragrunt exposes a deep_merge(map1, map2, ...) HCL function for combining map or object values.

For overlapping keys, values from later arguments override earlier arguments. Nested maps are merged recursively, lists are appended, and null arguments are ignored.

This is useful when building inputs from multiple JSON, YAML, or HCL-derived maps without having to rely on include block merge behavior.

terragrunt run --all --experiment deep-merge -- plan

deep-merge - How to provide feedback

Provide your feedback in the deep-merge GitHub Discussion.

deep-merge - Criteria for stabilization

To transition the deep-merge feature to a stable release, the following must be addressed:

• Confirm the merge semantics are useful for common configuration layering workflows.
• Confirm type handling for decoded JSON/YAML and native HCL objects matches user expectations.
• Positive feedback from users relying on the function in production pipelines.

---

dependency-fetch-output-from-state

Support for fetching dependency outputs directly from state files.

dependency-fetch-output-from-state - What it does

By default, Terragrunt retrieves dependency outputs by running tofu output or terraform output commands, which requires initializing the dependency unit and can be slow. When this experiment is enabled, Terragrunt will attempt to fetch dependency outputs directly from the remote state file, bypassing the need to initialize the dependency and significantly speeding up dependency processing.

Current Backend Support:

• S3 backend: Fully supported
• Other backends: Falls back to the normal method (using tofu/terraform output)

When an unsupported backend is encountered, Terragrunt will automatically fall back to the default method of using tofu/terraform output.

Known Limitations:

This experiment is not compatible with OpenTofu state encryption. When OpenTofu’s client-side state encryption is enabled, the state file stored in S3 is encrypted before upload. Since this experiment reads the raw state file directly from S3 via the AWS SDK, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, you must disable this experiment using the --no-dependency-fetch-output-from-state flag.

Disabling the feature:

You can disable the dependency-fetch-output-from-state feature using the --no-dependency-fetch-output-from-state flag, even when the experiment is enabled:

terragrunt run --all --experiment-mode --no-dependency-fetch-output-from-state -- plan

dependency-fetch-output-from-state - How to provide feedback

Provide your feedback in the dedicated GitHub discussion page. When reporting issues or providing feedback, please include:

• The backend type you’re using
• Any performance improvements you’ve observed
• Any issues or edge cases you’ve encountered

dependency-fetch-output-from-state - Criteria for stabilization

To transition the dependency-fetch-output-from-state feature to a stable release, the following must be addressed, at a minimum:

• Add support for additional backends (e.g., GCS, etc.)
• Comprehensive integration testing across different backend types
• Performance benchmarking to validate speed improvements
• Error handling and edge case testing
• Documentation of supported backends and limitations
• Handle OpenTofu state encryption gracefully (fallback or explicit error message)
• Community feedback on real-world usage

---

hook-context-env

Expose additional TG_CTX_* environment variables to hook scripts.

hook-context-env - What it does

When enabled, Terragrunt sets three additional environment variables on the process running every before_hook, after_hook, and error_hook:

• TG_CTX_HOOK_TYPE — before_hook, after_hook, or error_hook, depending on which lifecycle phase is executing the hook.
• TG_CTX_SOURCE — the resolved terraform source URL for the current unit, matching the precedence Terragrunt uses for the actual download: the --source CLI override if set, otherwise the evaluated terraform.source (with --source-map applied), otherwise ..
• TG_CTX_TERRAGRUNT_DIR — the directory containing the current Terragrunt config (equivalent to get_terragrunt_dir()).

These variables make it easier for hook scripts to branch on lifecycle phase, to know whether the unit pulls remote source, and to locate the config directory without having to thread that information through hook arguments.

terragrunt run --all --experiment hook-context-env -- apply

Example hook script:

#!/usr/bin/env bash

case "$TG_CTX_HOOK_TYPE" in
  before_hook) echo "preparing $TG_CTX_TERRAGRUNT_DIR" ;;
  after_hook)  echo "cleaning up $TG_CTX_TERRAGRUNT_DIR" ;;
  error_hook)  echo "failure in $TG_CTX_TERRAGRUNT_DIR" ;;
esac

if [ "$TG_CTX_SOURCE" != "." ]; then
  echo "unit uses source: $TG_CTX_SOURCE"
fi

hook-context-env - How to provide feedback

Provide your feedback in the hook-context-env GitHub Discussion.

hook-context-env - Criteria for stabilization

To transition the hook-context-env feature to a stable release, the following must be addressed:

• Confirm the three new variables cover the most common hook scripting needs.
• Confirm the chosen variable names and values (before_hook/after_hook/error_hook) match user expectations.
• Positive feedback from users relying on the variables in production hook scripts.

---

iac-engine

Support for Terragrunt IaC engines.

iac-engine - What it does

Enables usage of Terragrunt IaC engines for running IaC operations. This allows Terragrunt to use pluggable engines to execute Terraform/OpenTofu commands, providing enhanced functionality and extensibility.

IaC engines are still experimental, as the API is unstable and may change in future minor versions of Terragrunt.

You can disable engine usage on a per-command basis using the --no-engine flag, even when the experiment is enabled globally.

iac-engine - How to provide feedback

Provide your feedback on the Terragrunt IaC Engines GitHub discussion.

iac-engine - Criteria for stabilization

To transition the iac-engine feature to a stable release, the following must be addressed, at a minimum:

• API stability and backward compatibility guarantees
• Comprehensive integration testing across all supported operations
• Documentation of engine development and integration process
• Performance benchmarks and optimization
• Security review of engine execution and isolation mechanisms
• Community feedback on real-world usage and edge cases

---

oci

Experimental support for downloading modules from OCI Distribution registries using oci:// sources.

oci - What it does

OpenTofu 1.10 can download modules from an OCI Distribution registry using an oci:// source, but Terragrunt currently fails to resolve the same source in a terraform { source = "..." } block because no getter claims the oci scheme. This experiment reserves the flag for native Terragrunt support of oci:// module sources, so a single source string works the same way in both tofu and Terragrunt against registries such as Amazon ECR, GitHub Container Registry, Azure Container Registry, Google Artifact Registry, and self-hosted or air-gapped registries.

In its current form (initial registration) the experiment only reserves the oci experiment name. The experiment has no behavioral effect yet: there is no getter for the oci scheme, and oci:// sources still fail to download. Functional behavior will land in subsequent releases, gated by this experiment.

oci - How to enable it

# Via CLI flag
terragrunt --experiment oci run -- plan

# Via environment variable
export TG_EXPERIMENT=oci
terragrunt run -- plan

oci - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#4555. When reporting issues or providing feedback, please include:

• The registry you are using (ECR, GHCR, ACR, GAR, self-hosted).
• The authentication method (static credentials, ambient Docker config, or a credential helper such as ecr-login).
• The full oci:// source string, and whether you pin by tag or digest.
• Any errors encountered during module download.

oci - Criteria for stabilization

To transition the oci feature to a stable release, the following must be addressed, at a minimum:

• A getter that resolves oci:// sources, selecting the application/vnd.opentofu.modulepkg artifact and its archive/zip layer, with blob digest verification.
• Static and ambient Docker-config credential discovery matching OpenTofu’s search order.
• Credential-helper support (docker-credential-*, ecr-login) so ECR and other helper-backed registries work with per-run token minting.
• Content-addressable caching keyed on the resolved manifest digest, with correct re-resolution of mutable tags.
• A portability guarantee that one source string produces an identical module via tofu and Terragrunt.
• Documentation covering the source syntax, authentication tiers, and publishing contract.
• Integration test coverage against a real registry, gated behind a build tag.
• Community feedback on real-world usage.

---

optional-hooks

Support for disabling Terragrunt hooks during run.

optional-hooks - What it does

When enabled, users can pass --no-hooks to terragrunt run to skip configured before_hook, after_hook, and error_hook blocks.

terragrunt run --experiment optional-hooks --no-hooks -- plan

This is useful when a run needs to bypass hook automation temporarily, such as when debugging faulty hooks or OpenTofu/Terraform modules.

optional-hooks - Criteria for stabilization

To transition the optional-hooks feature to a stable release, the following must be addressed:

• Validate behavior with single-unit and queue-based runs.
• Gather community feedback on whether all hook types should be skipped.
• Confirm the flag name leaves room for more granular hook controls in the future.

---

slow-task-reporting

Progress reporting for long-running Terragrunt operations.

slow-task-reporting - What it does

When enabled, Terragrunt displays animated progress spinners for operations that take longer than 1 second (e.g., Git worktree creation). Once the operation completes, the spinner is replaced with an INFO log line showing the operation result and elapsed time.

This provides visual feedback during operations that would otherwise show no output:

• Git worktree creation for --filter with Git references
• Catalog repository cloning (terragrunt catalog)
• OpenTofu/Terraform source downloads via go-getter

In non-interactive environments (CI/CD, piped output), spinners are suppressed and INFO log lines are emitted instead. To prevent CI systems (e.g., CircleCI) from killing jobs due to prolonged output silence, periodic keepalive log lines are emitted every 30 seconds while the operation is in progress.

terragrunt run --all --experiment slow-task-reporting -- plan

slow-task-reporting - How to provide feedback

Provide your feedback on the slow-task-reporting GitHub Discussion.

slow-task-reporting - Criteria for stabilization

To transition the slow-task-reporting feature to a stable release, the following must be addressed:

• Validate spinner rendering across common terminal emulators (iTerm2, Terminal.app, Windows Terminal, GNOME Terminal)
• Extend progress reporting to additional slow operations (e.g., provider caching)
• Community feedback on usefulness and threshold tuning
• Ensure no interference with structured log output when using --log-format json

---

symlinks

Support symlink resolution for Terragrunt units.

symlinks - What it does

By default, Terragrunt will ignore symlinks when determining which units it should run. By enabling this experiment, Terragrunt will resolve symlinks and add them to the list of units being run.

symlinks - How to provide feedback

Provide your feedback on the Experiment: Symlinks discussion.

symlinks - Criteria for stabilization

To stabilize this feature, the following need to be resolved, at a minimum:

• Ensure that symlink support continues to work for users referencing symlinks in flags. See #3622.
  • Add integration tests for all filesystem flags to confirm support with symlinks (or document the fact that they cannot be supported).
• Ensure that MacOS integration tests still work. See #3616.
  • Add integration tests for MacOS in CI.

---

version-attribute

Support for a version attribute on the terraform block that resolves a registry module from a version constraint.

version-attribute - What it does

When enabled, the terraform block accepts an optional version attribute holding a version constraint for a tfr:// registry module, such as ~> 3.3 or >= 1.0.0, < 2.0.0:

terraform {
  source  = "tfr://registry.opentofu.org/terraform-aws-modules/vpc/aws"
  version = "~> 3.3"
}

Terragrunt resolves the constraint against the registry’s list-versions endpoint before the download begins, then fetches the highest published version that satisfies it. This brings the terraform block to parity with the version argument on OpenTofu and Terraform module blocks, so you no longer have to pin an exact version in the source URL.

The constraint lives only in the version attribute. By the time the module is downloaded and cached, it has been resolved to an exact version, so the --source override and the cache key still carry a concrete pin.

version-attribute - How to enable it

# Via CLI flag
terragrunt --experiment version-attribute run -- plan

# Via environment variable
export TG_EXPERIMENT=version-attribute
terragrunt run -- plan

version-attribute - How to provide feedback

Track and discuss this experiment in gruntwork-io/terragrunt#1930. When reporting issues or providing feedback, please include:

• The tfr:// source and the version constraint you set.
• The version you expected Terragrunt to resolve, and the version it resolved.
• Whether you rely on prereleases, and how you upgrade across newly published versions.

version-attribute - Criteria for stabilization

To transition the version-attribute feature to a stable release, the following must be addressed, at a minimum:

• Decide and document the cache invalidation policy. A constraint resolves once and is cached by source URL, so a newly published match is only picked up after --source-update. Confirm this is the right default, or re-resolve on every run.
• Decide and document the prerelease policy. A constraint that names a prerelease (for example >= 1.0.0-rc1) opts into prereleases, matching OpenTofu and Terraform.
• Decide whether --source and TG_SOURCE should keep accepting exact pins only, or also accept constraints.
• Community feedback on real-world usage.