Terraform and OpenTofu drift detection workflow

Infrastructure drift is a difference between the configuration you intend and the resources that exist. The difficult part is not only finding a difference. It is deciding which state is correct without turning a scheduled observation into an unreviewed mutation.

Forgeplane keeps detection and convergence separate. A monitor runs a non-mutating check, records evidence, and creates or updates a finding. An operator then chooses a supported follow-up.

Forgeplane is in private beta. Request access before planning a deployment around this workflow.

Choose a detection model

Model	Useful when	Operating boundary
Manual CLI check	Drift reviews are rare and one operator owns the target	Scheduling, credentials, evidence, and follow-up remain manual.
Scheduled CI job	Existing CI can reach the target and retain results	Deduplication, finding lifecycle, and remediation controls must be designed around the job.
Instance-bound monitor	You need scheduled checks tied to a governed template, environment, worker pool, and run history	You operate the control plane, credentials, workers, and provider access.

A check failure is not drift evidence. Credential expiry, provider errors, missing worker capacity, or network failures can all stop observation before a valid comparison exists.

Forgeplane detection flow

1. An active monitor becomes due.
2. The coordinator creates a non-mutating drift run for one existing instance.
3. An eligible Terraform or OpenTofu worker uses that instance’s published template version, environment, resolved inputs, connections, and managed-state context.
4. The worker compares declared and live infrastructure.
5. Forgeplane records the result and creates or updates a finding when drift exists.
6. An operator reviews the finding before requesting any supported response.

The drift_monitoring.enabled environment gate must allow scheduled checks. Monitor states are draft, active, paused, and disabled. The default cadence is four hours, with a supported range from 60 seconds to seven days.

See Drift monitors for configuration and scheduling details.

Retain evidence without alert floods

A useful drift record answers:

• which instance and configuration were checked;
• when the difference was observed;
• what plan evidence described it;
• how severe it is;
• whether the same difference was seen before; and
• which response, if any, was requested.

Forgeplane reuses an active finding when its drift fingerprint and scope match, then updates that finding’s observations and evidence. The monitor’s dedupe window has a different purpose: it throttles repeated automatic approval requests after a recent drift detection. It does not decide whether two observations belong to the same finding.

Finding states are open, resolution_pending, resolved, reopened, and suppressed. Keep finding state separate from monitor state: pausing a monitor does not resolve an existing finding.

Choose the response

Use this decision order:

1. Can the result be trusted? If the check failed or the execution context is stale, repair observation first.
2. Is the declared configuration still intended? If yes, consider a reviewable revert_live request.
3. Is the live change intended but handled outside automation? Record manual_ack. The current suppress endpoint does not store an operator rationale; keep any required explanation in a linked external ticket or runbook record.
4. Should live state become the new declared configuration? Treat this as a code and review task. Do not claim that the platform wrote the change back automatically.
5. Is the difference accepted only temporarily? Suppress or pause deliberately, with an owner and review date outside the automated mutation path.

Current Forgeplane boundary

Only revert_live is executable in the current convergence path. It creates a separate, reviewable request toward the declared configuration.

manual_ack records acknowledgement without automated remediation. accept_live and codify_live exist in the data model, but requests for them currently return a conflict. They do not import live state or write infrastructure code.

This boundary is deliberate: a scheduled drift check never silently approves or applies a change. Drift convergence describes the request, approval, and finding-state transitions.

Production checklist

Before enabling scheduled drift checks:

• verify the instance points to the intended published template version;
• confirm the worker image contains the required Terraform or OpenTofu binary;
• test provider credentials and target reachability from that worker pool;
• choose a cadence that respects provider limits, and a dedupe window that limits repeated automatic approval requests to operator capacity;
• route signed notifications to an owned response process when needed;
• test how failures, paused monitors, and repeated findings appear; and
• confirm that no detection path can mutate infrastructure without a separate request and approval boundary.

Use Webhooks for signed finding notifications, Approval workflows for gated changes, and Audit logging for investigation evidence.