»Drift Detection

Infrastructure drift means that your real-world infrastructure no longer matches the configuration in your Terraform state file. Drift occurs when a user modifies resources outside of the Terraform workflow. For example, a colleague may update resource configuration directly in the cloud provider console during a production incident, changing the resource attributes from those in tracked in your state file.

Hands On: Try our Manage Resource Drift tutorial on HashiCorp Learn to review how to detect and resolve drift.

Drift detection is a workspace-level setting. When enabled, Terraform Cloud will automatically run a drift detection assessment for that workspace every 24 hours. The assessment checks the actual settings of your infrastructure against those tracked in your workspace's state file.

»Requirements

Drift detection requires the following settings on your workspace:

• Terraform version 0.15.4+
• Remote execution mode or Agent execution mode for Terraform runs

»Enable Drift Detection

To enable drift detection within a workspace:

1. Verify that the workspace satisfies the requirements.
2. Go to the workspace and click Settings > General.
3. Select Enable under Drift Detection.
4. Click Save settings.

»Drift Detection Assessment Scheduling

If there are no active Terraform runs in the workspace, Terraform Cloud starts a drift detection assessment as soon as you enable the feature. If you enable drift detection during a speculative plan, Terraform Cloud will start drift detection soon after that plan's completion. If you enable drift detection during other types of runs, Terraform Cloud will start the first assessment in about 24 hours.

Drift detection never interrupts or interferes with runs. Terraform Cloud triggers a drift detection assessment if at least 24 hours have passed since the last assessment and there are no active runs in the workspace.

You can start a new run during a drift detection assessment, but it will cancel the current assessment. Terraform Cloud will run the next assessment in 24 hours.

If drift detection is enabled on multiple workspaces, assessments may run concurrently. Drift detection assessments do not affect your concurrency limit. Terraform Cloud also monitors and controls drift detection concurrency, so it will not cause issues for large-scale deployments with thousands of workspaces. However, Terraform Cloud performs drift detection assessments in batches, so drift detection may take longer to complete when you enable it in a large number of workspaces.

»Workspace Drift Status

After you enable drift detection, the workspace displays one of the following drift statuses:

• Pending: Terraform Cloud is performing a drift detection assessment for the workspace or there are no prior drift detection results. For example, a workspace will show this status for 24 hours when you enable drift detection during an active run.
• Drifted: Terraform Cloud has found that one or more real-world infrastructure resources do not match the workspace’s state file.
• Failed: Terraform Cloud could not successfully complete the drift detection assessment for this workspace and will retry 24 hours after the failed assessment.
• Checked: Terraform Cloud successfully completed the assessment and did not detect drift.

The workspace’s Drift tab contains details about the last drift detection assessment. If there is drift, Terraform Cloud shows how the real-world infrastructure differs from the latest version of the workspace’s state file.

»Resolving Drift

You can use one of the following approaches to correct workspace drift:

• Overwrite drift: Queue a new plan to realign your real-world infrastructure with your Terraform configuration.
• Update Terraform state and configuration to match drift: Queue a refresh-only plan to update your Terraform state to match your real-world infrastructure. We recommend also modifying your Terraform configuration to include any new or changed resources. Otherwise, Terraform will overwrite the updated state file during the next apply, reintroducing drift into the workspace. Refer to our Manage Resource Drift tutorial for a detailed example.