Skip to main content

Migrating from Terragrunt

Terragrunt and Atmos solve similar problems—managing Terraform at scale with DRY configurations. If you're coming from Terragrunt, this guide will help you understand the differences and migrate your infrastructure.

Key Differences at a Glance​

ConceptTerragruntAtmos
Configuration FormatHCL (terragrunt.hcl)YAML (.yaml)
Reuse Mechanisminclude {} blocksimport: with deep merge
Dependenciesdependency blocksdependencies.components for ordering and !terraform.output for values
Variable Passinginputs = {}vars: with inheritance
Localslocals {}locals
Module Sourceterraform { source = "..." }source: for JIT provisioning or vendor.yaml for vendoring
CLIterragrunt plan/applyatmos terraform plan/apply
Hooksbefore_hook, after_hook, error_hookhooks
State Backendremote_state with backend creationCentralized backend config with provision.backend
EnvironmentsDirectory structureStack files (YAML)
UnitsDirectory with terragrunt.hclComponent instance in a stack
StacksCollection of units (terragrunt.stack.hcl)Stack file (e.g., prod.yaml)

Additional Atmos Capabilities​

Atmos also provides the following capabilities. Compare their behavior with your existing tools and workflows when planning a migration:

FeatureDescription
Native AuthenticationBuilt-in multi-cloud auth with SAML, SSO, OIDC, and GitHub Actions. No separate tools needed—atmos auth login handles it all.
VendoringPull and version external modules locally with atmos vendor pull. Customize vendored code while tracking upstream.
Custom CommandsDefine your own CLI commands in YAML. No scripting needed—integrate team-specific workflows directly into Atmos.
WorkflowsOrchestrate multi-step operations across components and stacks. Chain commands, add conditions, run in parallel.
Terraform Shellatmos terraform shell vpc -s prod drops you into a configured shell for native Terraform debugging. All vars and backend pre-configured.
Affected Detectionatmos describe affected analyzes Git changes to find impacted components—purpose-built for CI/CD.
Component ValidationJSON Schema and OPA policy validation for stack configurations before deployment.
Stack Describeatmos describe component shows the fully-resolved configuration for any component in any stack.
Configuration Provenanceatmos describe component --provenance traces where every value came from across the import hierarchy.

Directory Structure Comparison​

Terragrunt uses HCL syntax for configuration, which might feel familiar if you're accustomed to Terraform—but it can also be confusing since it's not actually Terraform code. You're writing HCL that looks like Terraform but behaves differently, with Terragrunt-specific functions like find_in_parent_folders() and dependency blocks that don't exist in Terraform.

infrastructure/
├── terragrunt.hcl # Root config (HCL, not Terraform)
├── _envcommon/
│ ├── vpc.hcl # Shared config (HCL, not Terraform)
│ └── eks.hcl
├── prod/
│ ├── us-east-1/
│ │ ├── vpc/
│ │ │ └── terragrunt.hcl # More HCL config
│ │ └── eks/
│ │ └── terragrunt.hcl
│ └── terragrunt.hcl
└── dev/
└── us-east-1/
├── vpc/
│ └── terragrunt.hcl
└── eks/
└── terragrunt.hcl

Characteristics:

  • HCL config files scattered across directories
  • Environment structure baked into folder hierarchy
  • Each component needs its own terragrunt.hcl
  • Easy to confuse Terragrunt HCL with actual Terraform code

Key difference: Atmos cleanly separates components (native Terraform code) from stacks (YAML configuration). With Terragrunt, HCL configuration files are scattered throughout your directory structure alongside—and sometimes confused with—actual Terraform code.

Configuration Lives in YAML, Not the Filesystem

Atmos makes stack configuration explicit through YAML files and imports. Paths still locate components and imports, and stack filenames provide a fallback name when no explicit name or naming template is configured. See Stack Names. This means:

  • You can query any component's fully-resolved configuration with atmos describe component
  • You can trace where any value came from with atmos describe component --provenance
  • You can output configuration as JSON/YAML for tooling integration
  • You can organize stack directories for your team while defining configuration reuse through explicit imports

Terragrunt also offers path-aware functions such as path_relative_to_include() and find_in_parent_folders(). When translating those expressions, preserve the resulting backend keys and other values rather than assuming a new directory layout will produce the same configuration.

Concept Mapping​

If you're familiar with Terragrunt, the concepts below will help you translate what you already know into Atmos equivalents. Each section shows a side-by-side comparison so you can see exactly how Terragrunt patterns map to Atmos.

Include → Import​

Terragrunt uses include blocks with Terragrunt-specific functions like find_in_parent_folders() to locate and merge parent configurations. You must specify whether to expose included values, and the path resolution can be complex with nested directory structures.

terragrunt.hcl
include "root" {
path = find_in_parent_folders()
}

include "envcommon" {
path = "${dirname(find_in_parent_folders())}/_envcommon/vpc.hcl"
expose = true
}

Dependency → Remote State​

Terragrunt uses dependency blocks to reference outputs from other modules. You specify a relative path to the dependent module's directory, and Terragrunt reads its state file to extract outputs. This creates implicit ordering and requires the dependency to be applied first. Since it's all HCL, the line between "configuration" and "business logic" can blur—you're writing code that looks like Terraform but isn't.

eks/terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
}

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

mock_outputs → Component Mocks​

Terragrunt lets a dependency block declare mock_outputs so plan and validate still work before the dependency has been applied. mock_outputs_allowed_terraform_commands restricts which commands are allowed to use the mock values, so a real apply never runs against fake data by accident.

eks/terragrunt.hcl
dependency "vpc" {
config_path = "../vpc"
mock_outputs = {
vpc_id = "vpc-mock1234"
private_subnet_ids = ["subnet-a", "subnet-b"]
}
mock_outputs_allowed_terraform_commands = ["validate", "plan"]
}

Inputs → Vars​

Terragrunt passes variables to Terraform using the inputs block. These values become -var arguments when Terraform runs. The inputs block uses HCL syntax with equals signs and curly braces.

vpc/terragrunt.hcl
inputs = {
cidr_block = "10.0.0.0/16"
enable_dns_hostnames = true
environment = "production"
}

Terraform Source → Source Provisioning or Vendoring​

Terragrunt specifies the Terraform module source directly in each terragrunt.hcl file. The source is fetched at runtime, and you manage versions by changing the ref parameter. Shared configuration can supply the source reference through includes.

vpc/terragrunt.hcl
terraform {
source = "git::https://github.com/terraform-aws-modules/terraform-aws-vpc.git?ref=v5.0.0"
}

Generate Blocks → Code Generation​

Terragrunt uses generate blocks to create arbitrary files before Terraform runs. You write file contents as heredoc strings within HCL, specifying the path and overwrite behavior. This gives you full templating power, but that flexibility comes with complexity—you're essentially writing a code generator in HCL.

terragrunt.hcl
generate "provider" {
path = "provider.tf"
if_exists = "overwrite"
contents = <<EOF
provider "aws" {
region = "${local.aws_region}"
}
EOF
}

Hooks → Hooks​

Terragrunt supports hooks inside terragrunt.hcl using before_hook, after_hook, and error_hook blocks. Hooks run commands around selected Terraform operations.

terragrunt.hcl
terraform {
before_hook "fmt" {
commands = ["plan", "apply"]
execute = ["terraform", "fmt", "-check"]
}

after_hook "notify" {
commands = ["apply"]
execute = ["./scripts/notify.sh"]
}
}

Remote State Configuration​

Terragrunt configures remote state in the root terragrunt.hcl using a remote_state block and can create the configured backend resources when they do not exist. The path_relative_to_include() function dynamically generates state keys based on directory structure. Child configurations inherit this through include blocks.

terragrunt.hcl (root)
remote_state {
backend = "s3"
config = {
bucket = "terraform-state"
region = "us-east-1"
key = "${path_relative_to_include()}/terraform.tfstate"
}
}

Locals → Locals​

Terragrunt uses locals blocks for computed values and string interpolation. You define local variables with HCL syntax and reference them using local.variable_name. These are scoped to the current file and its includes.

terragrunt.hcl
locals {
account_id = "123456789012"
region = "us-east-1"
cluster_name = "${local.account_id}-${local.region}-eks"
}

inputs = {
cluster_name = local.cluster_name
}

run_cmd → YAML Functions​

Terragrunt's run_cmd() function executes shell commands and captures their output. You pass the command and arguments as separate strings, and the result can be assigned to a local variable.

terragrunt.hcl
locals {
account_id = run_cmd("aws", "sts", "get-caller-identity", "--query", "Account", "--output", "text")
}

extra_arguments → Component Settings​

Terragrunt's extra_arguments block lets you append additional CLI arguments to Terraform commands. You specify which commands (plan, apply, etc.) receive the extra arguments and what those arguments should be.

terragrunt.hcl
terraform {
extra_arguments "common_vars" {
commands = ["plan", "apply"]
arguments = ["-var-file=common.tfvars"]
}
}

Units and Stacks​

Terragrunt recently introduced formal Units and Stacks concepts (GA in v0.78.0, May 2025). Here's how they map to Atmos:

In Terragrunt terminology:

  • Unit: A directory containing a terragrunt.hcl file—a single instance of infrastructure with its own state. Each unit represents one deployment of a Terraform module.

  • Stack: A collection of units that can be managed together. Terragrunt supports both implicit stacks (directory-based) and explicit stacks (defined in terragrunt.stack.hcl files).

terragrunt.stack.hcl
# Explicit stack definition
unit "vpc" {
source = "../units/vpc"
values = {
environment = "prod"
cidr_block = "10.0.0.0/16"
}
}

unit "eks" {
source = "../units/eks"
values = {
environment = "prod"
cluster_name = "main"
}
}
Terragrunt ConceptAtmos EquivalentNotes
Unit (terragrunt.hcl)Component instance in components.terraformSame concept: single deployable with own state
Implicit Stack (directory)Stack fileAtmos uses explicit YAML files, not directories
Explicit Stack (terragrunt.stack.hcl)Stack file (.yaml)Both define collections of units/components
unit {} blockComponent entry under components.terraformAtmos uses YAML; Terragrunt uses HCL
values = {}vars:Both pass variables to the underlying module
Atmos Was Stack-First From the Start

Terragrunt evolved from a directory-per-unit model and later added explicit stack support. Atmos was designed stack-first—every deployment is defined in a stack file, making the relationship between components explicit and queryable from day one.

Function Mapping​

Terragrunt exposes HCL functions for path discovery, environment lookup, command execution, dependency wiring, and file reading. Atmos supports the same workflows, but many of them move from inline functions to explicit YAML configuration, YAML functions, or stack templating. The table below audits the functions in the Terragrunt function reference.

Path and Directory Functions​

Terragrunt FunctionAtmos EquivalentNotes
OpenTofu/Terraform built-insGo templates with Sprig/Gomplate, or YAML functionsAtmos does not expose Terraform's HCL function set directly. Use YAML functions for data access and templates for string, path, list, map, and semver helpers.
find_in_parent_folders()import: or !includeAtmos uses explicit imports and includes instead of walking parent directories.
path_relative_to_include()Explicit backend.key or templatesAtmos does not derive state keys from include paths. Configure state keys directly from stack/component context.
path_relative_from_include()Not usually neededAtmos imports, component base paths, and source provisioning use configured paths instead of include-relative module paths.
get_repo_root()!repo-rootYAML function returns repo root path
get_path_from_repo_root()No direct scalar functionUsually not needed; use configured stack/component paths, or combine !repo-root with templates when an absolute repo path is required.
get_path_to_repo_root()No direct scalar functionUse !repo-root for the absolute root. Atmos generally avoids relative path hops back to repo root.
get_terragrunt_dir()Manifest-relative paths, component base paths./ and ../ in !include resolve relative to the manifest file. Component paths come from components.terraform.base_path plus the component name.
get_working_dir()!cwdYAML function returns the directory where Atmos is executed.
get_parent_terragrunt_dir()import:Explicit imports replace parent-config discovery.
get_original_terragrunt_dir()!cwdAtmos is not directory-per-unit; use the command working directory when you need the invocation path.

Environment and Platform Functions​

Terragrunt FunctionAtmos EquivalentNotes
get_env("VAR", "default")!env VAR, defaultYAML function for environment variables
get_platform()No native equivalentSprig and Gomplate can read environment variables, but do not expose Go runtime.GOOS/runtime.GOARCH. Use !exec if needed.
get_aws_account_id()!aws.account_idYAML function backed by AWS STS
get_aws_account_alias()!execNo dedicated YAML function; run an AWS CLI command
get_aws_caller_identity_arn()!aws.caller_identity_arnYAML function backed by AWS STS
get_aws_caller_identity_user_id()!aws.caller_identity_user_idYAML function backed by AWS STS

Terraform Command Helpers​

Terragrunt FunctionAtmos EquivalentNotes
get_terraform_commands_that_need_vars()Built inAtmos generates and passes component varfiles automatically for Terraform commands that need them.
get_terraform_commands_that_need_input()settings.terraform.argsConfigure -input=false or related flags explicitly.
get_terraform_commands_that_need_locking()settings.terraform.argsConfigure lock flags explicitly when needed.
get_terraform_commands_that_need_parallelism()settings.terraform.argsConfigure -parallelism explicitly when needed.
get_terraform_command()No direct functionAtmos receives the Terraform subcommand from atmos terraform <command>. Use hooks or custom commands when behavior must vary by operation.
get_terraform_cli_args()settings.terraform.args, env, or pass-through argsUse component settings for durable args, TF_CLI_ARGS* env vars for Terraform-native behavior, or -- for one-off pass-through args.
get_default_retryable_errors()retry.conditionsAtmos has component retry configuration instead of a helper returning default regexes.

Command Execution​

Terragrunt FunctionAtmos EquivalentNotes
run_cmd("cmd", "arg1", ...)!exec!exec cmd arg1 executes shell commands in YAML functions.
run_cmd("--terragrunt-quiet", ...)No direct flagUse Atmos secret masking and avoid printing sensitive command output.
run_cmd("--terragrunt-global-cache", ...)No direct flagAtmos does not expose a command-output cache control for !exec.
run_cmd("--terragrunt-no-cache", ...)Default !exec behavior!exec runs when functions are processed; there is no Terragrunt-style cache toggle.

Configuration Reading​

Terragrunt FunctionAtmos EquivalentNotes
deep_merge()Stack imports and inheritanceAtmos deep-merges imported YAML configuration by design. Use Sprig/Gomplate template merge helpers only when inline expression merging is unavoidable.
read_terragrunt_config()import:Import reusable Atmos stack YAML instead of reading HCL into a local value.
read_tfvars_file()!include!include can load .tfvars and .tfvars.json into YAML values.
sops_decrypt_file()!exec or storesNo native SOPS YAML function. Use !exec sops ... for local encrypted files, or move secrets to a configured store and read with !store/!store.get.
get_terragrunt_source_cli_flag()No direct equivalentAtmos source provisioning uses source.uri and source.version in stack config. Use !env for local override patterns if you need them.

State and Outputs​

Terragrunt FunctionAtmos EquivalentNotes
dependency.X.outputs.Y!terraform.output!terraform.output component.output_name
N/A!terraform.stateRead arbitrary state attributes

Change Tracking and Constraints​

Terragrunt FunctionAtmos EquivalentNotes
mark_as_read()dependencies.filesDeclare explicit file dependencies so describe affected/list affected can track changes.
mark_glob_as_read()dependencies.foldersDeclare folder dependencies instead of imperatively marking glob reads.
constraint_check()Sprig semverCompare or tool dependency constraintsUse semverCompare in templates for conditional config, or Atmos toolchain dependency constraints for tool versions.
YAML Functions vs Templates

Atmos offers two ways to access dynamic values:

  • YAML Functions (!exec, !env, !terraform.output) — Preferred. Validated at parse time, readable, works with YAML tooling.
  • Go Templates ({{ env "VAR" }}, {{ semverCompare ">=2.0.0" .vars.version }}) — Escape hatch. Use when YAML functions don't cover your use case.

See YAML Functions for the complete reference.

CLI Command Comparison​

Terragrunt commands are directory-based—you cd into a component's directory and run commands there. For multi-component operations, run-all traverses the directory tree and executes in dependency order.

# Plan a single component
cd prod/us-east-1/vpc
terragrunt plan

# Apply a single component
cd prod/us-east-1/vpc
terragrunt apply

# Plan all components
terragrunt run-all plan

# Apply all components
terragrunt run-all apply

# Show outputs
terragrunt output

Adopt Terragrunt Units Incrementally (Experimental)​

You do not have to convert every terragrunt.hcl before Atmos is useful. An experimental plugin reads your existing Terragrunt HCL and presents each unit as an Atmos Terraform component, so you can list, plan, apply, and target them with Atmos while you migrate the rest. The plugin evaluates the HCL with Terragrunt's Go modules. Atmos runs every command, so Atmos authentication, the toolchain, and dependencies.tools apply. The Terragrunt executable is never used.

Development build

The plugin is not yet published. Until it is, build it from the Atmos repository and point plugins.packages at its directory with path. See the plugin README for the build commands.

atmos.yaml
components:
terraform:
base_path: components/terraform
command: tofu
terragrunt:
enabled: true
mode: native
discovery:
enabled: true
included_paths: [live/**]
plugins:
packages:
terragrunt:
path: /absolute/path/to/atmos/plugins/terragrunt

Then work with the units as components:

atmos list instances
atmos terraform plan --all
atmos terraform apply --all
atmos describe affected --base origin/main

Units found this way get their names from where they live on disk, so no stack YAML is needed. To place a unit in a stack you already have, import it instead (see Import units into a stack).

Component and stack names​

Discovery derives names from paths relative to the Atmos base path. Stack name templates and patterns (name_template, name_pattern) do not apply to discovered units, and atmos list instances is the authoritative list of names.

UnitComponentStack
live/dev/vpc/terragrunt.hclvpc (the unit directory name)live/dev (the directory above the unit)
live/vpc/terragrunt.hclvpclive
live/terragrunt.hcllivedefault
terragrunt.hcl in the base pathrootdefault
live/terragrunt.stack.hcl generating dev/appdev/app (the unit's path inside the stack)live (the directory of the stack file)

Two units with the same name in the same stack are an error that names both files. Directory names with spaces, dots, or Unicode work as they are.

A unit that is imported into a stack keeps its component name, but its stack is the stack that imports it. A YAML component with the same name is not a second definition: it is an override of the unit.

Import units into a stack​

Import a unit, a directory of units, or a terragrunt.stack.hcl to make the units components of the stack that imports them, next to the components defined in that stack's YAML:

stacks/dev.yaml
import:
- terragrunt://live/dev
vars:
stage: dev
atmos list instances --stack dev
atmos terraform plan vpc -s dev

The path after terragrunt:// is relative to the Atmos base path, not to the stack file. It must be a project-relative file named terragrunt.hcl or terragrunt.stack.hcl, or a directory. Globs, .., absolute paths, ?ref=, and # fragments are rejected. A path may not contain any of the characters \, ?, #, *, [, or {, even in a literal directory name, so rename such a directory or import its parent. The context, skip_if_missing, ttl, and nested_imports options are not supported for these imports.

  • An import never creates a stack. The units become components of the importing stack. Only units found by automatic discovery and not imported anywhere get a stack name from their directory. A unit that is imported is not also listed under its discovered stack.
  • Mixins and catalogs work like YAML imports. An import inside a mixin applies to every stack that imports the mixin, and the same unit can be imported by several stacks, each getting its own component. All of them share the unit's backend configuration, and therefore its state. Import a unit into more than one stack only when sharing is intended, or vary the backend key per stack in HCL, for example with get_env().
  • Imports ignore discovery.included_paths and discovery.excluded_paths. An import is an explicit request, so a unit excluded from automatic discovery can still be imported. Discovery does not need to be enabled for imports to work.
  • A unit name is unique within a stack. If an import brings in two different units that share a component name in the same stack, Atmos fails and names both files. A YAML component with the name of an imported unit is not a conflict; it deep-merges over the unit (see Override a unit from stack configuration).
  • An import must select a unit. An import that matches no unit with a terraform source is an error, not an empty result.
  • Dependencies stay inside the stack. A unit that depends on another unit gets a dependency on the component of the same name in the same stack. Import the dependency into that stack too, in the same import or a separate one; a bulk run (--all) fails with a missing-dependency error naming both components otherwise.

Override a unit from stack configuration​

An imported unit is the base of a component in the importing stack. Stack configuration for the same component name deep-merges over it with the usual rules, so you can change any setting of a unit without editing its HCL. The YAML can sit in the importing manifest or in any other import, before or after the unit's import.

stacks/dev.yaml
import:
- terragrunt://live/dev
components:
terraform:
vpc:
metadata:
inherits: [defaults]
vars:
name: dev-vpc # replaces the HCL input
tags:
team: platform # merged into the HCL tags map
env:
TF_LOG: ERROR # wins over env_vars from the unit's extra_arguments
settings:
owner: platform

Precedence, from lowest to highest:

  1. The unit's own evaluation. Inputs, extra_arguments environment, and hooks come from the HCL, evaluated again for every operation because inputs can depend on dependency outputs.
  2. Sections of abstract components named in metadata.inherits.
  3. Imports, in order, then the importing manifest, then the component's own block, then overrides.

Per section:

SectionBehavior
varsMerged over the unit's inputs when the command runs: maps merge key by key, scalars and lists are replaced (lists follow settings.list_merge_strategy). Set a variable to null to remove a unit input. !unset removes a value that came from stack layers (a catalog or base component), and then the unit's own input applies. Stack-wide vars reach the unit like they reach every component.
envWins over the environment of the unit's extra_arguments. It is also visible to get_env() while the HCL is evaluated.
settings, metadata (enabled, locked, terraform_workspace, inherits), hooks, providers, auth, dependenciesOrdinary stack configuration. terraform_workspace selects the workspace the unit runs in. A dependencies.tools entry at the stack, terraform, or component level pins the tool for every command, run_cmd, and hook of the unit.
commandSelects the executable, for example a pinned tofu. It must be the same engine the unit was discovered with. Switching between OpenTofu and Terraform is an error.
backend, backend_typeNot overridable. The unit's remote_state decides where its state lives, and dependency reads and saved plans rely on the same location. A component that sets backend_type to anything but the default, or backend options of its own, fails with an error that points to remote_state. A backend set in a global section is ignored for units.
metadata.component, source.uriNot overridable. The module comes from the unit's terraform { source }. Other source settings such as version merge normally.

atmos describe component shows the stack layer: the unit's HCL inputs are evaluated only when a command runs, so they are not listed. The merged variables are written to the generated var file in the component's working directory.

Units cannot carry metadata.labels or metadata.tags today.

Discovery paths​

included_paths and excluded_paths use the same pattern language. Patterns are doublestar globs relative to the Atmos base path, written with forward slashes on every platform. A pattern selects the path it matches and everything below it, so a directory name needs no /**. A leading ./ and a trailing / are ignored. Absolute patterns, .., and backslashes are rejected.

PatternSelects
live, live/, ./live, live/**every unit below live
live/dev/*every unit below any direct child of live/dev (a unit directory, or a folder of them)
live/dev/vpcthe unit in that directory
live/dev/vpc/terragrunt.hclexactly that file
**/vpc, live/*/vpcevery unit directory named vpc
., ./**, **everything (the default when included_paths is not set)

A pattern is compared in the case the filesystem reports, so Live and live can behave differently between macOS and Linux. Discovery skips hidden directories, node_modules, .terragrunt-cache, and .terragrunt-stack.

Discovery reports what it cannot use instead of silently returning less:

  • An included_paths pattern that selects no terragrunt.hcl or terragrunt.stack.hcl produces a warning that names the pattern.
  • A terragrunt.hcl without a terraform { source } block (and without Terraform files beside it) is treated as shared configuration, such as an include target, and a warning names it.
  • A dependency on a unit outside the discovery scope fails that unit's commands and names both units. Add the dependency to included_paths or import it.

Atmos follows the same rules as Terragrunt v1.2.1, whose symlink support is an opt-in experiment. Symlinks are best avoided.

  • A symlinked directory is not followed, so units below it are not discovered. A warning names each skipped link. Import the real directory instead, or list the target in included_paths.
  • A symlinked terragrunt.hcl or terragrunt.stack.hcl is a unit at the place the link lives, named from that location, and its content is read through the link. find_in_parent_folders() and relative paths resolve from the link's location.
  • A symlink inside a watched module or the unit's configuration that resolves outside the project root is rejected before anything runs. The error names the file and where it leads. Replace the link with a copy, or point it inside the project.

Provenance and inspection​

atmos describe component for a unit shows the unit's evaluated source and dependencies. It does not point at unrelated YAML: a discovered unit has no stack manifest, and an imported unit is attributed to the manifest that imported it. Per-input provenance is not available yet, and vars and backend show the stack's values until the unit is prepared for a command.

What Atmos runs for you​

  • dependency and dependencies blocks become ordering and output edges, and dependency outputs are refreshed in the same apply.
  • extra_arguments and before_hook, after_hook, and error_hook blocks run with the same environment, identity, and toolchain as the Terraform command. A hook that lists plan does not run for apply. The implicit init matches hooks for init, not for the requested command.
  • Dry runs do not evaluate Terragrunt configuration. Their command previews may omit dynamically computed extra arguments, required var files, and environment variables. Real runs include these values.
  • Generated files and backend configuration keep their Terragrunt identity, so existing state stays addressable.
  • atmos terraform plan followed by atmos terraform apply --from-plan applies exactly the reviewed plan. Atmos rejects the apply if the plan file, the unit's configuration, or the working directory changed after the plan. The original working directory must still exist. Commands such as output, validate, and init leave the saved plan in place, and a successful apply removes it, so applying the same plan twice reports that no saved plan exists.
  • Remote Git and HTTPS module sources are fetched by Atmos. A source that follows a branch (?ref=main) is fetched once and reused, with a notice; run atmos terraform source pull <component> -s <stack> --force to refresh it. A local module is copied again only when its files change.
  • Removing a generate block removes the file it generated, and a generate block that writes a backend block replaces the backend file Atmos would write. Atmos copies the .terraform.lock.hcl beside terragrunt.hcl into the working directory but does not copy changes back; copy it yourself after init -upgrade.
  • Tool versions come from .tool-versions and from dependencies.tools, which Atmos reads from stack manifests and component sections, not atmos.yaml. An imported unit takes dependencies.tools from the importing stack's configuration, and those pins take precedence over .tool-versions. A discovered unit has no stack manifest, so it takes its pins from .tool-versions.
  • A unit without a stable remote_state path keeps local state under .terragrunt-cache, which moves with the checkout path and disappears when the cache is deleted. Atmos keeps that location so existing state stays addressable, and warns when it applies.
  • !terraform.output and !terraform.state can read a Terragrunt unit like any other component.

Executables, errors, exclusions, and features​

  • terraform_binary in a unit selects the executable for that unit. Atmos resolves a name such as tofu through the toolchain and uses a path as given, resolved from the unit directory when relative. A stack-level command overrides it, and it overrides components.terraform.command. The executable must be Terraform or OpenTofu and cannot switch the unit between the two engines.
  • A unit's errors block applies to its init and main Terraform commands and to fetching its source. Ignore policies are checked before retry policies, and the first matching policy decides. max_attempts includes the first attempt. An ignored failure succeeds and writes its signals to error-signals.json in the module directory. When both settings.retry and an errors retry policy apply, settings.retry retries first and the policy retries what is left, so a failure can be attempted more often than either setting alone.
  • A unit whose exclude block lists the running command (all and all_except_output included) is skipped in --all, --affected, and --stack runs and reported by name. exclude_dependencies = true also skips its direct dependencies. With no_run unset, a direct run is skipped only for an exact action. no_run = true also honors all and all_except_output, and no_run = false never skips a direct run.
  • Set components.terraform.terragrunt.features to override feature blocks for every unit. TG_FEATURE=name=value,name2=value2 overrides those values per name. An override that no unit declares prints a warning naming it.
  • terragrunt-read-config (also read-config) after-hooks run after every command prepares the unit, in the unit directory. init-from-module hooks run around fetching the module source, only when it is fetched or refreshed.
  • A hook that executes tflint runs tflint --init and then tflint with the unit's .tflint.hcl, inputs, and variable files. TF_VAR_ variables from env_vars reach TFLint through the environment, so terraform.tfvars takes precedence over them, as it does for Terraform. Install tflint through the toolchain or PATH.

Identity, state encryption, and registry sources​

  • iam_role, iam_assume_role_duration, iam_assume_role_session_name, and iam_web_identity_token are supported. Atmos assumes the role in process through STS, on top of the credentials in use: the default Atmos identity or the ambient credential chain. It downloads an s3:: source with the temporary session, exports the session to Terraform, hooks, and workspace commands, and never writes it to a file or a saved plan. iam_web_identity_token is a token or the path of a file that contains one. Use a file if you apply saved plans, because a literal token is never stored with a plan.
  • If you select an identity with --identity or ATMOS_IDENTITY, that identity decides who the component runs as, and iam_role is not assumed. TG_IAM_ASSUME_ROLE, TG_IAM_ASSUME_ROLE_DURATION, TG_IAM_ASSUME_ROLE_SESSION_NAME, and TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN override the unit's settings, as they do in Terragrunt. run_cmd and get_env evaluate with the invocation's own environment, before the role is assumed, as in Terragrunt.
  • remote_state.encryption is written to the file that remote_state.generate creates, as an OpenTofu encryption block, so it requires OpenTofu. Any OpenTofu key provider works, for example pbkdf2, aws_kms, or gcp_kms. Without generate it has no effect, as in Terragrunt, and Atmos warns. remote_state.disable_init is accepted: Terragrunt uses it only to skip creating backend resources, Atmos never creates them, and OpenTofu initializes the backend as usual.
  • tfr:// module sources are resolved when a unit is prepared, using the Terraform module registry protocol. ?version= pins an exact version, the terraform { version } constraint selects among published versions, and with neither the latest stable release is used. Private registries authenticate with TF_TOKEN_<host>, a credentials block in the CLI configuration, or TG_TF_REGISTRY_TOKEN. A //subdir selects a directory inside the module.

What it does not support yet​

What it does not support yet​

Unsupported settings fail before any infrastructure command runs, with an error that names the unit, the file with line and column, and the setting. With automatic discovery, a broken unit does not affect other units or YAML components: it stays listed, and only commands that target it fail. An explicit import is stricter: it fails when any unit it selects reports an error, so that import contributes no units until the error is fixed. apply, plan, and destroy with --all validate every selected unit first and report "no infrastructure command was run". Evaluation errors can contain secrets, so Atmos shows the location and a hint but not the evaluator's text; run with ATMOS_LOGS_LEVEL=Debug to log the full message with secrets masked. Atmos does not fall back to the Terragrunt executable. Currently rejected:

  • Inline modules without terraform.source.
  • Output dependencies in a non-default workspace during discovery.
  • Stack-level overrides of a unit's backend, backend_type, metadata.component, or source.uri, because they would change state identity. Edit the unit's remote_state instead.

Terragrunt's built-in default retry list for transient errors, the --no-auto-retry flag, and errors handling around read-config hooks are not implemented; use settings.retry or an errors block. Discovery runs without side effects, so a unit whose locals call run_cmd cannot be discovered.

Migration Steps​

Step 1: Convert terragrunt.hcl to Stack YAML​

Each Terragrunt directory has its own terragrunt.hcl with include paths, source references, and inputs. The configuration is scattered across the directory tree with implicit relationships based on folder hierarchy.

prod/us-east-1/vpc/terragrunt.hcl
include "root" {
path = find_in_parent_folders()
}

terraform {
source = "../../../../modules/vpc"
}

inputs = {
cidr_block = "10.0.0.0/16"
environment = "prod"
region = "us-east-1"
}

Step 2: Move Terraform Root Modules​

What's a Root Module?

In Terraform, a root module is the top-level directory where you run terraform plan and terraform apply. It has its own state file. Child modules are reusable building blocks called from root modules—they don't have their own state.

In Atmos terminology, root modules are called components. Each component is a self-contained Terraform configuration that gets deployed independently with its own state.

Terragrunt typically references root modules from a modules/ directory (or pulls from remote sources). These are standard Terraform root modules that work independently.

modules/
├── vpc/ # Root module (has state)
│ ├── main.tf
│ └── variables.tf
└── eks/ # Root module (has state)
├── main.tf
└── variables.tf

Step 3: Update Backend Configuration​

Terragrunt manages state backend configuration in the root terragrunt.hcl. The path_relative_to_include() function generates unique state keys based on the directory structure, ensuring each component has its own state file.

terragrunt.hcl (root)
remote_state {
backend = "s3"
config = {
bucket = "terraform-state"
key = "${path_relative_to_include()}/terraform.tfstate"
region = "us-east-1"
}
}

Migration Checklist​

  • Install Atmos CLI (Installation Guide)
  • Create atmos.yaml configuration
  • Point components.terraform.base_path at the existing root modules, or optionally reorganize them
  • Convert terragrunt.hcl files to stack YAML
  • Extract common config to _defaults/
  • Map dependency ordering to dependencies.components and output lookups to !terraform.output or !terraform.state
  • Convert mock_outputs to component mocks and --use-mocks
  • Preserve existing backend state locations and workspace names
  • Test with atmos terraform plan
  • Update CI/CD pipelines
  • Train team on new commands

Stack Naming for Migrations​

Commands that target a component in a particular environment use a stack name, such as atmos terraform plan vpc -s <stack>. Define how Atmos determines these names; commands such as atmos list stacks can list stacks without selecting one.

Stack names and Terraform workspace names are distinct. During migration, use metadata.terraform_workspace to preserve an existing workspace explicitly, even if it does not match the stack name. For new deployments, Atmos can compute workspace names using a consistent convention.

You have two options:

If you have consistent context variables across all your stacks, configure name_template in atmos.yaml to programmatically compute stack names:

atmos.yaml
stacks:
name_template: "{{ .vars.environment }}-{{ .vars.stage }}"

This works well when:

  • You have consistent vars (like environment, stage, tenant) across all stacks
  • You want programmatic, convention-based naming
  • Your Terraform workspaces should follow the same naming pattern

Option 2: Use Explicit name Field (For Inconsistent or Legacy Naming)​

If your infrastructure doesn't follow a strict naming convention, use the name field in each stack manifest to explicitly specify the stack name:

stacks/us-east-1/prod/vpc.yaml
name: "prod-us-east-1-vpc"

import:
- catalog/vpc

components:
terraform:
vpc:
vars:
cidr: "10.0.0.0/16"

This is the right choice when:

  • Your stacks don't have consistent context variables
  • You're migrating infrastructure from multiple sources with different naming conventions
  • Workspace names are ad-hoc or don't follow a pattern you can express as a template

The name field takes precedence over name_template, so you can use both approaches—template for most stacks, explicit names for exceptions.

For complete documentation on stack naming, see Stack Names.

Why Migrate?​

Advantages of Atmos​

  • Clear separation of code and config - YAML for configuration, native Terraform for code. Components (code) and stacks (config) live in different directories—no "Terraform-like but not Terraform" confusion
  • Components are pure Terraform - Your modules work with or without Atmos, no vendor lock-in
  • YAML is universal - Every language and tool can parse it; no HCL knowledge needed for configuration
  • Deep merge semantics - Compose configuration through imports and component inheritance
  • Schema validation - JSON Schema + OPA policies for configuration validation
  • Multi-tool orchestration - Not just Terraform (Helmfile, Packer, etc.)
  • Active development - Regular releases, responsive community

When to Stay with Terragrunt​

  • It's working for you - If your team knows Terragrunt well and has no pain points, there's no reason to change
  • Strong HCL preference - If your team prefers HCL over YAML and wants configuration in the same language as Terraform code
  • Migration cost outweighs the benefit - Compare your current workflows with Atmos equivalents before switching. Atmos supports dynamic file generation, but its templates and configuration need translation; the general-purpose generation feature is experimental.

Get Help​

Migrating a large codebase? We're here to help:

Next Steps​

Now that you understand the migration path: