Drift Detection

Drift detection identifies when your deployed infrastructure no longer matches your Terraform configuration. Atmos Pro provides automated drift detection with scheduled scans, detailed reports, and remediation workflows — all integrated into your existing GitOps process.

What You'll Configure

• GitHub workflow to upload instance list to Atmos Pro
• Atmos stack settings for drift detection and remediation
• Scheduled drift detection runs

What is Infrastructure Drift?

Infrastructure drift occurs when the actual state of your cloud resources diverges from the desired state defined in your Terraform code. This can happen for several reasons:

1. Manual Changes — Someone modifies resources directly in the cloud console
2. External Automation — Other tools or scripts modify resources outside of Terraform
3. Provider Updates — Cloud provider changes default values or resource behavior
4. Incomplete Applies — Terraform runs that fail partway through

Undetected drift creates significant risks including security vulnerabilities, compliance violations, deployment failures, and operational confusion as teams lose confidence in their infrastructure code as the source of truth.

How Drift Detection Works

Drift detection in Atmos Pro involves three coordinated workflows:

1. Instance Registration

First, Atmos Pro needs to know what instances (component + stack combinations) exist in your infrastructure. The list-instances workflow uploads this inventory to Atmos Pro.

This workflow runs on a schedule (e.g., nightly) or on-demand to keep the instance list current when components are added or removed.

2. Drift Detection

When a drift detection run is triggered from Atmos Pro, it dispatches the detect workflow for each registered instance. This workflow runs terraform plan and reports the results back to Atmos Pro.

Instances with detected changes are marked as "drifted" in the Atmos Pro dashboard.

3. Remediation

For any drifted instance, you can trigger remediation directly from the Atmos Pro UI. This dispatches the remediate workflow, which runs terraform apply to restore the desired state.

Configuration

1 Add the List Instances Workflow

Add this workflow to your infrastructure repository. It runs on a schedule to keep Atmos Pro's instance registry current.

.github/workflows/atmos-pro-list-instances.yaml

name: 👽 Atmos Pro List instances
run-name: list instances

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

# Avoid running the same stack in parallel mode (from different workflows)
# This applied to across workflows to both plan and apply
concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: false

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

jobs:
  atmos-list-instances:
    name: list instances

    runs-on:
      - "runs-on=${{ github.run_id }}"
      - "runner=small"
      - "tag=list-instances"
      - "private=false"

    steps:
      - uses: runs-on/action@v1
      - uses: unfor19/install-aws-cli-action@v1

      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set atmos cli config path vars
        shell: bash
        run: |-
          echo "ATMOS_CLI_CONFIG_PATH=$(realpath ${{ vars.ATMOS_CONFIG_PATH }})" >> $GITHUB_ENV

      - name: Install Atmos
        uses: cloudposse/github-action-setup-atmos@v2
        with:
          atmos-version: ${{ vars.ATMOS_VERSION }}
          token: ${{ github.token }}
          install-wrapper: false

      # We need to assume AWS credentials to read the Terraform state
      - name: Assume Planner Role
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: "us-east-1"
          role-to-assume: "arn:aws:iam::333333333333:role/acme-core-gbl-auto-planner"
          role-session-name: "atmos-pro-list-instances"
          mask-aws-account-id: "no"

      - name: List instances and upload to Atmos Pro
        env:
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
          ATMOS_PROFILE: "github-plan"
        run: |
          atmos list instances \
            --upload

Update the IAM Role ARN

Update the role-to-assume with your actual planner role ARN. The workflow needs read access to Terraform state to enumerate instances.

2 Configure the Plan Workflow for Drift Detection

The existing atmos-pro-terraform-plan.yaml workflow already supports drift detection through the upload_status input. When upload_status: true, the plan results are uploaded to Atmos Pro for drift tracking.

.github/workflows/atmos-pro-terraform-plan.yaml

name: 👽 Atmos Pro Terraform Plan
run-name: plan ${{ inputs.component }}/${{ inputs.stack }}/${{ inputs.atmos_pro_run_id}}

on:
  workflow_dispatch:
    inputs:
      atmos_pro_run_id:
        description: "Atmos Pro Run ID"
        type: string
      sha:
        description: "Commit SHA"
        type: string
      component:
        description: "Component"
        required: true
        type: string
      stack:
        description: "Stack"
        required: true
        type: string
      upload_status:
        description: "Upload status to Atmos Pro"
        required: false
        type: boolean
        default: false

# Avoid running the same stack in parallel mode (from different workflows)
# This applied to across workflows to both plan and apply
concurrency:
  group: "${{ inputs.stack }}-${{ inputs.component }}"
  cancel-in-progress: false

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

jobs:
  atmos-plan:
    name: ${{ inputs.component }}-${{ inputs.stack }}

    runs-on:
      - "runs-on=${{ github.run_id }}"
      - "runner=terraform"
      - "tag=${{ inputs.component }}-${{ inputs.stack }}"
      - "private=false"

    steps:
      - uses: runs-on/action@v1
      - uses: unfor19/install-aws-cli-action@v1

      - name: Plan Atmos Component
        uses: cloudposse/github-action-atmos-terraform-plan@v5
        env:
          ATMOS_PROFILE: "github-plan"
          ATMOS_PRO_WORKSPACE_ID: ${{ vars.ATMOS_PRO_WORKSPACE_ID }}
        with:
          # Atmos Pro args
          component: ${{ inputs.component }}
          stack: ${{ inputs.stack }}
          sha: ${{ inputs.sha }}
          # Upload the status to Atmos Pro
          atmos-pro-upload-status: ${{ inputs.upload_status }}
          # Atmos required configuration
          atmos-version: ${{ vars.ATMOS_VERSION }}
          atmos-config-path: ${{ vars.ATMOS_CONFIG_PATH }}

Key parameters for drift detection:

• upload_status — When true, uploads plan results to Atmos Pro (used by detect workflow)
• atmos-pro-upload-status — The GitHub Action input that enables status upload

3 Configure Atmos Stack Settings

Add drift detection configuration to your Atmos stack defaults. This tells Atmos Pro which workflows to dispatch for detection and remediation.

stacks/orgs/acme/_defaults.yaml

vars:
  namespace: acme

# Workflow configuration anchors for reuse
plan-wf-config: &plan-wf-config
  atmos-pro-terraform-plan.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"

apply-wf-config: &apply-wf-config
  atmos-pro-terraform-apply.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
      github_environment: "{{ .vars.tenant }}-{{ .vars.stage }}"

# Drift detection uses the plan workflow with upload_status enabled
detect-wf-config: &detect-wf-config
  atmos-pro-terraform-plan.yaml:
    inputs:
      component: "{{ .atmos_component }}"
      stack: "{{ .atmos_stack }}"
      upload_status: true

settings:
  pro:
    enabled: true
    # Standard PR workflows
    pull_request:
      opened:
        workflows: *plan-wf-config
      synchronize:
        workflows: *plan-wf-config
      reopened:
        workflows: *plan-wf-config
      merged:
        workflows: *apply-wf-config
    # Drift detection configuration
    drift_detection:
      enabled: true
      detect:
        workflows: *detect-wf-config
      remediate:
        workflows: *apply-wf-config

Key configuration:

• detect.workflows — Uses the plan workflow with upload_status: true to report drift
• remediate.workflows — Uses the apply workflow to fix drift (same as PR merge workflow)

4 Configure Repository Permissions

Drift detection requires additional repository permissions in Atmos Pro:

1. Go to atmos-pro.com and log in to your organization
2. From the dashboard, select your infrastructure repository
3. Click Quick Actions in the top right corner
4. Select Repository Permissions
5. Add the following permissions:

• Instances Create — Allows the list-instances workflow to register new instances
• Instances Update — Allows drift detection to update instance status

5 Configure Drift Detection Schedule

Create a drift detection schedule in the Atmos Pro dashboard:

1. Go to atmos-pro.com and log in to your organization
2. From the dashboard, select your infrastructure repository
3. Click Quick Actions in the top right corner
4. Select Schedule Drift Detection
5. Configure the schedule frequency and save

Common schedule frequencies:

• Weekly — Run once a week to audit infrastructure drift (recommended for most teams)
• Daily — Run nightly for environments requiring tighter compliance

Pausing Schedules

Drift detection schedules can be paused and resumed at any time from the same Quick Actions menu. This is useful during planned maintenance windows or major migrations.

Workflow Summary

Workflow	Purpose	Trigger	Frequency
atmos-pro-list-instances.yaml	Upload instance inventory	Schedule + on-demand	Nightly or weekly
atmos-pro-terraform-plan.yaml	Detect drift (with upload_status)	Atmos Pro dispatch	Per drift detection run
atmos-pro-terraform-apply.yaml	Remediate drift	Atmos Pro dispatch	On-demand from UI

Operational Workflow

The intended operational workflow for drift detection:

1. List instances runs on schedule — Keeps Atmos Pro's instance registry current (e.g., nightly)
2. Drift detection runs on schedule — Scans all instances for drift (e.g., weekly)
3. Review drifted components — Audit the list of drifted instances in Atmos Pro dashboard
4. Remediate on demand — Fix individual drifted components from the UI as needed

This approach provides regular visibility into infrastructure drift while allowing controlled, deliberate remediation rather than automatic fixes.

Troubleshooting

No instances appearing in Atmos Pro

• Verify the atmos-pro-list-instances.yaml workflow is running successfully
• Check that ATMOS_PRO_WORKSPACE_ID is set in your repository variables
• Ensure the IAM role has permissions to read Terraform state

Drift detection not running

• Verify settings.pro.drift_detection.enabled: true in your stack defaults
• Check that the drift detection schedule is configured in Atmos Pro
• Ensure the detect workflow configuration matches your actual workflow filename

Remediation failing

• Verify the remediate workflow configuration matches your apply workflow
• Check that GitHub environments are properly configured for protected stages
• Review the GitHub Actions logs for specific errors

Next Steps

Atmos Pro is fully configured! Continue with deploying the database layer—create a PR and let Atmos Pro handle the planning and deployment! Provision Databases