Skip to main content

Atmos Pro

Configure Atmos Pro integration for stack locking, status reporting, and workspace management across your organization.

Overview​

Atmos Pro provides centralized management capabilities for teams using Atmos at scale:

  • Stack Locking — Prevent concurrent modifications to the same stack
  • Status Reporting — Track deployment status and history
  • Workspace Management — Organize teams and projects

Configuration​

Configure Atmos Pro in your atmos.yaml:

atmos.yaml

settings:
  pro:
    base_url: "https://app.cloudposse.com"
    endpoint: "api/v1"
    token: ""
    workspace_id: ""
    github_oidc:
      request_url: ""
      request_token: ""

Configuration Reference​

settings.pro.base_url

Base URL for the Atmos Pro API.

  • Type: string
  • Default: https://app.cloudposse.com
  • Environment Variable: ATMOS_PRO_BASE_URL
settings.pro.endpoint

API endpoint path appended to the base URL.

  • Type: string
  • Default: api/v1
  • Environment Variable: ATMOS_PRO_ENDPOINT
settings.pro.token

API authentication token for Atmos Pro. Required for authentication when not using GitHub OIDC.

  • Type: string
  • Default: (none)
  • Environment Variable: ATMOS_PRO_TOKEN
settings.pro.workspace_id

Atmos Pro workspace identifier. Required when using GitHub OIDC authentication.

  • Type: string
  • Default: (none)
  • Environment Variable: ATMOS_PRO_WORKSPACE_ID
settings.pro.github_oidc.request_url

GitHub Actions OIDC token request URL. Automatically set in GitHub Actions via the ACTIONS_ID_TOKEN_REQUEST_URL environment variable.

  • Type: string
settings.pro.github_oidc.request_token

GitHub Actions OIDC request token. Automatically set in GitHub Actions via the ACTIONS_ID_TOKEN_REQUEST_TOKEN environment variable.

  • Type: string

Environment Variables​

ATMOS_PRO_BASE_URL
Override the Atmos Pro API base URL. Maps to settings.pro.base_url.
ATMOS_PRO_ENDPOINT
Override the API endpoint path. Maps to settings.pro.endpoint.
ATMOS_PRO_TOKEN
API authentication token. Maps to settings.pro.token.
ATMOS_PRO_WORKSPACE_ID
Workspace identifier for OIDC authentication. Maps to settings.pro.workspace_id.
ATMOS_PRO_RUN_ID
CI/CD run identifier. Set automatically in CI environments for tracking.

Authentication Methods​

Atmos Pro supports two authentication methods:

Direct API Token​

Use an API token for authentication in any environment:

atmos.yaml

settings:
  pro:
    token: !env ATMOS_PRO_TOKEN

Store your token securely and pass it via environment variable:

export ATMOS_PRO_TOKEN="your-api-token"
atmos pro lock vpc -s prod/us-east-1

GitHub OIDC Token Exchange​

For GitHub Actions workflows, use OIDC token exchange for secure, token-less authentication:

atmos.yaml

settings:
  pro:
    workspace_id: "your-workspace-id"
    github_oidc:
      request_url: !env ACTIONS_ID_TOKEN_REQUEST_URL
      request_token: !env ACTIONS_ID_TOKEN_REQUEST_TOKEN

In your GitHub Actions workflow:

name: Deploy Infrastructure
on: push

permissions:
  id-token: write  # Required for OIDC token request
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy with Atmos
        run: |
          atmos pro lock vpc -s prod/us-east-1
          atmos terraform apply vpc -s prod/us-east-1
          atmos pro unlock vpc -s prod/us-east-1