A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
»Health Assessments
Note: Health Assessments (formerly called drift detection) is available in the Terraform Cloud Business tier.
Health assessment describes the regular, automatic inspection of a workspace to surface resource lifecycle concerns. You can enable health assessments to check your workspace for infrastructure drift.
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.
When enabled, Terraform Cloud automatically runs a health assessment for your workspace every 24 hours. The assessment checks for infrastructure drift by comparing the actual settings of your infrastructure against those tracked in your workspace's state file.
»Requirements
Workspaces require the following settings to receive health assessments:
- Terraform version 0.15.4+
- Remote execution mode or Agent execution mode for Terraform runs
»Enable Health Assessments
You can enforce health assessments across all eligible workspaces in an organization within the organization Health settings. Enforcing health assessments at an organization-level overrides workspace-level settings. You can only enable health assessments within a specific workspace when health assessments are not enforced at the organization level.
To enable health assessments within a workspace:
- Verify that the workspace satisfies the requirements.
- Go to the workspace and click Settings > General.
- Select Enable under Health Assessments.
- Click Save settings.
»Health Assessment Scheduling
If there are no active Terraform runs in the workspace, Terraform Cloud starts a health assessment as soon as you enable the feature. If you enable health assessments during a speculative plan, Terraform Cloud will start a health assessment soon after that plan's completion. If you enable health assessments during other types of runs, Terraform Cloud will start the first assessment in about 24 hours.
A health assessment never interrupts or interferes with runs. Terraform Cloud triggers a health 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 health assessment, but it will cancel the current assessment. Terraform Cloud will run the next assessment in 24 hours.
If health assessments are enabled on multiple workspaces, assessments may run concurrently. Health assessments do not affect your concurrency limit. Terraform Cloud also monitors and controls health assessment concurrency, so it will not cause issues for large-scale deployments with thousands of workspaces. However, Terraform Cloud performs health assessments in batches, so health assessments may take longer to complete when you enable them in a large number of workspaces.
»Workspace Health Status
After you enable health assessments, the workspace displays one of the following statuses:
- Pending: Terraform Cloud is performing a health assessment for the workspace or there are no prior assessment results. For example, a workspace will show this status for 24 hours when you enable health assessments 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 health 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 or other concerns.
The workspace’s Drift tab contains details about the last health 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.