Skip to main content
Terraform Cloud’s Drift Detection feature, introduced in mid-2022, continuously monitors your infrastructure for out-of-band changes. By comparing your deployed resources against your version-controlled Terraform code, it helps ensure your environments stay in sync.

​
Prerequisites and Licensing

Terraform Cloud Drift Detection requires a Business Tier license. If you’re evaluating this feature, ensure your organization has the correct plan.

​
Overview of Workspaces and Health Status

From the Terraform Cloud UI, you can quickly see which workspaces are “Errored,” “Applied,” or have drift:
The image shows a webpage about "Drift Detection" in Terraform, featuring a list of workspaces with their statuses, such as "Errored" and "Applied." The interface includes options for filtering and sorting the workspaces.

​
Enable Drift Detection

You can enable health assessments — including drift detection — either globally or per workspace.
  1. Navigate to Settings in your organization.
  2. Select Health and choose your preferred scope.
The image shows a settings page for "Health" in Terraform Cloud, where users can enable health assessments across all workspaces or set them per workspace. There is a button to update settings and a navigation menu on the left.
In this demo, we’ve enabled health checks at the workspace level. Open the Clumsy Bird workspace to confirm its current status. A recent plan and apply completed with no drift:
The image shows a Terraform Cloud workspace interface with a completed run for deleting a file named "security-groups.tf." The plan finished with no changes needed, and the infrastructure matches the configuration.
Once enabled, you’ll see a new Drift section in the workspace sidebar:
The image shows a settings page for a Terraform workspace, with options for sharing, health assessments, and user interface preferences. A success message indicates the workspace settings have been saved.

​
Verifying the Baseline State

Before simulating drift, confirm that your deployed infrastructure matches code. For example, check your AWS EC2 dashboard for the Clumsy Bird instance:
The image shows an AWS EC2 dashboard with a running instance named "my-app-dev-clumsy-bird-development-instance." The instance details and tags are displayed, including information like owner, project, and environment.

​
Simulate Drift

In the AWS Console, modify the Environment tag from development to production:
The image shows an AWS EC2 management interface where tags are being assigned to an instance, with fields for "Owner," "Project," "Name," and "Environment."
After saving, Terraform Cloud’s periodic health assessment will detect this change. You can filter by Drift on the workspace dashboard:
The image shows a dashboard interface for managing workspaces, with options to filter by status and a list of workspaces with their current status, repository, and latest change information.
The first health assessment typically runs 24 hours after your last active Terraform run. Learn more in the Health Assessment Scheduling documentation.
The image is a webpage from HashiCorp Terraform discussing "Health Assessment Scheduling," detailing how the timing of health assessments in a workspace depends on active Terraform runs. It explains different scenarios for scheduling and the behavior of Terraform Cloud during health assessments.

​
Detecting and Reviewing Drift

Once the assessment completes, Terraform Cloud will highlight any discrepancies. In the Clumsy Bird workspace, drift is detected and detailed under the Health tab:
The image shows a Terraform Cloud interface indicating a drift detection in a workspace, with details of changes in an AWS instance's configuration, such as IAM instance profile and public IP.

​
Handling Detected Drift

Terraform Cloud offers two primary options:
MethodDescription
Accept the driftRun a Refresh State plan to update Terraform’s state file without changing code.
Override the driftExecute a standard Plan and Apply to revert the infrastructure back to match your code.
Example of a detected drift diff: 
aws aws_instance.clumsy_bird :
  iam_instance_profile :
    id : 
    public_ip : 
  tags :
    Environment : "development-manual-change"
  tags.all :
    Environment :
      "development" : "development-manual-change"

​
Accepting the Drift

Click Start New Run and select Refresh State. This updates the Terraform state to reflect the manual change.

​
Overriding the Drift

Select the usual Plan and Apply workflow to revert the tag back to development:
The image shows a Terraform Cloud workspace interface where a plan is currently running, indicating that the infrastructure matches the configuration. The sidebar includes options like Overview, Runs, States, Variables, Health, and Settings.
After completion, verify in the AWS Console that the Environment tag is back to development. The Health tab will now show No drift detected.

​
Configuring Drift Notifications

Stay informed by setting up notifications under Notifications. For example, send an email or Slack message whenever drift is detected:
The image shows a Terraform Cloud workspace overview for "devops-aws-myapp-dev," displaying details of the latest run, including resources, outputs, and health metrics. The run was triggered via the UI, with policy checks passed and no estimated cost change.
Choose Health events and enable Drift detected:
The image shows a user interface for setting up notifications, with options to send messages via Webhook, Email, Slack, or Microsoft Teams. It includes fields for entering a name, webhook URL, and token.
Specify your email recipients or Slack channel:
The image shows a notification settings page for a workspace, allowing users to select email recipients and choose specific health and run events for which they want to receive notifications. Options include "Check failed," "Drift detected," and "Health assessment errored."

​
Summary

Terraform Cloud Drift Detection (Business Tier) ensures your infrastructure matches your code by:

Watch Video

Practice Lab