Cloud Integrations

Deploy the infrastructure needed to run Terraform and Atmos workflows through Atmos Pro.

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.
  1. 1
    State Backend (S3 + DynamoDB) to store Terraform state and enable state locking.
  2. 2
    Plan File Storage (S3 + optional DynamoDB) to persist Terraform plan outputs for review and approvals.
  3. 3
    OIDC Integration with GitHub for workflows to authenticate with your cloud provider.
To make things easier, we’ve provided a CloudFormation template that sets up everything for you.
For AWS, we implement the required components for connecting Atmos Pro with a CloudFormation template that provisions a state backend, plan file storage, and GitHub Actions—using S3, DynamoDB, and a GitHub OIDC integration with IAM roles.
Deploy the complete Terraform backend infrastructure in a single CloudFormation stack:

Important

Your stack name must be unique across all AWS accounts. We use the stack name as part of the S3 bucket and DynamoDB table IDs.
Launch Stack
Or manually deploy the template with the AWS CLI:
aws cloudformation deploy \
  --stack-name my-backend \
  --template-url https://s3.amazonaws.com/cplive-core-ue2-public-cloudformation/aws-cloudformation-terraform-backend.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --no-fail-on-empty-changeset \
  --parameter-overrides GitHubOrg=my-org
ParameterDescriptionDefault
CreateStateBackendSet to 'true' to create state backend resources (S3 bucket, DynamoDB table), 'false' to skiptrue
CreatePlanFileStorageSet to 'true' to create plan file storage resources (S3 bucket, DynamoDB table), 'false' to skiptrue
CreateGitHubAccessSet to 'true' to create GitHub access resources (OIDC provider, IAM role), 'false' to skiptrue
CreateOIDCProviderSet to 'true' to create the GitHub OIDC provider, 'false' to skip (if it already exists)true
GitHubOrgGitHub organization or username
GitHubRepoGitHub repository name. Set to * to allow all repositories*
Once deployed, you will need to add the new role and plan file storage configuration to your Atmos configuration.
integrations:
  github:
    gitops:
      opentofu-version: "1.10.0"
      artifact-storage:
        region: "us-east-1" # Ensure this matches the region where the template was deployed
        bucket: "my-backend-tfplan" # Get this value from the PlanBucketName output
        table: "my-backend-tfplan" # Get this value from the PlanDynamoDBTableName output
        role: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
      role:
        plan: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
        apply: "arn:aws:iam::123456789012:role/my-backend-github-actions" # Get this value from the GitHubActionsRoleARN output
Then use the state backend with Atmos by specifying the S3 bucket and DynamoDB table.
terraform:
  backend_type: s3
  backend:
    s3:
      bucket: my-backend-tfstate # Get this value from the StateBucketName output
      dynamodb_table: my-backend-tfstate # Get this value from the StateDynamoDBTableName output
      role_arn: null # Set to null to use the current AWS credentials
      encrypt: true
      key: terraform.tfstate
      acl: bucket-owner-full-control
      region: us-east-1 # Ensure this matches the region where the template was deployed
  remote_state_backend:
    s3:
      role_arn: null # Set to null to use the current AWS credentials
To destroy the template, run:
aws cloudformation delete-stack --stack-name my-backend
This will destroy the stack and all the resources it created. However, if the S3 bucket is not empty, the stack will fail to destroy.
To destroy the stack and empty the S3 bucket, run:
aws cloudformation delete-stack --stack-name my-backend --deletion-mode FORCE_DELETE_STACK

Warning

This will destroy the state files and empty the S3 bucket. This is a destructive action and cannot be undone.
Support for other cloud providers is coming soon. Check back for guides on:
  • Google Cloud Platform (GCP) - Using Cloud Storage and Cloud KMS
  • Microsoft Azure - Using Azure Storage and Key Vault
  • HashiCorp Cloud Platform (HCP) - Using Terraform Cloud backend
Terraform & OpenTofuAtmos Docs