# 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

| Concept | Terragrunt | Atmos |
|---------|------------|-------|
| **Configuration Format** | HCL (`terragrunt.hcl`) | YAML (`.yaml`) |
| **Reuse Mechanism** | `include {}` blocks | `import:` with deep merge |
| **Dependencies** | `dependency` blocks | [`dependencies.components`](/stacks/dependencies/components) for ordering and [`!terraform.output`](/functions/yaml/terraform.output) for values |
| **Variable Passing** | `inputs = {}` | `vars:` with inheritance |
| **Locals** | `locals {}` | [`locals`](/stacks/locals) |
| **Module Source** | `terraform { source = "..." }` | `source:` for JIT provisioning or `vendor.yaml` for vendoring |
| **CLI** | `terragrunt plan/apply` | `atmos terraform plan/apply` |
| **Hooks** | `before_hook`, `after_hook`, `error_hook` | [`hooks`](/stacks/hooks) |
| **State Backend** | `remote_state` with backend creation | Centralized backend config with [`provision.backend`](/stacks/components/provision/backend) |
| **Environments** | Directory structure | Stack files (YAML) |
| **[Units](https://terragrunt.gruntwork.io/docs/getting-started/terminology/)** | Directory with `terragrunt.hcl` | Component instance in a stack |
| **[Stacks](https://terragrunt.gruntwork.io/docs/features/stacks/)** | Collection 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:

| Feature | Description |
|---------|-------------|
| **[Native Authentication](/cli/commands/auth/usage)** | Built-in multi-cloud auth with SAML, SSO, OIDC, and GitHub Actions. No separate tools needed—`atmos auth login` handles it all. |
| **[Vendoring](/cli/commands/vendor/pull)** | Pull and version external modules locally with `atmos vendor pull`. Customize vendored code while tracking upstream. |
| **[Custom Commands](/cli/configuration/commands)** | Define your own CLI commands in YAML. No scripting needed—integrate team-specific workflows directly into Atmos. |
| **[Workflows](/workflows)** | Orchestrate multi-step operations across components and stacks. Chain commands, add conditions, run in parallel. |
| **[Terraform Shell](/cli/commands/terraform/shell)** | `atmos terraform shell vpc -s prod` drops you into a configured shell for native Terraform debugging. All vars and backend pre-configured. |
| **[Affected Detection](/cli/commands/describe/affected)** | `atmos describe affected` analyzes Git changes to find impacted components—purpose-built for CI/CD. |
| **[Component Validation](/cli/commands/validate/stacks)** | JSON Schema and OPA policy validation for stack configurations before deployment. |
| **[Stack Describe](/cli/commands/describe/component)** | `atmos describe component` shows the fully-resolved configuration for any component in any stack. |
| **[Configuration Provenance](/cli/commands/describe/component)** | `atmos describe component --provenance` traces where every value came from across the import hierarchy. |

## Directory Structure Comparison

### Terragrunt

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.

```plaintext
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

### Atmos

With Atmos, the distinction is clear: **YAML for configuration, Terraform for code**. Your stack configurations are pure YAML—no Terraform domain knowledge required—while all components are native Terraform modules, unchanged and portable.

```plaintext
infrastructure/
├── atmos.yaml                     # Atmos config (YAML)
├── components/
│   └── terraform/
│       ├── vpc/
│       │   ├── main.tf            # Native Terraform
│       │   └── variables.tf       # Native Terraform
│       └── eks/
│           ├── main.tf
│           └── variables.tf
└── stacks/
    ├── _defaults/
    │   ├── globals.yaml           # Shared defaults
    │   └── vpc-defaults.yaml
    ├── dev/
    │   ├── us-east-1.yaml         # Dev in us-east-1
    │   └── us-west-2.yaml         # Dev in us-west-2
    ├── staging/
    │   └── us-east-1.yaml         # Staging in us-east-1
    └── prod/
        ├── us-east-1.yaml         # Prod in us-east-1
        └── us-west-2.yaml         # Prod in us-west-2
```

:::tip Flexible Design Patterns
Atmos supports many [design patterns](/design-patterns) for organizing your stacks—from simple flat structures for startups to enterprise-scale patterns with multi-tenant, multi-region hierarchies. Choose the pattern that fits your needs and evolve as you grow.
:::

**Characteristics:**

- Code (Terraform) and config (YAML) cleanly separated
- One stack file per environment—no per-component config files
- Components are native Terraform—work with or without Atmos
- Anyone can read YAML; no HCL knowledge needed

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

:::info 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](/stacks/name). 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](/stacks/imports)

### Terragrunt

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.

**File:** `terragrunt.hcl`

```hcl
include "root" {
  path = find_in_parent_folders()
}

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

### Atmos

Atmos uses simple `import` statements—just list the files you want to include. All imports are automatically deep-merged in order, with later values overriding earlier ones. No special functions or expose flags needed.

**File:** `stacks/prod.yaml`

```yaml
import:
  - _defaults/globals
  - _defaults/vpc-defaults
```

### Dependency → [Remote State](/stacks/remote-state)

### Terragrunt

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.

**File:** `eks/terragrunt.hcl`

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

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

### Atmos

Atmos separates dependency ordering from value lookup. Use [`dependencies.components`](/stacks/dependencies/components) to declare explicit component ordering, and use [`!terraform.output`](/functions/yaml/terraform.output) to read outputs from another component's remote state.

Because Atmos uses YAML for configuration and keeps Terraform for code, there's a clear separation: **stacks are configuration, components are code**. Your configuration (what to deploy, with what values) stays in YAML. Your business logic (how resources are created) stays in Terraform. This separation makes it easier to reason about your infrastructure.

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    eks:
      dependencies:
        components:
          - name: vpc
      vars:
        vpc_id: !terraform.output vpc.vpc_id
        subnet_ids: !terraform.output vpc.private_subnet_ids
```

### mock\_outputs → Component Mocks

### Terragrunt

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.

**File:** `eks/terragrunt.hcl`

```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"]
}
```

### Atmos

Atmos has a close equivalent: a component declares literal output values under `mocks`, and `atmos terraform plan` and `atmos describe component` use them when you explicitly pass `--use-mocks`. Like Terragrunt's `mock_outputs`, the mocks are fallbacks: `!terraform.state` and `!terraform.output` return the real value when the dependency has been applied, and the `mocks` value only when the dependency has no state or the requested output is missing. Credential, network, and backend errors still fail rather than being replaced by mock values.

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    vpc:
      mocks:
        vpc_id: vpc-mock1234
        private_subnet_ids: [subnet-a, subnet-b]
```

```shell
atmos terraform plan eks -s prod --use-mocks
atmos describe component eks -s prod --use-mocks
```

Only `atmos terraform plan` and `atmos describe component` accept `--use-mocks`. It is rejected on `apply`, `deploy`, and `destroy` before stack resolution even happens, so a mock value can never reach a mutating Terraform operation — a stronger guarantee than opting individual commands in through `mock_outputs_allowed_terraform_commands`.

If you want the previous hermetic behavior, where lookups resolve from `mocks` only and never read state, use `--use-mocks=always` or set `components.terraform.mocks.mode: always`. In `always` mode an undeclared `mocks` entry is a hard error unless the expression supplies a YQ `//` default. In the default `fallback` mode the order is real value, then mock, then YQ `//` default, then the original error. See the provider-free `examples/terraform-component-mocks` example in the Atmos repository for a complete walkthrough.

### Inputs → Vars

### Terragrunt

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.

**File:** `vpc/terragrunt.hcl`

```hcl
inputs = {
  cidr_block           = "10.0.0.0/16"
  enable_dns_hostnames = true
  environment          = "production"
}
```

### Atmos

Atmos uses the `vars` section under each component. Variables are defined in YAML and automatically passed to Terraform. You can define vars at multiple levels (global, component) and they deep-merge, allowing inheritance and overrides.

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    vpc:
      vars:
        cidr_block: "10.0.0.0/16"
        enable_dns_hostnames: true
        environment: production
```

### Terraform Source → [Source Provisioning](/cli/commands/terraform/source) or [Vendoring](/vendor/)

### Terragrunt

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.

**File:** `vpc/terragrunt.hcl`

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

### Atmos Source Provisioning

Atmos source provisioning is the closest equivalent to Terragrunt's `terraform.source`: declare the remote module source in stack configuration, and Atmos fetches it when the component runs.

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    vpc:
      source:
        uri: "git::https://github.com/terraform-aws-modules/terraform-aws-vpc.git"
        version: "v5.0.0"
        ttl: "7d"  # Optional: refresh cached sources after this duration
      provision:
        workdir:
          enabled: true
```

Then run Terraform normally. Atmos automatically provisions the source before Terraform runs:

```shell
atmos terraform plan vpc --stack prod
```

You can also pull the source explicitly when you want to prefetch or refresh it manually:

```shell
atmos terraform source pull vpc --stack prod
```

The `ttl` setting is an Atmos-specific addition that controls when cached sources are refreshed, which is especially useful for floating refs like branches. Set `ttl: "0s"` to disable source caching and pull every time. Terragrunt does not provide an equivalent source cache TTL.

Workdir provisioning is strongly recommended with source provisioning. It stages each component instance under `.workdir/`, so Terraform runs with isolated `.terraform/` directories, generated varfiles, and backend files.

### Atmos Vendoring

Atmos vendoring is the workflow for explicitly pulling a local copy of remote module code. Define sources in `vendor.yaml`, pull them with `atmos vendor pull`, and reference the local component in stacks. Teams often use this when they want vendored code committed for review, auditability, offline use, or local customization.

First, define the vendor source:

**File:** `vendor.yaml`

```yaml
apiVersion: atmos/v1
kind: AtmosVendorConfig
spec:
  sources:
    - source: "git::https://github.com/terraform-aws-modules/terraform-aws-vpc.git?ref=v5.0.0"
      targets:
        - "components/terraform/vpc"
```

Then pull it: `atmos vendor pull`

Finally, reference in your stack:

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    vpc:
      metadata:
        component: vpc  # Points to components/terraform/vpc/
```

### Generate Blocks → [Code Generation](/stacks/generate)

### Terragrunt

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.

**File:** `terragrunt.hcl`

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

### Atmos

Atmos supports declarative file generation with the [`generate`](/stacks/generate) section. This is the closest equivalent to Terragrunt `generate` blocks: define the files in YAML, and Atmos writes them before Terraform runs when `auto_generate_files` is enabled, or when you run `atmos terraform generate files`.

You can generate HCL, JSON, YAML, Markdown, or any text file. Backend and provider generation remain common built-in workflows, but `generate` covers custom auxiliary files too.

### Stack Config (YAML)

Define generated files declaratively in YAML. String values are treated as Go templates, so stack variables can be rendered into the generated file.

**File:** `stacks/prod.yaml`

```yaml
vars:
  aws_region: us-east-1

terraform:
  auto_generate_files: true

components:
  terraform:
    vpc:
      generate:
        provider.tf: |
          provider "aws" {
            region = "{{ .vars.aws_region }}"
          }
```

### Generated provider.tf

Atmos generates this file before Terraform runs.

**File:** `components/terraform/vpc/provider.tf`

```hcl
provider "aws" {
  region = "us-east-1"
}
```

### Hooks → [Hooks](/stacks/hooks)

### Terragrunt

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

**File:** `terragrunt.hcl`

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

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

### Atmos

Atmos supports lifecycle hooks in stack configuration. Hooks can run before or after Terraform `init`, `plan`, `apply`, and `deploy`. Atmos also includes native hook kinds for common workflows: `infracost` for cost estimates, `trivy`, `checkov`, and `kics` for security and policy scanning, plus `command` for custom scripts.

**File:** `stacks/prod.yaml`

```yaml
components:
  terraform:
    vpc:
      hooks:
        cost:
          events: [after.terraform.plan]
          kind: infracost

        security:
          events: [after.terraform.plan]
          kind: trivy

        policy:
          events: [after.terraform.plan]
          kind: checkov

        kics:
          events: [after.terraform.plan]
          kind: kics

        notify:
          events: [after.terraform.apply]
          kind: command
          command: ./scripts/notify.sh
```

### Remote State Configuration

### Terragrunt

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.

**File:** `terragrunt.hcl (root)`

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

### Atmos

Atmos centralizes backend configuration in YAML and supports automatic backend provisioning with [`provision.backend`](/stacks/components/provision/backend). The `backend:` block describes where state lives, and `provision.backend.enabled` tells Atmos to create that backend if it does not exist.

**File:** `stacks/catalog/vpc.yaml`

```yaml
components:
  terraform:
    vpc:
      backend_type: s3
      backend:
        bucket: terraform-state
        key: vpc/terraform.tfstate
        region: us-east-1
        use_lockfile: true

      provision:
        backend:
          enabled: true
```

Before Terraform runs, Atmos checks whether the backend exists, provisions it if needed, and then continues with `terraform init`.

### Locals → [Locals](/stacks/locals)

### Terragrunt

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.

**File:** `terragrunt.hcl`

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

inputs = {
  cluster_name = local.cluster_name
}
```

### Atmos

Atmos supports `locals` for file-scoped computed values and `vars` for values passed into components. Use locals to reduce repetition or build derived values, then reference them with `.locals.*` in `vars`, `settings`, `env`, and other templated sections.

**File:** `stacks/prod-us-east-1.yaml`

```yaml
locals:
  account_id: "123456789012"
  region: us-east-1
  cluster_name: "{{ .locals.account_id }}-{{ .locals.region }}-eks"

components:
  terraform:
    eks:
      vars:
        account_id: "{{ .locals.account_id }}"
        region: "{{ .locals.region }}"
        cluster_name: "{{ .locals.cluster_name }}"
```

Atmos locals are scoped to the file where they are defined. Use `vars` when you need inherited values across imports, and use `locals` when you need temporary computed values inside one stack file.

### run\_cmd → YAML Functions

### Terragrunt

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.

**File:** `terragrunt.hcl`

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

### Atmos

Atmos provides **YAML functions** (like `!exec`) as the preferred way to run commands or fetch dynamic values. YAML functions are validated at parse time, produce readable configurations, and integrate naturally with YAML syntax.

**File:** `stacks/prod-us-east-1.yaml`

```yaml
vars:
  account_id: !exec aws sts get-caller-identity --query Account --output text
```

:::tip Why YAML functions over templates?
Atmos also supports Go templates (`{{ exec "..." }}`), but we recommend YAML functions because:

- **Validation**: YAML functions are validated at parse time; templates can only be validated after generation
- **Readability**: Templates turn YAML into string soup that's hard to read and debug
- **Tooling**: YAML functions work with standard YAML tooling; templates break syntax highlighting and linting

Use templates only as an escape hatch when YAML functions don't cover your use case.
:::

### extra\_arguments → Component Settings

### Terragrunt

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.

**File:** `terragrunt.hcl`

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

### Atmos

Atmos uses the `settings.terraform.args` section to pass additional arguments to Terraform. These arguments are appended to all Terraform commands for that component and can be defined at multiple levels with inheritance.

**File:** `stacks/prod-us-east-1.yaml`

```yaml
components:
  terraform:
    vpc:
      settings:
        terraform:
          args:
            - "-var-file=common.tfvars"
```

### Units and Stacks

Terragrunt recently introduced formal [Units and Stacks](https://terragrunt.gruntwork.io/docs/getting-started/terminology/) concepts (GA in v0.78.0, May 2025). Here's how they map to Atmos:

### Terragrunt

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

**File:** `terragrunt.stack.hcl`

```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"
  }
}
```

### Atmos

Atmos has always had these concepts, just with different names:

- **Unit → Component Instance**: In Atmos, when you define a component in a stack's `components.terraform` section, that's a unit—a single deployable instance with its own state.

- **Stack → Stack File**: An Atmos stack file (e.g., `prod-us-east-1.yaml`) is exactly what Terragrunt now calls a stack—a collection of component instances managed together.

**File:** `stacks/prod-us-east-1.yaml`

```yaml
# Stack file = collection of component instances (units)
components:
  terraform:
    vpc:                    # Unit 1: VPC instance
      vars:
        environment: prod
        cidr_block: "10.0.0.0/16"

    eks:                    # Unit 2: EKS instance
      vars:
        environment: prod
        cluster_name: main
```

The key difference: Atmos has used YAML for this since day one, while Terragrunt's `terragrunt.stack.hcl` is a newer HCL-based approach to the same problem.

| Terragrunt Concept | Atmos Equivalent | Notes |
|--------------------|------------------|-------|
| Unit (`terragrunt.hcl`) | Component instance in `components.terraform` | Same concept: single deployable with own state |
| Implicit Stack (directory) | Stack file | Atmos uses explicit YAML files, not directories |
| Explicit Stack (`terragrunt.stack.hcl`) | Stack file (`.yaml`) | Both define collections of units/components |
| `unit {}` block | Component entry under `components.terraform` | Atmos uses YAML; Terragrunt uses HCL |
| `values = {}` | `vars:` | Both pass variables to the underlying module |

:::tip 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](https://docs.terragrunt.com/reference/hcl/functions/).

### Path and Directory Functions

| Terragrunt Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| OpenTofu/Terraform built-ins | Go templates with Sprig/Gomplate, or YAML functions | Atmos 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 `!include` | Atmos uses explicit imports and includes instead of walking parent directories. |
| `path_relative_to_include()` | Explicit `backend.key` or templates | Atmos does not derive state keys from include paths. Configure state keys directly from stack/component context. |
| `path_relative_from_include()` | Not usually needed | Atmos imports, component base paths, and source provisioning use configured paths instead of include-relative module paths. |
| `get_repo_root()` | `!repo-root` | YAML function returns repo root path |
| `get_path_from_repo_root()` | No direct scalar function | Usually 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 function | Use `!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()` | `!cwd` | YAML function returns the directory where Atmos is executed. |
| `get_parent_terragrunt_dir()` | `import:` | Explicit imports replace parent-config discovery. |
| `get_original_terragrunt_dir()` | `!cwd` | Atmos is not directory-per-unit; use the command working directory when you need the invocation path. |

### Environment and Platform Functions

| Terragrunt Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `get_env("VAR", "default")` | `!env VAR, default` | YAML function for environment variables |
| `get_platform()` | No native equivalent | Sprig 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_id` | YAML function backed by AWS STS |
| `get_aws_account_alias()` | `!exec` | No dedicated YAML function; run an AWS CLI command |
| `get_aws_caller_identity_arn()` | `!aws.caller_identity_arn` | YAML function backed by AWS STS |
| `get_aws_caller_identity_user_id()` | `!aws.caller_identity_user_id` | YAML function backed by AWS STS |

### Terraform Command Helpers

| Terragrunt Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `get_terraform_commands_that_need_vars()` | Built in | Atmos generates and passes component varfiles automatically for Terraform commands that need them. |
| `get_terraform_commands_that_need_input()` | `settings.terraform.args` | Configure `-input=false` or related flags explicitly. |
| `get_terraform_commands_that_need_locking()` | `settings.terraform.args` | Configure lock flags explicitly when needed. |
| `get_terraform_commands_that_need_parallelism()` | `settings.terraform.args` | Configure `-parallelism` explicitly when needed. |
| `get_terraform_command()` | No direct function | Atmos 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 args | Use 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.conditions` | Atmos has component retry configuration instead of a helper returning default regexes. |

### Command Execution

| Terragrunt Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `run_cmd("cmd", "arg1", ...)` | `!exec` | `!exec cmd arg1` executes shell commands in YAML functions. |
| `run_cmd("--terragrunt-quiet", ...)` | No direct flag | Use Atmos secret masking and avoid printing sensitive command output. |
| `run_cmd("--terragrunt-global-cache", ...)` | No direct flag | Atmos 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 Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `deep_merge()` | Stack imports and inheritance | Atmos 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 stores | No 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 equivalent | Atmos 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 Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `dependency.X.outputs.Y` | `!terraform.output` | `!terraform.output component.output_name` |
| N/A | `!terraform.state` | Read arbitrary state attributes |

### Change Tracking and Constraints

| Terragrunt Function | Atmos Equivalent | Notes |
|---------------------|------------------|-------|
| `mark_as_read()` | `dependencies.files` | Declare explicit file dependencies so `describe affected`/`list affected` can track changes. |
| `mark_glob_as_read()` | `dependencies.folders` | Declare folder dependencies instead of imperatively marking glob reads. |
| `constraint_check()` | Sprig `semverCompare` or tool dependency constraints | Use `semverCompare` in templates for conditional config, or Atmos toolchain dependency constraints for tool versions. |

:::tip 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](/functions/yaml) for the complete reference.
:::

## CLI Command Comparison

### Terragrunt

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.

```bash
# 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
```

### Atmos

Atmos commands run from **anywhere within a configured Atmos repository**—you never need to `cd` anywhere. Just specify the component and stack, and Atmos finds everything automatically. This makes scripts and CI/CD pipelines simpler and eliminates directory management entirely.

```bash
# Plan a single component (from repo root)
atmos terraform plan vpc -s prod-us-east-1

# Apply a single component
atmos terraform apply vpc -s prod-us-east-1

# Plan ALL components in ALL stacks
atmos terraform plan --all

# Apply ALL components in ALL stacks
atmos terraform apply --all

# Show outputs
atmos terraform output vpc -s prod-us-east-1

# List all stacks
atmos list stacks

# Describe a component
atmos describe component vpc -s prod-us-east-1
```

**GitOps-native:** Atmos goes beyond simple "run all" with intelligent change detection:

```bash
# See what changed between commits (table output for humans)
atmos list affected --ref main

# Plan ONLY components affected by changes in current branch
atmos terraform plan --affected

# Apply ONLY affected components
atmos terraform apply --affected

# Compare against a specific branch or commit
atmos list affected --ref refs/heads/feature-branch
atmos list affected --sha abc123def

# Include dependent components (if vpc changed, also plan eks that depends on it)
atmos list affected --include-dependents=true

# Same comparison as JSON/YAML, for scripting and CI
atmos describe affected --base main
```

This is purpose-built for CI/CD: instead of planning everything on every PR, Atmos analyzes Git changes to determine exactly which components and stacks are affected—including changes to stack configs, component code, and even local Terraform modules. `list affected` and `describe affected` both diff **committed** trees, not the working tree—commit a change before comparing.

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

:::note 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](https://github.com/cloudposse/atmos/blob/main/plugins/terragrunt/README.md) for the build commands.
:::

**File:** `atmos.yaml`

```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:

```shell
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](#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.

| Unit | Component | Stack |
| --- | --- | --- |
| `live/dev/vpc/terragrunt.hcl` | `vpc` (the unit directory name) | `live/dev` (the directory above the unit) |
| `live/vpc/terragrunt.hcl` | `vpc` | `live` |
| `live/terragrunt.hcl` | `live` | `default` |
| `terragrunt.hcl` in the base path | `root` | `default` |
| `live/terragrunt.stack.hcl` generating `dev/app` | `dev/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](#override-a-unit-from-stack-configuration).

### 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:

**File:** `stacks/dev.yaml`

```yaml
import:
  - terragrunt://live/dev
vars:
  stage: dev
```

```shell
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](#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.

**File:** `stacks/dev.yaml`

```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:

| Section | Behavior |
| --- | --- |
| `vars` | Merged 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. |
| `env` | Wins 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`, `dependencies` | Ordinary 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. |
| `command` | Selects 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_type` | Not 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.uri` | Not 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](https://github.com/bmatcuk/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.

| Pattern | Selects |
| --- | --- |
| `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/vpc` | the unit in that directory |
| `live/dev/vpc/terragrunt.hcl` | exactly that file |
| `**/vpc`, `live/*/vpc` | every 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.

### Symlinks

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.

### Credentials, values, and logs

- Terragrunt functions that call AWS, such as `get_aws_account_id()`, and S3 dependency state reads use the identity of the Atmos invocation: its profile, shared credentials and config files, web identity token file, static keys, and `AWS_ENDPOINT_URL` or `AWS_ENDPOINT_URL_<SERVICE>` overrides. `TG_IAM_ASSUME_ROLE` applies on top. An Atmos identity takes precedence over a `profile` set in a `remote_state` block.
- Unit inputs reach OpenTofu with their exact numeric values and with null preserved. An input written as `sensitive(...)`, directly or through a local, an object literal, or `merge()`, is masked in all output and logs, kept out of the generated variable file, and passed to OpenTofu through a `TF_VAR_` environment variable.
- Terragrunt's own log events are hidden by default. With `--logs-level=Debug` or `Trace`, or `ATMOS_LOGS_LEVEL`, Atmos prints them on stderr with the plugin, component, and stack, with secrets masked. They never change a command's output or exit code. A warning about a unit is shown once per command.

### Flags

Options a configuration provider declares in its package metadata appear as flags on the `atmos terraform` commands that accept them, under a section named for the provider. A flag follows the order command line, then environment, then `atmos.yaml`, then the declared default, and a value you leave unset is never sent. Provider flags cannot reuse a flag Atmos owns.

The Terragrunt provider adds `--terragrunt-feature name=value` (repeatable, also `ATMOS_TERRAGRUNT_FEATURE` and `TG_FEATURE`), `--terragrunt-iam-assume-role`, `--terragrunt-iam-assume-role-duration`, `--terragrunt-iam-assume-role-session-name`, `--terragrunt-iam-assume-role-web-identity-token`, and `--terragrunt-download-dir`. The token is never written to configuration or printed. A saved plan is bound to the provider options it was created with: apply it with the same options, or create a new plan.

### Atmos Pro

Terragrunt units are ordinary Terraform components to Atmos Pro: `atmos describe affected --upload` and `atmos list instances --upload` report them by component and stack, and a unit joins Atmos Pro when the stack that imports it sets `settings.pro.enabled: true`.

To plan one unit on one runner and apply it on another, run `atmos terraform plan` followed by `atmos terraform planfile upload`, which publishes the plan and its record together. On the next runner, `atmos terraform planfile download` followed by `atmos terraform apply --from-plan` re-provisions the working directory from the checkout, verifies it against the reviewed plan, and applies exactly that plan. With an absolute `base_path`, the checkout must be at the same absolute path on both runners.

### Executable mode

Set `components.terraform.terragrunt.mode: executable` to keep Terragrunt itself as the engine while Atmos still discovers and orders units, authenticates, resolves the toolchain and environment, and runs one pinned `terragrunt run` per unit. Pin Terragrunt 1.0.0 or newer in `.tool-versions` or `dependencies.tools`. Hooks, `errors`, `exclude`, and IAM roles are Terragrunt's own in this mode. Atmos-managed saved plans, stack `vars` and `providers` overrides, and `terraform shell` are not available, and `--all` is scheduled by Atmos, not by `terragrunt run --all`. A project is either native or executable, never both, and native mode never falls back to the executable.

### 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. `atmos terraform deploy` verification of a stored plan on a fresh runner is not supported; use `planfile download` and `apply --from-plan`. 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

### Before (Terragrunt)

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.

**File:** `prod/us-east-1/vpc/terragrunt.hcl`

```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"
}
```

### After (Atmos)

The Atmos stack file consolidates all configuration in one place. Imports bring in shared defaults, vars set environment-level values, and components define what to deploy. Each component points to a local Terraform module.

**File:** `stacks/prod-us-east-1.yaml`

```yaml
import:
  - _defaults/globals

vars:
  environment: prod
  region: us-east-1

components:
  terraform:
    vpc:
      metadata:
        component: vpc  # Points to components/terraform/vpc
      vars:
        cidr_block: "10.0.0.0/16"
```

### Step 2: Move Terraform Root Modules

:::info 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.
:::

### Before (Terragrunt)

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

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

### After (Atmos)

Atmos runs your existing root modules as components. Set `components.terraform.base_path` to their current parent directory, such as `modules`. Moving them to the conventional `components/terraform/` directory shown below is optional; the Terraform code can stay unchanged.

```plaintext
components/terraform/
├── vpc/                    # Component = root module
│   ├── main.tf
│   └── variables.tf
└── eks/                    # Component = root module
    ├── main.tf
    └── variables.tf
```

Keep `modules/` with `components.terraform.base_path: modules`, or choose the illustrated layout if you want to reorganize.

### Step 3: Update Backend Configuration

### Before (Terragrunt)

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.

**File:** `terragrunt.hcl (root)`

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

### After (Atmos)

Atmos can define backend settings in a shared defaults file. When migrating, preserve the full existing backend state location and Terraform workspace; do not substitute newly generated keys for existing state. Use per-component backend overrides and `metadata.terraform_workspace` to match the current deployment. The following example illustrates shared configuration; adapt it to your actual state locations.

**File:** `stacks/_defaults/globals.yaml`

```yaml
terraform:
  backend_type: s3
  backend:
    s3:
      bucket: terraform-state
      key: terraform.tfstate
      region: us-east-1
```

Component-specific key prefixes:

**File:** `stacks/prod-us-east-1.yaml`

```yaml
components:
  terraform:
    vpc:
      backend:
        s3:
          workspace_key_prefix: vpc
```

## Migration Checklist

- \[ ] Install Atmos CLI ([Installation Guide](/install))
- \[ ] 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:

### Option 1: Use `name_template` (Recommended for Consistent Patterns)

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

**File:** `atmos.yaml`

```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:

**File:** `stacks/us-east-1/prod/vpc.yaml`

```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](/stacks/name).

## 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](/stacks/generate), 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:

- **[Slack Community](/community/slack)** - Ask migration questions
- **[Office Hours](/community/office-hours)** - Live support for complex migrations
- **[GitHub Discussions](https://github.com/cloudposse/atmos/discussions)** - Share your migration story

## Next Steps

Now that you understand the migration path:

- **[Learn YAML in Atmos](/learn/yaml)** - YAML is more powerful than you might think. Learn how Atmos uses deep merging, scope, and inheritance
- **[Explore YAML Functions](/functions/yaml)** - YAML functions like `!terraform.output`, `!env`, and `!exec` are first-class YAML features (technically explicit tags) that give your configuration superpowers
- **[Try the Quick Start](/quick-start/simple)** - Get hands-on with Atmos
- **[Read Core Concepts](/learn/why-atmos)** - Understand Atmos deeply
- **[Explore Stack Configuration](/stacks/)** - Advanced YAML features
