Skip to main content
Sponsor @cloudposse

Deploy with Atmos and Terraform

Verify and complete the AWS infrastructure setup for Atmos Pro using Atmos and Terraform. This approach checks your existing backend infrastructure and deploys the additional resources needed for plan file storage and GitHub OIDC integration.

You will learn

  • Verify existing Terraform backend infrastructure (S3 + DynamoDB)
  • Deploy new S3 bucket and DynamoDB table for plan file storage
  • Ensure GitHub OIDC integration is properly configured
  • Create IAM roles for GitHub Actions authentication

Overview​

Atmos Pro doesn't run Terraform or Atmos itself. It dispatches GitHub Actions that you control. To run Terraform in those GitHub Actions, you need to set up a few things in your cloud environment:

  • State Backend (S3 + DynamoDB) to store Terraform state and enable state locking
  • Plan File Storage (S3 + DynamoDB) to persist Terraform plan outputs for review and approvals
  • OIDC Integration with GitHub for workflows to authenticate with your cloud provider

This deployment method verifies your existing backend infrastructure (which should already be deployed as part of the reference architecture) and deploys the additional resources needed for plan file storage and GitHub OIDC integration.

Quick Start​

Steps
1. Vendoratmos workflow vendor -f gitops
2. Deployatmos workflow deploy/all -f gitops
GitOps Terminology

Currently, the workflows use the terminology "gitops". In the future, we plan to replace this with "atmos-pro".

Requirements​

1 Authentication Prerequisites​

The GitHub Action workflows expect the gitops AWS Team to be properly setup and connected to GitHub OIDC. This component should already be deployed with aws-teams/aws-team-roles and github-oidc-provider respectively. Verify the following to complete the authentication prerequisites.

Trusted GitHub Repos

By default in the Reference Architecture, the trusted_github_repos input is commented out for aws-teams. Now is the time to uncomment those lines. Please see stacks/catalog/aws-teams.yaml

  • The gitops Team is defined and deployed by aws-teams
  • The team has trusted relationships with the infrastructure repo via trusted_github_repos Capitalization matters! In the reference architecture, these values are initially commented out and will need to be updated with your specific repository information: 
    components:
      terraform:
        aws-teams:
          vars:
            trusted_github_repos:
              gitops:
                - "acme/infra:main"
  • The aws-team-roles default catalog allows the gitops team to assume the terraform role
  • github-oidc-provider is deployed to the account where Atmos Pro infrastructure will be created
  • The workflows have adequate permission
GitHub Workflow Permissions

In order to assume GitHub OIDC roles, a workflow needs the following:

permissions:
  id-token: write # This is required for requesting the JWT
  contents: read # This is required for actions/checkout

How To Setup​

1 Vendor Components​

The gitops stacks depends on components that may already exist in your component library (s3-bucket and dynamodb) and adds new components to manage the GitHub OIDC access. Vendor these components either with the included Atmos Workflows or using Atmos Vendoring.

vendor:
These are the commands included in the vendor workflow in the examples/snippets/stacks/workflows/gitops.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

2 Deploy Atmos Pro Infrastructure​

Deploy the Atmos Pro infrastructure components with the following workflow:

deploy/all:
These are the commands included in the deploy/all workflow in the examples/snippets/stacks/workflows/gitops.yaml file:
    No commands found

Too many commands? Consider using the Atmos workflow! 🚀

Review​

Congratulations! The Atmos components have now verified and deployed:

  • Verified existing Terraform backend infrastructure (S3 bucket and DynamoDB table for state)
  • Deployed new S3 bucket to store Terraform plan files
  • Deployed new DynamoDB table for managing plan files
  • Ensured GitHub OIDC provider is properly configured
  • Created IAM roles for GitHub Actions authentication

You're now ready to start using Atmos Pro with GitHub Actions.