How it Works

In this section, we'll discuss how Atmos Pro works with Github Actions to deploy your Atmos stacks in a specific order. We will discuss how it all works in this section and will walk you through the steps needed to configuration Atmos Pro in the next section.

Atmos Pro can be configure to run workflows in many different ways, but in order to explain how it works, we'll use the following example:

If this isn't the workflow you're looking for, we'll demonstrate how to configure Atmos Pro for different scenarios in the next section, but for now, let's focus on the workflow we just described.

Code is Pushed to a Feature Branch

The process starts when developer makes some changes to the Atmos stacks or terraform modules in their infrastructure repository, opens a feature branch, and pushes the code changes to the feature branch.

Determine Affected Stacks

When code is pushed to a branch, Cloud Posse's Atmos Affected Stacks GitHub Action runs the atmos describe affected command to determine which stacks are affected by the code change.

Stacks are considered affected if their configuration changes, if there are any changes to the terraform code they are using, if any global configuration is changed, or if the stack is dependent on another stack that is affected.

Affected Stacks Upload

Once the affected stacks have been determined, the GitHub Action uploads the list affected stacks to the Atmos Pro API. The app then processes the list of affected stacks and determines the order in which stacks need to be deployed.

Atmos Pro API Key

In order for Atmos Pro to be able to securely upload the list of affected stacks to the Atmos Pro API, you will need to create an API key for your workspace. You can do this by clicking the API Keys link in the Atmos Pro UI.

Once you have created an API key, you will need to add it to your Github repository as a secret. You can do this by following the GitHub documentation.

And passing it to the Atmos Pro GitHub Actions workflow as an input.

jobs:
  affected:
    name: Determine Affected Stacks
    runs-on:
      - "ubuntu-latest"
    steps:
      - name: Determine Affected Stacks
        id: affected
        uses: cloudposse/github-action-atmos-affected-stacks@feature/add-atmos-pro-upload
        with:
          atmos-version: ${{ vars.ATMOS_VERSION }}
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}
          atmos-pro-upload: true
          atmos-pro-token: ${{ secrets.ATMOS_PRO_TOKEN }}
          head-ref: ${{ github.event.pull_request.head.sha }}

Github Workflow Dispatch (Root Stacks)

Each top-level, or Root Stack (a stack that is not dependent on another affected stack) is dispatched to a separate workflow run. For the purposes of this example, we'll use the atmos-terraform-plan workflow but, which workflow runs and its inputs are fully user configurable.

The workflow runs the atmos terraform plan to produce a Terraform plan file for the stack.

Github Workflow Dispatch (Child Stacks)

Atmos Pro is notified by Github Webhooks when a stack has been dispatched, is running, or has completed. Once a stack completes, then the first level of dependent stacks, or Child Stacks, are dispatched to separate workflow runs. This process continues until all levels of dependent stacks have been dispatched.

Pull Request Merged

Once the feature branch is merged into the main branch, the Atmos Pro GitHub App will again run the atmos describe affected command and upload its list of affected stacks to the Atmos Pro API. The app then goes through the process again of determining the order in which stacks need to be deployed and dispatches each stack to separate workflow runs.

This time, we'll use atmos-terraform-apply workflow as an example but, again, which workflow runs and its inputs are fully user configurable.

The workflow runs the atmos terraform apply to apply the Terraform the stack. You will also notice that the workflow is configured to take environment as an input. This is the GitHub environment that the stack is being deployed to. In our example workflow, we are requiring approvals for the production environment using GitHub's built-in Deployment Protection Rules.

Status Reporting

Finally, through the entire process, Atmos Pro creates and updates a comment on the Pull Request with a list of all affected stacks, dependency graph and current status of each dispatched stack.

Next steps

Now that you've learned how Atmos Pro works, you can start using Atmos Pro to deploy your Atmos stacks. To learn more about how to configure Atmos to support Atmos Pro, click the Atmos Configuration link below.