Drift

Drift detection in Terrateam runs a plan operation against all dirspaces in a repository. If changes are found, a GitHub Issue in the repository is automatically created. Reconciliation can optionally be enabled to automatically apply the changes.

Configuration

Drift detection is configured in the .terrateam/config.yml file under the drift key. Here’s the default configuration:

drift:
  enabled: false
  reconcile: false

Drift options

The drift section has the following options:

Key	Type	Description
enabled	Boolean	Specifies whether drift detection is enabled. If set to false, drift detection and reconciliation will not run. Default is false.
schedule	String	The interval to run drift detection and reconciliation: hourly, daily, weekly, monthly.
reconcile	Boolean	Specifies whether reconciliation is enabled. Default is false.
tag_query	String	Limit which directories are run with a tag query. Default is "".

Examples

Enabling drift detection

drift:
  enabled: true
  schedule: daily

This configuration will enable drift detection and run it on a daily schedule.

Enabling drift detection with reconciliation

drift:
  enabled: true
  reconcile: true
  schedule: weekly

This configuration will enable drift detection with automatic reconciliation and run it on a weekly schedule.

Limiting drift detection to specific directories

drift:
  enabled: true
  schedule: hourly
  tag_query: "dir:production"

This configuration will enable drift detection, run it on an hourly schedule, and limit it to directories tagged with dir:production.

Schedule

The schedule key can be set to one of the following values:

• hourly
• daily
• weekly
• monthly

There is no default value for schedule, and this key is required when drift detection is enabled.

Reconciliation

The reconcile key enables or disables automatic reconciliation. When enabled, if changes are found during drift detection, an apply operation will automatically run against the generated Terraform plan to reconcile the infrastructure state.

Notifications

GitHub Issues

If changes are found during drift detection, a GitHub Issue can be automatically created by adding the following configuration:

hooks:
  plan:
    post:
      - type: drift_create_issue

Duplicate issues for identical changes will not be created.

Slack

You can create Slack notifications using the official GitHub integration for Slack:

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

   /github subscribe owner/repo issues

Custom notifications

To create custom notifications or actions when drift detection finds changes, you can implement a custom hook using the Terrateam configuration file.

Hooks

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

Example notification script

#!/usr/bin/env bash
set -e
if [[ "$TERRATEAM_RUN_KIND" == "drift" ]] && [[ -f "$TERRATEAM_RESULTS_FILE" ]]; then
  jq < "$TERRATEAM_RESULTS_FILE"
fi

Considerations

When configuring drift detection in your Terrateam configuration, keep the following in mind:

• Drift detection operations are equivalent to plan operations. Existing workflows and hooks run for all drift detection operations.
• The following environment variable is defined for plan and apply operations initiated by drift detection:
  • TERRATEAM_RUN_KIND=drift
• If reconciliation is enabled, changes will be automatically applied without manual review or approval. Ensure that you have appropriate safeguards and testing in place before enabling automatic reconciliation.
• Drift detection can generate a significant number of GitHub Issues if changes are frequently detected. Consider using appropriate filters, such as the tag_query option, to limit the scope of drift detection and reduce noise.
• Custom notifications and actions can be implemented using hooks and scripts to integrate drift detection with your existing monitoring and alerting systems.