Skip to main content

Native Terragrunt Integration Beyond Discovery

· 6 min read
Erik Osterman
Founder @ Cloud Posse

Teams adopting Atmos alongside Terragrunt need more than a list of units. Existing HCL must retain its backend identity, generated-file ownership, and dependencies when Atmos prepares an operation. This experimental extension builds on native discovery with additional host adapters and compatibility checks.

Native Terragrunt discovery and planning
 
00:00.0 / 00:00.0

View the full example

Try it locally​

The example keeps a Terragrunt unit under live/, discovers it as an Atmos Terraform component, and plans a built-in terraform_data resource with OpenTofu. It requires no cloud credentials or Terragrunt executable.

Development build required

The plugin and example are not yet released. Build Atmos and the native plugin from this PR's checkout before running the commands below. The example initializer in the widget uses main; until this PR merges, copy the example from your checkout instead:

# Run from the Atmos repository checkout for this PR.
go build -o build/atmos .
./build/atmos plugin build plugins/terragrunt
export PATH="$PWD/build:$PATH"
export ATMOS_TERRAGRUNT_PLUGIN_PATH="$PWD/plugins/terragrunt"
atmos init ./examples/terragrunt-native ./terragrunt-native \
--copy --no-git
cd terragrunt-native
export ATMOS_PROFILE=dev

Install OpenTofu before planning. The recording starts after the host and plugin have been built and the package path configured.

Copy the example into a new directory and make it your own:

atmos init examples/terragrunt-native
cd terragrunt-native

The example's dev profile reads the package path from ATMOS_TERRAGRUNT_PLUGIN_PATH. Select it, then inspect and plan the discovered unit:

export ATMOS_PROFILE=dev
atmos list stacks
atmos list instances
atmos terraform plan demo -s live

The example already enables native discovery. It stores state locally if you choose to apply it; its README includes apply, output, and cleanup commands.

Enable compatibility in an existing project​

From your project's root, register the built plugin and opt into native discovery with config set:

atmos config set plugins.packages.terragrunt.path \
"$ATMOS_TERRAGRUNT_PLUGIN_PATH"
atmos config set components.terraform.base_path \
components/terraform
atmos config set components.terraform.command tofu
atmos config set components.terraform.terragrunt.enabled true
atmos config set components.terraform.terragrunt.mode native
atmos config set --type=yaml \
components.terraform.terragrunt.discovery.included_paths \
'["live/**"]'
atmos config set \
components.terraform.terragrunt.discovery.enabled true
atmos list stacks
atmos list instances

Adjust live/** to your Terragrunt directory layout. Atmos requires components.terraform.base_path even though Terragrunt units do not live there, and the directory does not need to exist. Keep your existing Terraform command setting if you use Terraform instead of OpenTofu. Discovery does not require per-unit Atmos YAML. Use the component and stack names from the inventory when running atmos terraform plan <component> -s <stack>.

Put units in the stacks you already have​

Discovery names a unit's stack after the directory above it. To make a unit a component of one of your own stacks instead, import it from that stack's file:

import:
- terragrunt://live/dev

The units below live/dev become components of the importing stack, and no extra stack appears. Import the same unit from a shared mixin and every stack that uses the mixin gets it. If an imported unit has the same component name as a YAML component in that stack, Atmos names both and stops. Discovery paths, patterns, and symlink rules are described in the migration guide.

Inspect the executor​

The default instance table shows Component, Stack, Type, and Engine. A native Terragrunt unit remains a Terraform component. Its engine reflects the selected Terraform or OpenTofu executable.

Existing column overrides remain authoritative. Projects pinned to editions before 2026-10-29 retain the two-column default.

Keep package names predictable​

New plugin installations use the product name as their local alias: cloudposse/terragrunt becomes terragrunt. Existing declarations keep their aliases, and a collision requires an explicit --as value.

Package identity stays separate from source repository and OCI release location. A plugin can move from a monorepo into a standalone repository without changing its consumer identity.

Hooks and extra arguments run under Atmos​

Units that rely on before_hook, after_hook, error_hook, or extra_arguments no longer need to stay on the Terragrunt executable. The plugin evaluates them, and Atmos runs them with the same identity, environment, and toolchain as the Terraform command, so a tool pinned in dependencies.tools is available to a hook even when it is not on your PATH. A hook scoped to plan does not run for apply, and the implicit init matches hooks for init rather than for the command you requested.

Apply the plan you reviewed​

After atmos terraform plan, atmos terraform apply --from-plan applies that exact plan. Atmos rejects the apply if the plan file, the unit's configuration, or the working directory changed in between.

The same flow works across runners, which is how Atmos Pro plans on one runner and applies on another. atmos terraform planfile upload publishes the plan together with its record. On the next runner, atmos terraform planfile download and atmos terraform apply --from-plan re-provision the working directory from the checkout, verify it against the reviewed plan, and apply exactly that plan.

The settings Terragrunt users already rely on​

terraform_binary, errors retry and ignore policies, exclude, feature flags, iam_role and web identity tokens, remote_state encryption, tfr:// registry sources, and the read-config and init-from-module hook lifecycles all run natively. Atmos assumes IAM roles in process on top of the identity you already use, applies retry and ignore policies around each Terraform step, and names every unit an exclude block skips. Functions such as get_aws_account_id() use the same identity as the rest of the run.

Atmos Pro and executable mode​

Units are ordinary Terraform components to Atmos Pro: atmos describe affected --upload and atmos list instances --upload report them, and you can plan and apply one unit at a time. Teams that want to keep Terragrunt itself as the engine can set mode: executable, and Atmos still orders the units and supplies authentication, the toolchain, and the environment for each terragrunt run.

Compatibility is explicit​

Native mode evaluates HCL through Terragrunt Go modules and executes through Atmos. It does not call the Terragrunt executable or silently fall back to it. Unsupported behavior produces an error before infrastructure execution, and the error names the unit, the file, and the setting.

The package remains experimental. Local fixture results do not establish a compatibility percentage, and real cloud provisioning needs its own acceptance evidence.

See the Terragrunt migration guide, plugin usage, and instance listing.