drift

drift schedules drift detection and reconciliation in a repository that Stategraph Orchestration manages. It also sets run windows.

A drift run is a plan operation. Your workflows and hooks run for it, and plans and applies that drift starts get TERRATEAM_RUN_KIND=drift. A new or changed schedule runs immediately, inside its window if it has one.

Default Configuration

drift:
  enabled: false
  schedules: {}

Keys

Schedule

schedule is the most frequent interval, not a guarantee of when or how often drift runs. In practice, this matters only for hourly, because a drift run can take longer than an hour.

Window

For valid time zone abbreviations, see this list.

Legacy Single Schedule Form

You can also write one schedule directly under drift, with the schedule, reconcile, and tag_query keys. It is the same as a schedules entry named default, without window.

drift:
  enabled: true
  schedule: daily
  reconcile: false

Examples

Enabling Drift Detection

drift:
  enabled: true
  schedules:
    default:
      tag_query: ''
      schedule: daily

Enabling Drift Detection with Reconciliation

drift:
  enabled: true
  schedules:
    default:
      tag_query: ''
      schedule: weekly
      reconcile: true

Using Tag Queries to Limit Scope

This schedule runs hourly, only for dir:production:

drift:
  enabled: true
  schedules:
    prod:
      tag_query: 'dir:production'
      schedule: hourly

Enable Drift for Production After Work Hours and Development Any Time

Both schedules run daily. The production window is from 6pm to 7am the next day.

drift:
  enabled: true
  schedules:
    prod:
      tag_query: 'dir:production'
      schedule: daily
      window:
        start: '18:00 EST'
        end: '07:00 EST'
    dev:
      tag_query: 'dir:dev'
      schedule: daily

Notifications

Issues

To open an issue when drift detection finds changes, add this hook:

hooks:
  plan:
    post:
      - type: drift_create_issue

Orchestration does not open a second issue for the same changes. If changes are frequent, drift detection can open many issues. To reduce them, limit the scope with tag_query.

• On GitHub, the runner opens the issue with a token from the Stategraph GitHub App.
• On GitLab, the runner opens the issue in the project with an access token that you supply, and adds the terrateam and drift labels. Orchestration finds an open drift issue by these two labels, so keep both labels on it.

On GitLab, set up the token before you turn on the hook:

1. Create a project or group access token with the api scope. A personal access token with the api scope also works.
2. Open your GitLab project and go to Settings, then CI/CD, then Variables.
3. Add the token as a masked variable with the Key TERRATEAM_DRIFT_ACCESS_TOKEN.

Terraform will perform the following actions:

  # aws_security_group_rule.https will be updated in-place
  ~ resource "aws_security_group_rule" "https" {
      ~ cidr_blocks = [
          - "0.0.0.0/0",
          + "10.0.0.0/8",
        ]
        id          = "sgrule-2468013579"
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Grouping

By default, one issue lists every drifted dirspace. For one issue per drifted dirspace, set group_by: dirspace:

hooks:
  plan:
    post:
      - type: drift_create_issue
        group_by: dirspace

Use dirspace when different teams own the dirspaces, or when each dirspace needs its own triage, assignee, and closure. Each issue has the title Terrateam: Drift Detected - <dir> (<workspace>), and Orchestration deduplicates each issue on its own. A new drift run does not open an issue again when its plan output did not change.

Slack

On GitHub, send Slack notifications with the official GitHub Integration for Slack:

• Install the app in your Slack workspace and channel.
• Use the /github command to subscribe to your Terraform repository:

/github subscribe owner/repo issues

On GitLab, use the Slack integration of the project to notify a channel of new issues. Drift issues have the terrateam and drift labels.

Custom Notifications

For custom notifications or actions when drift detection finds changes, add a hook. Use it to connect drift detection to your monitoring and alerting systems:

hooks:
  plan:
    post:
      - type: run
        cmd: ['bash', '-c', '$TERRATEAM_ROOT/drift-notify.sh']

drift-notify.sh:

#!/usr/bin/env bash
set -e
if [[ "$TERRATEAM_RUN_KIND" == "drift" ]] && [[ -f "$TERRATEAM_RESULTS_FILE" ]]; then
  echo "This is a drift operation"
fi

Related

• Drift detection
• hooks
• Tag queries