Update Atmos Stack Configuration

Atmos Pro works together with the Atmos CLI to deploy your stacks. Update your Atmos configuration to enable Atmos Pro.

This section assumes you are familiar with Atmos and have already been using it to deploy your stacks. If you are new to Atmos, please refer to the Atmos documentation for more information.
How it works
Each stack within your Atmos configuration file needs to be configured to use Atmos Pro. Luckily, Atmos' flexible structure with inheritance and mixins makes this easy to set reasonable defaults for every stack in your Atmos configuration and then override exceptions as needed.
stacks/mixins/atmos-pro.yaml
settings:
  pro:
    enabled: true
Then, in your stack configuration, you can simply import the atmos-pro mixin to apply the settings to all stacks.
stacks/orgs/ex1/plat/dev/us-east-2/demo.yaml
import:
  - mixins/atmos-pro
Next, in the same file, specify which workflows Atmos Pro should dispatch for your stacks. This is where you define the events and workflows that Atmos Pro will manage.
stacks/mixins/atmos-pro.yaml
settings:
  pro:
    enabled: true
    pull_request: # when a pull request...
      opened: # is opened...
        workflows:
          atmos-terraform-plan.yaml: # dispatch the atmos-terraform-plan.yaml workflow...
            inputs: # with the following inputs
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      synchronize:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      reopened:
        workflows:
          atmos-terraform-plan.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
      merged:
        workflows:
          atmos-terraform-apply.yaml:
            inputs:
              component: "{{ .atmos_component }}"
              stack: "{{ .atmos_stack }}"
At first glance, this configuration looks verbose and seems that it could be simplified by using lists rather than maps in the YAML configuration. However, we use maps because we want to be able to deep merge the configuration using atmos, and lists do not support deep merging.
In practice, we recommend to simplify the configuration by using YAML anchors.
For example:
stacks/mixins/atmos-pro.yaml
plan-wf-config: &plan-wf-config
  atmos-terraform-plan.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
 
apply-wf-config: &apply-wf-config
  atmos-terraform-apply.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
 
settings:
  pro:
    enabled: true
    pull_request:
      opened:
        workflows: *plan-wf-config
      synchronize:
        workflows: *plan-wf-config
      reopened:
        workflows: *plan-wf-config
      merged:
        workflows: *apply-wf-config
To ensure your components are deployed in the correct order, you need to define dependencies between components using the settings.depends_on section. 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 VPC is created before a database is provisioned within it, or that a Kubernetes cluster is ready before applications are deployed to it.
stacks/orgs/ex1/plat/dev/us-east-2/demo.yaml
components:
  terraform:
    api:
      settings:
        depends_on:
          "1":
            component: "database"
          "2":
            component: "cluster"
    frontend:
      settings:
        depends_on:
          "1":
            component: "api"
          "2":
            component: "cache"
    cdn:
      settings:
        depends_on:
          "1":
            component: "object-storage"
          "2":
            component: "frontend"
The settings.depends_on section is a map where the keys are descriptions or numbers that help identify the dependencies. The dependencies are processed in lexicographical order based on these keys.
Why is settings.depends_on a map instead of a list?

We use maps instead of lists because maps support deep merging in Atmos, while lists do not. This allows you to inherit and override dependencies from mixins and base configurations.

Each 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.

Ready to configure GitHub workflows?

Now that you've configured your Atmos stacks, set up your GitHub Actions workflows to work with Atmos Pro.

Configure GitHub WorkflowsLearn about Ordered Deployments
Atmos WorkspacesGitHub Workflows