Atmos Migration

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 full tutorials for end users, see:

• Migrating from Native Terraform
• Migrating from Terraform Workspaces
• Migrating from Terragrunt -- see from-terragrunt.md for agent recipes
• Migrating from Terramate -- see 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. 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.
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. 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.
7. 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:

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:

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

1. Install Atmos and create atmos.yaml in the existing project.
2. Add one custom command that calls an existing task, such as make build, just build, or task build.
3. Run atmos build and confirm it produces the same result as the original command.
4. Move task bodies into native steps as needed, preserving parameters, environments, dependency order, and freshness behavior. No stack files or Terraform changes are required.