Terraform orchestration: plan/apply/deploy, workspace management, backend config, varfile generation, authentication
Atmos wraps the Terraform CLI to provide stack-aware orchestration of infrastructure operations. Instead of manually managing workspaces, backends, variable files, and authentication for each Terraform component, Atmos resolves the full configuration from stack manifests and handles all of these concerns automatically.
When you run any atmos terraform command, Atmos performs the following sequence:
backend.tf.json file in the component directory with the
correct backend settings (S3 bucket, key, region, etc.) derived from the stack config.terraform.tfvars.json file containing all vars defined for the
component in the stack.provision.backend.enabled: trueterraform init -- Initializes the working directory with the generated backend config. Cleans
.terraform/environment first and optionally adds -reconfigure.terraform plan, apply, destroy, etc. with the generated
varfile and any additional flags.This means a single command like atmos terraform plan vpc -s plat-ue2-dev replaces what would normally
require multiple manual steps: configuring the backend, writing tfvars, running init, selecting the workspace,
and then running plan.
Generates a Terraform execution plan showing what changes would be made.
atmos terraform plan <component> -s <stack>
By default, Atmos saves the plan to a file using the naming convention <context>-<component>.planfile.
This planfile can later be used with --from-plan to apply the exact reviewed changes.
# Basic plan
atmos terraform plan vpc -s plat-ue2-dev
# Skip planfile generation (useful for Terraform Cloud)
atmos terraform plan vpc -s dev --skip-planfile
# Plan with custom output path
atmos terraform plan vpc -s dev -out=/tmp/my-plan.tfplan
# Plan only specific resources
atmos terraform plan vpc -s dev -target=aws_subnet.private
Applies Terraform changes. Supports interactive approval, planfile-based apply, and auto-approve.
atmos terraform apply <component> -s <stack>
# Interactive apply (prompts for confirmation)
atmos terraform apply vpc -s plat-ue2-dev
# Apply from a previously generated plan
atmos terraform plan vpc -s dev
atmos terraform apply vpc -s dev --from-plan
# Apply a specific planfile
atmos terraform apply vpc -s dev --planfile /tmp/my-plan.tfplan
# Auto-approved apply (no confirmation prompt)
atmos terraform apply vpc -s dev -auto-approve
Combines plan and apply with automatic approval. This is the most common command for CI/CD pipelines.
atmos terraform deploy <component> -s <stack>
Key differences from apply:
-auto-approve -- no interactive confirmation--deploy-run-init to control whether init runs# Deploy a component
atmos terraform deploy vpc -s plat-ue2-dev
# Deploy from a previously generated plan
atmos terraform deploy vpc -s dev --from-plan
# Deploy a specific planfile
atmos terraform deploy vpc -s dev --planfile /tmp/vpc-plan.tfplan
Destroys all resources managed by a component in a stack.
atmos terraform destroy <component> -s <stack>
# With auto-approve (use with extreme caution)
atmos terraform destroy vpc -s dev -auto-approve
# Targeted destroy
atmos terraform destroy vpc -s dev -target=aws_instance.web
Initializes the Terraform working directory. Atmos runs this automatically before plan, apply, and deploy, so manual invocation is rarely needed.
atmos terraform init <component> -s <stack>
# Reconfigure the backend
atmos terraform init vpc -s dev -reconfigure
# Upgrade provider plugins
atmos terraform init vpc -s dev -upgrade
# Migrate state between backends
atmos terraform init vpc -s dev -migrate-state
Atmos supports executing Terraform commands across multiple components simultaneously using filter flags.
These work with plan, apply, and deploy.
# All components in all stacks
atmos terraform plan --all
# All components in a specific stack
atmos terraform plan --stack prod
# Specific components across stacks
atmos terraform deploy --components vpc,eks
# Only components affected by git changes (in dependency order)
atmos terraform deploy --affected
# Affected with dependents included
atmos terraform deploy --affected --include-dependents
# Filter by YQ query expression
atmos terraform plan --query '.vars.tags.team == "eks"'
# Combine filters
atmos terraform plan --affected --stack prod
# Always preview first with --dry-run
atmos terraform deploy --all --dry-run
Atmos calculates Terraform workspace names from stack context variables and automatically manages workspace selection. When you run any terraform command, Atmos:
terraform init -reconfigureterraform workspace select (or creates it with terraform workspace new
if it does not exist)You can also manage workspaces explicitly:
atmos terraform workspace vpc -s plat-ue2-dev
The recommended approach for stable workspace keys uses metadata.name: