Migrating to Atmos
Overview
Use this skill to adopt Atmos for infrastructure orchestration, general-purpose task running,
or tool-version management. Select the migration path from the user's goal and existing tools.
For Make, Just, and Task, assume the user is adopting Atmos as a task runner for application
builds, tests, scripts, releases, and other automation. Custom commands need only atmos.yaml;
do not introduce Terraform components, stacks, .tfvars conversion, or cloud credentials unless
the user separately requests infrastructure orchestration. Preserve the commands behind the tasks,
and let Atmos call the existing task runner while individual tasks are migrated.
For Terraform repositories, Atmos can adopt the existing file layout. Start with the smallest
change that gives value and add structure as needed.
For Fogg, read from-fogg.md before applying generic Terraform advice:
keep generated files for adoption, then take ownership of configuration generation and checks
so future changes no longer require Fogg.
For full tutorials for end users, see:
Terraform or OpenTofu
This skill applies the same way to Terraform and to OpenTofu. Atmos runs the binary set in
components.terraform.command in atmos.yaml. The default binary is terraform. The migration
steps, file layouts, and the remote-state bridge do not change based on the binary. Use the same
word the user uses. If the user says "OpenTofu," write "OpenTofu" in your response.
Core Principles
These principles come before your normal instincts. Read them before you propose a change to the
user's repository.
- Terraform migration can preserve the existing layout. Atmos does not require a filesystem
reorganization. Point
base_path at the user's existing layout (e.g., base_path: "terraform"
or base_path: ".") when preserving layout lowers adoption risk. The components/terraform/
convention is still the best-practice layout for new or fully migrated repos because Atmos
supports multiple toolchains (Terraform, Helmfile, Packer, Ansible); it is not a prerequisite
for adopting Atmos in Terraform-only repos.
- Existing
.tfvars files may be kept during migration. Use !include to pull them into
stacks when the user wants minimal disruption. Converting values into native stack YAML remains
the best-practice end state when the user wants deep-merge inheritance and richer stack
composition, but it can happen progressively.
- No Terraform code changes are required. Don't rewrite providers, backends, or modules
during migration. Atmos generates
backend.tf.json and *.auto.tfvars.json at runtime.
- Workspaces are not the enemy. If the user has
terraform.workspace-driven environments,
Atmos can map onto their existing state via metadata.terraform_workspace and
workspace_key_prefix. They do not have to abandon their workspace state to adopt Atmos.
- Prefer YAML functions over Gomplate datasources. When both can express the same thing
(
!include vs gomplate.datasources for files, !exec vs templated shell, !env vs
gomplate getenv, !store vs custom datasource URLs), reach for the YAML function first.
YAML functions are type-safe, can't break YAML parsing, produce clear errors, and don't
require enabling Gomplate. See the atmos-yaml-functions
and atmos-templates skills for the boundary.
- Start with one working command. For task-runner adoption, start with
atmos build or
another existing task. For Terraform adoption, start with a plan. Add configuration structure
only when it serves the selected migration.
- Task-runner adoption is a complete use case. Map targets, recipes, and tasks to custom
commands. Preserve ordering and shared prerequisites; use workflows where they help organize
reusable multi-step automation. No Terraform migration is implied. Atmos can call
make,
just, or task during incremental adoption, with no requirement to remove the original files.
Decide the Migration Shape First
Find the user's source pattern before you propose any change. Each pattern points to a different
reference file:
| User has... |
Use reference |
One TF root module, env config via .tfvars or env vars |
from-native-terraform.md |
| Multiple TF root modules in scattered dirs |
from-native-terraform.md |
terraform.workspace-driven environments with shared state backend |
from-terraform-workspaces.md |
fogg.yml, Fogg-generated Terraform and Make/CI tasks |
from-fogg.md |
.tm.hcl files, stack.tm.hcl, generate_hcl blocks (Terramate project) |
from-terramate.md |
| Need to read outputs from un-migrated TF (legacy or another repo) |
remote-state-bridge.md |
| User has a Makefile driving builds/tests/deploys |
from-makefile.md |
User has a Justfile (just command runner) |
from-justfile.md |
| User has a Taskfile.yml (go-task) |
from-taskfile.md |
cloudposse/github-action-atmos-component-updater |
from-component-updater.md |
Terragrunt (terragrunt.hcl or terragrunt.stack.hcl) |
from-terragrunt.md |
mise config (mise.toml, .mise.toml, .mise/config.toml, .tool-versions) for tool versions |
from-mise.md |
aqua.yaml (Aqua CLI) for tool versions |
from-aqua.md |
| CI on GitHub Actions (setup-terraform, configure-aws-credentials, dflook, tfcmt) |
to-native-ci.md |
| Scanner actions (TFLint, Checkov, Trivy, KICS, Infracost, tfsec) |
to-native-ci-scanners.md |
| User is migrating off Rain / raw CloudFormation |
from-rain.md |
The remote-state-bridge pattern makes progressive migration possible. It lets a team migrate one
component at a time. Without it, the team must migrate everything at once. Use this pattern when
the user has existing Terraform state that a new Atmos component must read.
Common Problems in Task-Runner Migration
Check these before you open a reference file; each reference file's own "Common Problems" section
has the exact field names and steps.
- Default order differs by source tool. Task's
deps: runs concurrently by default, matching
dependencies.commands/dependencies.workflows directly. Make and Just run dependencies
sequentially by default (make -j is required for concurrency) -- moving an ordinary Make/Just
chain to dependencies.commands changes the order and can introduce a race. Preserve ordered
steps for a sequential source chain; reach for dependencies.commands only when the source used
-j, the prerequisites are genuinely independent, or a prerequisite is shared by more than one
caller (deduped to a single run regardless of concurrency, true for every one of these tools).
- Freshness checks map to
inputs/artifacts at the step level, not to a whole recipe/task.
Task's sources:/generates: and non-.PHONY Make targets skip the entire recipe when
nothing changed. Atmos's step-level inputs.sources/artifacts.paths (implicitly
when: checksum.changed) only skip that step -- later steps in the same command still run.
Combine multi-command recipes into one shell/script step if the freshness gate must cover
all of them together; this doesn't carry over automatically. require/assert only checks
existence, not freshness.
workflows.base_path must be set explicitly once the user has their own atmos.yaml
(atmos workflow <name> fails without it) -- add it the moment migration reaches its first
workflow. Workflows can organize general-purpose tasks as well as infrastructure operations;
many target chains can stay custom commands. For task-runner adoption, a path such as
workflows.base_path: "workflows" keeps workflows separate from Terraform stacks.
Migrating Authentication
Authentication is an orthogonal migration axis from IaC -- a user may migrate their Terraform code,
their auth setup, both, or neither in a given session. Don't conflate the two. Identify which
credential tooling the user has today and route to the matching reference:
| User has... |
Use reference |
~/.aws/config/~/.aws/credentials profiles |
from-aws-config.md |
gcloud CLI config, ADC, or service-account keys |
from-gcp-config.md |
az CLI config, service principals, or Managed Identity |
from-azure-config.md |
| Leapp (desktop credential manager) |
from-leapp.md |
Granted (the assume CLI) |
from-granted.md |
| saml2aws |
from-aws2saml.md |
| okta-aws-cli |
from-okta-cli.md -- partial support only, read the gap callouts |
All are pure config-translation guides -- there is no atmos auth import/migrate command.
None of them require touching the user's IaC migration path; they can run before, after, or
independently of one. from-okta-cli.md is the one exception to "full mapping exists": whether it
works depends on the org's Okta auth policy, not on a different AWS app type -- read it fully
before promising a user anything.
The Minimum-Viable Migration
Choose the checklist for the user's goal.
Task Runner
- Install Atmos and create
atmos.yaml in the existing project.
- Add one custom command that calls an existing task, such as
make build, just build, or
task build.
- Run
atmos build and confirm it produces the same result as the original command.
- Move task bodies into native steps as needed, preserving parameters, environments, dependency
order, and freshness behavior. No stack files or Terraform changes are required.
Terraform Orchestration
Use this checklist when the user explicitly wants Atmos to orchestrate existing Terraform code.
- Install Atmos. See
atmos.tools/install.
- Create
atmos.yaml at the repo root, pointing base_path and components.terraform.base_path
at the user's existing layout. Do not ask them to move files.
- Create one stack file for one environment. Use
!include of an existing .tfvars file so
nothing has to be rewritten:# stacks/dev.yaml
import:
- _defaults
components:
terraform:
vpc:
vars: !include ../path/to/existing/dev.tfvars
- Run
atmos terraform plan vpc -s dev and confirm output matches what terraform plan -var-file=dev.tfvars produced before.
A working example of this shape is at examples/native-terraform/ in the Atmos repository.
File-Layout Options
Pick the layout that matches the user's goals. Atmos recommends the components/terraform/
layout, especially for a new repository or a multi-tool project. You can keep an existing layout
when the user wants less disruption.
base_path |
Use when |
base_path: "." |
TF root modules live at the repo root; user wants zero file moves |
base_path: "terraform" |
TF-only repo with code already in terraform/; preserve dir name |
base_path: "." + components.terraform.base_path: "components/terraform" |
Multi-toolchain or new repo; canonical Atmos layout |
For more organization patterns, such as multi-region, multi-account, and organization
hierarchies, see the skill atmos-design-patterns.
YAML Functions vs Gomplate Datasources
This is a common mistake: an agent chooses a Gomplate datasource when a YAML function is safer
and clearer. Use the option in the right column:
| Goal |
Reach for (NOT this) |
Use instead |
| Include a file's contents |
gomplate.datasources with file URL |
!include path/to/file |
| Read an environment variable |
gomplate getenv "FOO" |
!env FOO |
| Run a shell command |
Template + gomplate exec |
!exec "command" |
| Read a store value |
Custom datasource URL |
!store store_name component stack key |
| Read Terraform output |
Templated remote-state datasource |
!terraform.state component output |
| Get current AWS account ID |
gomplate.datasources AWS plugin |
!aws.account_id |
A YAML function checks its own types. It gives a clear error message. It works without Gomplate
turned on. It does not require the template text to stay valid YAML. Use a Go template only for
control flow, such as a conditional, a loop, or a dynamic key, that a YAML function cannot
express. See atmos-templates for when to use a Go template.
What Does NOT Need to Change
Tell the user this list first, if they are afraid of a large rewrite. None of these items must
change to adopt Atmos:
- Terraform code. Providers, resources, data sources, and modules stay the same.
- Module sources. A local path, such as
source = "../../modules/foo", or a registry
source, keeps working.
- Backend code. You can delete the
backend "s3" {} block from the .tf files, because
Atmos creates backend.tf.json. Or you can keep the block and turn off backend generation in
atmos.yaml. Both methods work.
.tfvars files. Atmos reads them through !include. Convert them to YAML later, only if
the user wants deep-merge inheritance.
- Custom provider configuration. Providers stay in the
.tf files. Pass environment
variables through stack env:. Pass Terraform variables through stack vars:.
When to Escalate to Other Skills
After the minimum migration works, the user will often ask what to do next. Send each question
to the correct skill:
- Organize many stacks, such as by organization, tenant, account, or region. Use
atmos-design-patterns.
- Build abstract components, inheritance, or catalog patterns. Use
atmos-components.
- Use deep merging, imports, or overrides. Use atmos-stacks.
- Vendor third-party components. Use atmos-vendoring.
- Migrate an AWS/GCP/Azure CLI, Leapp, Granted, saml2aws, or okta-aws-cli setup. Start with
the matching reference in Migrating Authentication above. For
authoring new auth config beyond a migration, go straight to atmos-auth.
- Add validation policies, such as OPA or JSON Schema. Use
atmos-validation.
- Set up CI/CD with affected-component detection. Use atmos-ci.
- Migrate third-party GitHub Actions CI (dflook, tfcmt, etc.) to Native CI. Use
to-native-ci.md.
- Share data between components through a store. Use
atmos-stores.
Anti-Patterns
Push back if a user or another agent proposes one of these methods during migration:
- "You must move all Terraform into
components/terraform/ before you use Atmos." This is
false. That layout is a recommendation, not a requirement. Let the user pick: adopt the
recommended layout now, or point base_path at the current layout and reorganize later.
- "You must rewrite all
.tfvars files as YAML before you run Atmos." This is false. Native
stack YAML is the best final format for inheritance and composition. But !include lets the
user keep existing .tfvars files during a step-by-step migration.
- "Delete your workspace state and start over." This is false. Connect the existing state
with
metadata.terraform_workspace and the remote-state-bridge pattern.
- "Add a Gomplate datasource for everything." This is false. Use a YAML function first.
- "Adopt the full multi-account organization hierarchy on day one." This is false. Start
with one stack file.
- "Task-runner migration requires Terraform stacks or components." Custom commands run general
automation from
atmos.yaml. Keep infrastructure adoption separate from task-runner adoption.
- "Delete the existing task file before adopting Atmos." Atmos can call the existing runner.
Migrate task bodies incrementally and preserve the source tool's ordering and freshness semantics.
- "Wrap atmos commands in a Makefile, Justfile, or Taskfile forever." This is false. A
wrapper is a good bridge while the user builds trust in Atmos, not the final state -- change
each leaf target to a custom command (see Principle 7 and "Common Problems in Task-Runner
Migration" above for the concurrency/ordering details per source tool).
Every reference file is already linked, with its routing condition, from the "Decide the
Migration Shape First" and "Migrating Authentication" tables above -- load a reference directly
from there rather than a separate resource list.
1---2name: atmos-migration3description: "Migrate to Atmos from native Terraform, Terraform Workspaces, Fogg, Terramate, Terragrunt, Make, Just, or Task; migrate Rain or raw CloudFormation stacks to the aws/cloudformation component; migrate tool versions from mise or Aqua CLI; migrate AWS/GCP/Azure CLI configs, Leapp, Granted, saml2aws, or okta-aws-cli to atmos auth; and replace GitHub Actions CI (dflook, tfcmt, cloud OIDC, component updater, TFLint, Checkov, Trivy, KICS, Infracost, tfsec) with Atmos Native CI. Use for incremental adoption that preserves layout, state, task behavior, and CI enforcement."4metadata:5 source: https://skillmd.com/skills/cloudposse/atmos-migration6 copyright: Copyright Cloud Posse, LLC 20267 version: "1.0.0"8 category: state-versioning9references:10 - references/from-native-terraform.md11 - references/from-terraform-workspaces.md12 - references/remote-state-bridge.md13 - references/from-fogg.md14 - references/from-terramate.md15 - references/from-makefile.md16 - references/from-justfile.md17 - references/from-taskfile.md18 - references/from-component-updater.md19 - references/from-terragrunt.md20 - references/from-mise.md21 - references/from-aqua.md22 - references/from-aws-config.md23 - references/from-gcp-config.md24 - references/from-azure-config.md25 - references/from-leapp.md26 - references/from-granted.md27 - references/from-aws2saml.md28 - references/from-okta-cli.md29 - references/to-native-ci.md30 - references/to-native-ci-scanners.md31 - references/from-rain.md32---3334# Migrating to Atmos3536## Overview3738Use this skill to adopt Atmos for infrastructure orchestration, general-purpose task running,39or tool-version management. Select the migration path from the user's goal and existing tools.4041For Make, Just, and Task, assume the user is adopting Atmos as a task runner for application42builds, tests, scripts, releases, and other automation. Custom commands need only `atmos.yaml`;43do not introduce Terraform components, stacks, `.tfvars` conversion, or cloud credentials unless44the user separately requests infrastructure orchestration. Preserve the commands behind the tasks,45and let Atmos call the existing task runner while individual tasks are migrated.4647For Terraform repositories, Atmos can adopt the existing file layout. Start with the smallest48change that gives value and add structure as needed.4950For Fogg, read [from-fogg.md](references/from-fogg.md) before applying generic Terraform advice:51keep generated files for adoption, then take ownership of configuration generation and checks52so future changes no longer require Fogg.5354For full tutorials for end users, see:5556- [Migrating from Native Terraform](https://atmos.tools/migration/native-terraform)57- [Migrating from Terraform Workspaces](https://atmos.tools/migration/terraform-workspaces)58- [Migrating from Terragrunt](https://atmos.tools/migration/terragrunt) -- see59 [from-terragrunt.md](references/from-terragrunt.md) for agent recipes60- [Migrating from Fogg](https://atmos.tools/migration/fogg) -- see61 [from-fogg.md](references/from-fogg.md) for adoption and behavioral parity62- Migrating from Terramate -- see [from-terramate.md](references/from-terramate.md)63 (no atmos.tools tutorial yet)64- [Migrating from Makefiles](https://atmos.tools/migration/makefile)65- [Migrating from Justfiles](https://atmos.tools/migration/justfile)66- [Migrating from Taskfile.yml](https://atmos.tools/migration/taskfile)67- [Migrating from Rain / Raw CloudFormation](https://atmos.tools/migration/rain)6869## Terraform or OpenTofu7071This skill applies the same way to Terraform and to OpenTofu. Atmos runs the binary set in72`components.terraform.command` in `atmos.yaml`. The default binary is `terraform`. The migration73steps, file layouts, and the remote-state bridge do not change based on the binary. Use the same74word the user uses. If the user says "OpenTofu," write "OpenTofu" in your response.7576## Core Principles7778These principles come before your normal instincts. Read them before you propose a change to the79user's repository.80811. **Terraform migration can preserve the existing layout.** Atmos does not require a filesystem82 reorganization. Point `base_path` at the user's existing layout (e.g., `base_path: "terraform"`83 or `base_path: "."`) when preserving layout lowers adoption risk. The `components/terraform/`84 convention is still the best-practice layout for new or fully migrated repos because Atmos85 supports multiple toolchains (Terraform, Helmfile, Packer, Ansible); it is not a prerequisite86 for adopting Atmos in Terraform-only repos.872. **Existing `.tfvars` files may be kept during migration.** Use `!include` to pull them into88 stacks when the user wants minimal disruption. Converting values into native stack YAML remains89 the best-practice end state when the user wants deep-merge inheritance and richer stack90 composition, but it can happen progressively.913. **No Terraform code changes are required.** Don't rewrite providers, backends, or modules92 during migration. Atmos generates `backend.tf.json` and `*.auto.tfvars.json` at runtime.934. **Workspaces are not the enemy.** If the user has `terraform.workspace`-driven environments,94 Atmos can map onto their existing state via `metadata.terraform_workspace` and95 `workspace_key_prefix`. They do not have to abandon their workspace state to adopt Atmos.965. **Prefer YAML functions over Gomplate datasources.** When both can express the same thing97 (`!include` vs `gomplate.datasources` for files, `!exec` vs templated shell, `!env` vs98 `gomplate getenv`, `!store` vs custom datasource URLs), reach for the YAML function first.99 YAML functions are type-safe, can't break YAML parsing, produce clear errors, and don't100 require enabling Gomplate. See the [atmos-yaml-functions](../atmos-yaml-functions/SKILL.md)101 and [atmos-templates](../atmos-templates/SKILL.md) skills for the boundary.1026. **Start with one working command.** For task-runner adoption, start with `atmos build` or103 another existing task. For Terraform adoption, start with a plan. Add configuration structure104 only when it serves the selected migration.1057. **Task-runner adoption is a complete use case.** Map targets, recipes, and tasks to custom106 commands. Preserve ordering and shared prerequisites; use workflows where they help organize107 reusable multi-step automation. No Terraform migration is implied. Atmos can call `make`,108 `just`, or `task` during incremental adoption, with no requirement to remove the original files.109110## Decide the Migration Shape First111112Find the user's source pattern before you propose any change. Each pattern points to a different113reference file:114115| User has... | Use reference |116| --- | --- |117| One TF root module, env config via `.tfvars` or env vars | [from-native-terraform.md](references/from-native-terraform.md) |118| Multiple TF root modules in scattered dirs | [from-native-terraform.md](references/from-native-terraform.md) |119| `terraform.workspace`-driven environments with shared state backend | [from-terraform-workspaces.md](references/from-terraform-workspaces.md) |120| `fogg.yml`, Fogg-generated Terraform and Make/CI tasks | [from-fogg.md](references/from-fogg.md) |121| `.tm.hcl` files, `stack.tm.hcl`, `generate_hcl` blocks (Terramate project) | [from-terramate.md](references/from-terramate.md) |122| Need to read outputs from un-migrated TF (legacy or another repo) | [remote-state-bridge.md](references/remote-state-bridge.md) |123| User has a Makefile driving builds/tests/deploys | [from-makefile.md](references/from-makefile.md) |124| User has a Justfile (`just` command runner) | [from-justfile.md](references/from-justfile.md) |125| User has a Taskfile.yml (go-task) | [from-taskfile.md](references/from-taskfile.md) |126| `cloudposse/github-action-atmos-component-updater` | [from-component-updater.md](references/from-component-updater.md) |127| Terragrunt (`terragrunt.hcl` or `terragrunt.stack.hcl`) | [from-terragrunt.md](references/from-terragrunt.md) |128| mise config (`mise.toml`, `.mise.toml`, `.mise/config.toml`, `.tool-versions`) for tool versions | [from-mise.md](references/from-mise.md) |129| `aqua.yaml` (Aqua CLI) for tool versions | [from-aqua.md](references/from-aqua.md) |130| CI on GitHub Actions (setup-terraform, configure-aws-credentials, dflook, tfcmt) | [to-native-ci.md](references/to-native-ci.md) |131| Scanner actions (TFLint, Checkov, Trivy, KICS, Infracost, tfsec) | [to-native-ci-scanners.md](references/to-native-ci-scanners.md) |132| User is migrating off Rain / raw CloudFormation | [from-rain.md](references/from-rain.md) |133134The remote-state-bridge pattern makes progressive migration possible. It lets a team migrate one135component at a time. Without it, the team must migrate everything at once. Use this pattern when136the user has existing Terraform state that a new Atmos component must read.137138### Common Problems in Task-Runner Migration139140Check these before you open a reference file; each reference file's own "Common Problems" section141has the exact field names and steps.142143- **Default order differs by source tool.** Task's `deps:` runs concurrently by default, matching144 `dependencies.commands`/`dependencies.workflows` directly. Make and Just run dependencies145 sequentially by default (`make -j` is required for concurrency) -- moving an ordinary Make/Just146 chain to `dependencies.commands` changes the order and can introduce a race. Preserve ordered147 steps for a sequential source chain; reach for `dependencies.commands` only when the source used148 `-j`, the prerequisites are genuinely independent, or a prerequisite is shared by more than one149 caller (deduped to a single run regardless of concurrency, true for every one of these tools).150- **Freshness checks map to `inputs`/`artifacts` at the step level, not to a whole recipe/task.**151 Task's `sources:`/`generates:` and non-`.PHONY` Make targets skip the *entire* recipe when152 nothing changed. Atmos's step-level `inputs.sources`/`artifacts.paths` (implicitly153 `when: checksum.changed`) only skip *that step* -- later steps in the same command still run.154 Combine multi-command recipes into one `shell`/`script` step if the freshness gate must cover155 all of them together; this doesn't carry over automatically. `require`/`assert` only checks156 existence, not freshness.157- **`workflows.base_path` must be set explicitly** once the user has their own `atmos.yaml`158 (`atmos workflow <name>` fails without it) -- add it the moment migration reaches its first159 workflow. Workflows can organize general-purpose tasks as well as infrastructure operations;160 many target chains can stay custom commands. For task-runner adoption, a path such as161 `workflows.base_path: "workflows"` keeps workflows separate from Terraform stacks.162163## Migrating Authentication164165Authentication is an orthogonal migration axis from IaC -- a user may migrate their Terraform code,166their auth setup, both, or neither in a given session. Don't conflate the two. Identify which167credential tooling the user has today and route to the matching reference:168169| User has... | Use reference |170| --- | --- |171| `~/.aws/config`/`~/.aws/credentials` profiles | [from-aws-config.md](references/from-aws-config.md) |172| `gcloud` CLI config, ADC, or service-account keys | [from-gcp-config.md](references/from-gcp-config.md) |173| `az` CLI config, service principals, or Managed Identity | [from-azure-config.md](references/from-azure-config.md) |174| Leapp (desktop credential manager) | [from-leapp.md](references/from-leapp.md) |175| Granted (the `assume` CLI) | [from-granted.md](references/from-granted.md) |176| saml2aws | [from-aws2saml.md](references/from-aws2saml.md) |177| okta-aws-cli | [from-okta-cli.md](references/from-okta-cli.md) -- **partial support only, read the gap callouts** |178179All are pure config-translation guides -- there is no `atmos auth import`/`migrate` command.180None of them require touching the user's IaC migration path; they can run before, after, or181independently of one. `from-okta-cli.md` is the one exception to "full mapping exists": whether it182works depends on the org's Okta auth policy, not on a different AWS app type -- read it fully183before promising a user anything.184185## The Minimum-Viable Migration186187Choose the checklist for the user's goal.188189### Task Runner1901911. Install Atmos and create `atmos.yaml` in the existing project.1922. Add one custom command that calls an existing task, such as `make build`, `just build`, or193 `task build`.1943. Run `atmos build` and confirm it produces the same result as the original command.1954. Move task bodies into native steps as needed, preserving parameters, environments, dependency196 order, and freshness behavior. No stack files or Terraform changes are required.197198### Terraform Orchestration199200Use this checklist when the user explicitly wants Atmos to orchestrate existing Terraform code.2012021. **Install Atmos.** See `atmos.tools/install`.2032. **Create `atmos.yaml`** at the repo root, pointing `base_path` and `components.terraform.base_path`204 at the user's existing layout. Do not ask them to move files.2053. **Create one stack file** for one environment. Use `!include` of an existing `.tfvars` file so206 nothing has to be rewritten:207 ```yaml208 # stacks/dev.yaml209 import:210 - _defaults211 components:212 terraform:213 vpc:214 vars: !include ../path/to/existing/dev.tfvars215 ```2164. **Run `atmos terraform plan vpc -s dev`** and confirm output matches what `terraform plan217 -var-file=dev.tfvars` produced before.218219A working example of this shape is at `examples/native-terraform/` in the Atmos repository.220221## File-Layout Options222223Pick the layout that matches the user's goals. Atmos recommends the `components/terraform/`224layout, especially for a new repository or a multi-tool project. You can keep an existing layout225when the user wants less disruption.226227| `base_path` | Use when |228| --- | --- |229| `base_path: "."` | TF root modules live at the repo root; user wants zero file moves |230| `base_path: "terraform"` | TF-only repo with code already in `terraform/`; preserve dir name |231| `base_path: "."` + `components.terraform.base_path: "components/terraform"` | Multi-toolchain or new repo; canonical Atmos layout |232233For more organization patterns, such as multi-region, multi-account, and organization234hierarchies, see the skill [atmos-design-patterns](../atmos-design-patterns/SKILL.md).235236## YAML Functions vs Gomplate Datasources237238This is a common mistake: an agent chooses a Gomplate datasource when a YAML function is safer239and clearer. Use the option in the right column:240241| Goal | Reach for (NOT this) | Use instead |242| --- | --- | --- |243| Include a file's contents | `gomplate.datasources` with file URL | `!include path/to/file` |244| Read an environment variable | `gomplate getenv "FOO"` | `!env FOO` |245| Run a shell command | Template + `gomplate exec` | `!exec "command"` |246| Read a store value | Custom datasource URL | `!store store_name component stack key` |247| Read Terraform output | Templated remote-state datasource | `!terraform.state component output` |248| Get current AWS account ID | `gomplate.datasources` AWS plugin | `!aws.account_id` |249250A YAML function checks its own types. It gives a clear error message. It works without Gomplate251turned on. It does not require the template text to stay valid YAML. Use a Go template only for252control flow, such as a conditional, a loop, or a dynamic key, that a YAML function cannot253express. See [atmos-templates](../atmos-templates/SKILL.md) for when to use a Go template.254255## What Does NOT Need to Change256257Tell the user this list first, if they are afraid of a large rewrite. None of these items must258change to adopt Atmos:259260- **Terraform code.** Providers, resources, data sources, and modules stay the same.261- **Module sources.** A local path, such as `source = "../../modules/foo"`, or a registry262 source, keeps working.263- **Backend code.** You can delete the `backend "s3" {}` block from the `.tf` files, because264 Atmos creates `backend.tf.json`. Or you can keep the block and turn off backend generation in265 `atmos.yaml`. Both methods work.266- **`.tfvars` files.** Atmos reads them through `!include`. Convert them to YAML later, only if267 the user wants deep-merge inheritance.268- **Custom provider configuration.** Providers stay in the `.tf` files. Pass environment269 variables through stack `env:`. Pass Terraform variables through stack `vars:`.270271## When to Escalate to Other Skills272273After the minimum migration works, the user will often ask what to do next. Send each question274to the correct skill:275276- **Organize many stacks**, such as by organization, tenant, account, or region. Use277 [atmos-design-patterns](../atmos-design-patterns/SKILL.md).278- **Build abstract components, inheritance, or catalog patterns.** Use279 [atmos-components](../atmos-components/SKILL.md).280- **Use deep merging, imports, or overrides.** Use [atmos-stacks](../atmos-stacks/SKILL.md).281- **Vendor third-party components.** Use [atmos-vendoring](../atmos-vendoring/SKILL.md).282- **Migrate an AWS/GCP/Azure CLI, Leapp, Granted, saml2aws, or okta-aws-cli setup.** Start with283 the matching reference in [Migrating Authentication](#migrating-authentication) above. For284 authoring new auth config beyond a migration, go straight to [atmos-auth](../atmos-auth/SKILL.md).285- **Add validation policies, such as OPA or JSON Schema.** Use286 [atmos-validation](../atmos-validation/SKILL.md).287- **Set up CI/CD with affected-component detection.** Use [atmos-ci](../atmos-ci/SKILL.md).288- **Migrate third-party GitHub Actions CI** (dflook, tfcmt, etc.) to Native CI. Use289 [to-native-ci.md](references/to-native-ci.md).290- **Share data between components through a store.** Use291 [atmos-stores](../atmos-stores/SKILL.md).292293## Anti-Patterns294295Push back if a user or another agent proposes one of these methods during migration:296297- **"You must move all Terraform into `components/terraform/` before you use Atmos."** This is298 false. That layout is a recommendation, not a requirement. Let the user pick: adopt the299 recommended layout now, or point `base_path` at the current layout and reorganize later.300- **"You must rewrite all `.tfvars` files as YAML before you run Atmos."** This is false. Native301 stack YAML is the best final format for inheritance and composition. But `!include` lets the302 user keep existing `.tfvars` files during a step-by-step migration.303- **"Delete your workspace state and start over."** This is false. Connect the existing state304 with `metadata.terraform_workspace` and the remote-state-bridge pattern.305- **"Add a Gomplate datasource for everything."** This is false. Use a YAML function first.306- **"Adopt the full multi-account organization hierarchy on day one."** This is false. Start307 with one stack file.308- **"Task-runner migration requires Terraform stacks or components."** Custom commands run general309 automation from `atmos.yaml`. Keep infrastructure adoption separate from task-runner adoption.310- **"Delete the existing task file before adopting Atmos."** Atmos can call the existing runner.311 Migrate task bodies incrementally and preserve the source tool's ordering and freshness semantics.312- **"Wrap atmos commands in a Makefile, Justfile, or Taskfile forever."** This is false. A313 wrapper is a good bridge while the user builds trust in Atmos, not the final state -- change314 each leaf target to a custom command (see Principle 7 and "Common Problems in Task-Runner315 Migration" above for the concurrency/ordering details per source tool).316317Every reference file is already linked, with its routing condition, from the "Decide the318Migration Shape First" and "Migrating Authentication" tables above -- load a reference directly319from there rather than a separate resource list.