Skip to content
Forgeplane Docs

Terraform and OpenTofu drift detection

Terraform and OpenTofu drift detection compares an instance’s declared configuration with live infrastructure without silently changing resources. A drift monitor belongs to one instance, so it reuses that instance’s template version, environment, inputs, connections, and managed state.

Detection and convergence are separate

Section titled “Detection and convergence are separate”

Detection records evidence; it does not remediate live infrastructure.

Workflow Behavior
Detection Creates a non-mutating drift run and records whether drift exists.
Finding Tracks the affected instance, evidence, severity, and resolution state.
Convergence Starts a separate, request-based workflow. Only revert_live is executable today.
Accept or codify Reserved in the data model, but accept_live and codify_live requests currently return a conflict.

This separation prevents a scheduled observation from becoming an unreviewed infrastructure mutation.

Detection flow

Section titled “Detection flow”
  1. An active monitor becomes due.
  2. The coordinator creates a non-mutating drift run for its instance.
  3. An eligible worker compares declared and live state.
  4. Forgeplane records the result and creates or updates a finding when drift exists.
  5. An operator reviews the finding and chooses a supported follow-up action.

The environment’s drift_monitoring.enabled feature gate must allow scheduled monitoring. A disabled gate blocks the operation; it does not silently change monitor state or discard history.

Monitor scope and lifecycle

Section titled “Monitor scope and lifecycle”

A monitor is not a second deployment target. It inherits the instance’s published template version, environment, resolved inputs, connections, and managed-state context.

Configuration state Scheduling behavior
draft Saved but not scheduled.
active Eligible for scheduled checks.
paused Temporarily excluded from scheduling while retaining configuration and history.
disabled Deactivated and not scheduled.

Configuration state and the latest check result are separate. Runtime status reports idle, running, no_drift, drift_detected, or failed; Forgeplane also tracks consecutive failures.

See Drift monitors for cadence, deduplication, and configuration changes.

Findings and evidence

Section titled “Findings and evidence”

A finding identifies the affected instance, detection time, plan evidence, status, and severity. Finding statuses are open, resolution_pending, resolved, reopened, and suppressed; severities are low, medium, and high.

Evidence records capture the observed difference. Forgeplane uses a drift fingerprint, scope key, observation count, and confidence score to track repeated observations and avoid treating the same unchanged difference as a new event on every check.

Supported follow-up actions

Section titled “Supported follow-up actions”

The data model recognizes these resolution types:

  • revert_live: create a reviewable convergence path toward the declared configuration;
  • manual_ack: acknowledge the finding without automated remediation;
  • accept_live: reserved for a future workflow and not executable today;
  • codify_live: reserved for a future workflow and not executable today.

Only revert_live can execute. Requests for accept_live or codify_live fail with a conflict rather than implying that live changes were accepted or written back to code. See Drift convergence for gates and request behavior.

Section titled “Related workflows”