atmos-migration

Migrating to Atmos

Overview

This skill is a decision guide. Use it to migrate an existing Terraform repository to Atmos. Atmos can adopt an existing repository without a reorganization. The components/terraform/ layout is a recommendation. It is not a requirement. Start with the smallest change that gives value. Add more only when the user has a real need for it.

This skill also covers migrating CLI tool-version management from mise or Aqua CLI to the Atmos toolchain -- see from-mise.md and from-aqua.md in the routing table below.

For full tutorials for end users, see:

• Migrating from Native Terraform
• Migrating from Terraform Workspaces
• Migrating from Terragrunt -- see from-terragrunt.md for the agent-actionable recipes
• Migrating from Terramate -- covered by this skill via references/from-terramate.md (no atmos.tools tutorial yet)
• Migrating from Makefiles
• Migrating from Justfiles
• Migrating from Taskfile.yml

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.

1. Migration is opt-in, not all-or-nothing. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. Crawl → walk → run. Get the user to a working atmos terraform plan in 20 minutes; defer inheritance, catalogs, and multi-account hierarchies until they have a concrete need.
7. Task runners are not a blocker. Atmos custom commands and workflows can replace the targets, recipes, and tasks that Make, Just, and Task provide. This doesn't have to happen all at once — a Makefile, Justfile, or Taskfile can stay as a thin wrapper around atmos commands during migration, the same incremental approach described in Principle 6. The end state turns each leaf target into a custom command; a target chain usually stays a custom command too, using dependencies.commands/dependencies.workflows for its prerequisites. Reserve workflows for fixed, multi-step orchestration across more than one component — not every dependency chain needs one.