Cloud Integrations
Set up your cloud environment 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 two things in your cloud environment:
- 1Terraform State Backend to store Terraform state. If you already have one, you can skip to configuring Atmos to use it.
- 2OIDC Integration with GitHub so your workflows can authenticate with your cloud provider using short-lived credentials. Static credentials are strongly discouraged.
If you already have an S3 backend for Terraform state, skip ahead to Step 2: OIDC Integration.
S3 Native Locking
Terraform 1.10+ and OpenTofu 1.8+ support native S3 state
locking via
use_lockfile: true,
eliminating the need for a DynamoDB table. All examples on this page use S3 native locking.Atmos can automatically provision your S3 state backend with secure defaults — versioning, encryption, public access blocked, and native S3 locking — without needing Terraform or CloudFormation.
Enable automatic backend provisioning in your stack configuration:
settings:
provision:
backend:
enabled: trueWith this enabled, Atmos will automatically create the S3 backend on your first
terraform init. You can also provision backends explicitly:atmos terraform backend create vpc --stack devFor complete documentation, see Automatic Backend Provisioning on the Atmos docs.
Alternatively, deploy the backend infrastructure using our CloudFormation template:
Important
Your stack name must be unique across all AWS accounts. We use the stack name as part of the S3 bucket name.
Or manually deploy 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| Parameter | Description | Default |
|---|---|---|
CreateStateBackend | Set to 'true' to create state backend resources (S3 bucket), 'false' to skip | true |
CreateGitHubAccess | Set to 'true' to create GitHub access resources (OIDC provider, IAM role), 'false' to skip | true |
CreateOIDCProvider | Set to 'true' to create the GitHub OIDC provider, 'false' to skip (if it already exists) | true |
GitHubOrg | GitHub organization or username | |
GitHubRepo | GitHub repository name. Set to * to allow all repositories | * |
To destroy the template, run:
aws cloudformation delete-stack --stack-name my-backendThis 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_STACKWarning
This will destroy the state files and empty the S3 bucket. This is a destructive action and cannot be undone.
Once your S3 backend exists, configure Atmos to use it:
terraform:
backend_type: s3
backend:
s3:
bucket: my-backend-tfstate
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 backend was deployed
remote_state_backend:
s3:
role_arn: null # Set to null to use the current AWS credentialsYour GitHub Actions workflows need credentials to access your cloud provider. The recommended approach is OIDC — your workflows exchange a short-lived GitHub token for cloud credentials, with no static secrets to manage.
Configure an Atmos auth profile to use GitHub OIDC:
auth:
providers:
github-oidc:
kind: github/oidc
region: us-east-2
spec:
audience: sts.amazonaws.com
identities:
my-org/deploy:
default: true
kind: aws/assume-role
via:
provider: github-oidc
principal:
assume_role: arn:aws:iam::123456789012:role/my-backend-github-actionsFor step-by-step instructions on setting up the IAM role and trust policy, see the Cloud Authentication page.
Learn about Auth Profiles
For OIDC setup with Azure or GCP, see the Cloud Authentication page which covers all three providers.