Configure Atmos Stacks
Configure your Atmos stacks to work with Atmos Pro. Start with a basic stack definition and add workflow dispatches and component dependencies.
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.The workflow filename keys (e.g.,
atmos-terraform-plan.yaml, atmos-terraform-apply.yaml) are significant — Atmos
Pro uses them to determine the command type (plan, apply, detect, remediate) for each deployment. Use descriptive
filenames that include the command keyword. See Workflow Naming
Conventions for details.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.All dependencies in Atmos are explicit — Atmos does not infer deployment order from remote state references or any
other implicit relationships. You must declare every dependency in the
dependencies.components list for Atmos Pro to
orchestrate the correct deployment order.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: clusterHere 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.Next: Configure Atmos CI
Set up Atmos native CI integration to automatically update commit statuses, create job summaries, and export plan results.