Configure Atmos Stacks
Configure your Atmos stacks to work with Atmos Pro. Start with a basic stack definition and add workflow dispatches, dependencies, and CI integration.
Atmos Pro reads your Atmos stack configuration to determine which components to deploy, in what order, and which workflows to dispatch. This page walks you through configuring your stacks for Atmos Pro.
If you're new to Atmos, start by creating a basic stack configuration. A stack defines what to deploy and where.
Each stack file lives in
stacks/ and has a name at the top that uniquely identifies the stack, followed by the components (Terraform root modules) to deploy:name: dev
components:
terraform:
vpc:
vars:
cidr_block: "10.0.0.0/16"
region: us-east-1
eks:
vars:
cluster_version: "1.29"
instance_types:
- t3.largeThe top-level
name identifies this stack. Component names (vpc, eks) are simple—they reference Terraform root modules in your components/terraform/ directory. Atmos Pro tracks each component/stack pair (e.g., vpc in dev) across plan, apply, and drift detection.For a step-by-step guide on adopting Atmos, see the migration guide. For complete documentation, see the Atmos Stacks documentation.
Add
settings.pro to your stack configuration to enable Atmos Pro. This tells Atmos Pro which workflows to dispatch for each event (pull request, merge, release) and enables features like drift detection.We recommend creating a mixin so you can apply the same Atmos Pro settings to all your stacks:
plan-wf-config: &plan-wf-config
atmos-terraform-plan.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
drift-detection-wf-config: &drift-detection-wf-config
atmos-terraform-plan.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
upload: "true"
apply-wf-config: &apply-wf-config
atmos-terraform-apply.yaml:
inputs:
component: "{{ .atmos_component }}"
stack: "{{ .atmos_stack }}"
github_environment: "{{ .vars.tenant }}-{{ .vars.stage }}"
settings:
pro:
enabled: true
drift_detection:
enabled: true
detect:
workflows: *drift-detection-wf-config
remediate:
workflows: *apply-wf-config
pull_request:
opened:
workflows: *plan-wf-config
synchronize:
workflows: *plan-wf-config
reopened:
workflows: *plan-wf-config
merged:
workflows: *apply-wf-config
release:
released:
workflows: *apply-wf-configThis mixin defines three workflow configurations using YAML anchors to avoid repetition. The
plan-wf-config dispatches a plan workflow, the drift-detection-wf-config dispatches a plan with the upload input set to "true" so results are captured, and the apply-wf-config dispatches an apply workflow with a github_environment input for deployment protection rules.Then, in your stack configuration, import the mixin to apply the settings to all stacks:
name: dev
import:
- mixins/atmos-pro/default
components:
terraform:
vpc:
vars:
cidr_block: "10.0.0.0/16"
region: us-east-1To ensure your components are deployed in the correct order, define dependencies between components using the
dependencies.components list. This is crucial for complex environments where certain components must be available before others can be deployed.For example, you might need to ensure that a database is created before an API is provisioned, or that a frontend is ready before a CDN is configured to serve it.
components:
terraform:
api:
dependencies:
components:
- component: database
- component: cluster
vars:
database_id: !terraform.state database ".database_id // \"mock-database-id\""
cluster_id: !terraform.state cluster ".cluster_id // \"mock-cluster-id\""Here is a fuller example showing multiple components with their dependency chains:
components:
terraform:
api:
dependencies:
components:
- component: database
- component: cluster
frontend:
dependencies:
components:
- component: api
- component: cache
cdn:
dependencies:
components:
- component: object-storage
- component: frontendEach dependency object can specify:
component(required)- The name of the component this component depends on
namespace(optional)- If the component is in a different organization
tenant(optional)- If the component is in a different organizational unit
environment(optional)- If the component is in a different region
stage(optional)- If the component is in a different account
If no context variables are provided, the dependency is assumed to be within the same stack. You can also specify dependencies across different stacks by providing the appropriate context variables.
For more detailed information about configuring dependencies, refer to the Atmos documentation on dependencies. You can also use the
atmos describe dependents command to explore dependency relationships in your configuration.Configure the
ci block in your atmos.yaml to control how Atmos integrates with your CI environment. This block enables features that export plan data, write summaries, and post commit status checks.ci:
enabled: true
output:
enabled: true
summary:
enabled: true
checks:
enabled: true
context_prefix: ""
statuses:
component: true
add: true
change: true
destroy: trueEach sub-feature controls a specific CI integration:
output— When enabled, exports variables to$GITHUB_OUTPUTso downstream steps in your workflow can reference plan results (e.g., whether changes were detected).summary— When enabled, writes a formatted plan summary to$GITHUB_STEP_SUMMARY, which GitHub renders directly on the workflow run page.checks— When enabled, posts commit status checks to the pull request. Thecontext_prefixlets you namespace the check names, and thestatusesmap controls which check types are reported:componentfor per-component status, andadd,change,destroyfor resource-level operation statuses.
Next: Configure Toolchain
Set up Atmos Toolchain to manage tool versions across your team and CI pipelines.