Drift Reconciliation and Brownfield Import with a Zero-Diff Gate

Tier: Core · Workflow area: Infrastructure as Code

AI accelerates the tedious middle: narrating what drifted and why it matters, planning a safe reconciliation order, and generating import blocks plus matching HCL. The objective gate is beautifully binary: terraform plan says No changes, or you are not done.

When to use

• •
  Scheduled drift detection shows diffs you need to explain and resolve (console hotfixes, autoscaling side effects, another team's "temporary" change).
• •
  Taking over a client estate where half the resources were clicked into existence.
• •
  Post-incident: emergency console changes need folding back into code.

Skip AI for single-resource drift you already understand — terraform apply or one import block, done.

Prerequisites

• •
  Terraform ≥ 1.5 (import blocks) or OpenTofu; state access.
• •
  Read access to the live environment (aws cli/az/gcloud) for inventory.
• •
  Optional: driftctl or your platform's drift detection for the discovery pass.
• •
  A quiet window — reconciling state while others apply is misery.

The workflow

1. 1.

   Capture the evidence. For drift: terraform plan -refresh-only -out=drift.plan then terraform show -json drift.plan > drift.json. For brownfield: inventory the unmanaged resources (aws resourcegroupstaggingapi get-resources, or driftctl's unmanaged report).

2. 2.

   Ask for a narrative and a safe ordering — not an apply script.

   Copy

   Attached: refresh-only plan JSON showing drift in our prod stack.
   
   For each drifted resource:
   1. Describe the drift in plain English: what changed, in which direction
      (console-ahead-of-code or code-ahead-of-console).
   2. Classify: HARMLESS (tags, descriptions) / RISKY (security groups, IAM,
      scaling settings) / DATA-AFFECTING (anything on stateful resources).
   3. Recommend per resource: adopt into code (update HCL to match reality),
      revert (apply code over reality), or investigate (conflicting intent).
   4. Give a reconciliation order that never leaves a security control
      loosened mid-sequence.
   Flag anything where reverting could cause an outage (e.g., reverting a
   scaling change made during an incident).
   

3. 3.

   Investigate before adopting or reverting. The narrative tells you what; only humans can find out why. A security group opened by hand might be an unauthorized change (revert) or an emergency fix for an incident still in progress (adopt, then fix properly). Check change tickets, CloudTrail, and the incident channel before deciding.

4. 4.

   For brownfield: generate import blocks + HCL together.

   Copy

   Generate Terraform import blocks and matching resource HCL for these
   unmanaged resources (inventory JSON attached; AWS provider ~> 5.40).
   Rules:
   - One import block per resource, IDs exactly from the inventory.
   - HCL must reflect the resource's ACTUAL current configuration from the
     attached describe output — not defaults, not best practice. Matching
     reality is the goal; improving it comes later, as a separate diff.
   - Group into logical modules matching our repo layout (attached tree).
   

   Copy

   import {
     to = aws_security_group.legacy_app
     id = "sg-0a1b2c3d4e5f67890"
   }
   

5. 5.

   Run the zero-diff gate. terraform plan after import (or after adopt-edits) must show no changes for the touched resources. Every remaining diff means the generated HCL guessed an attribute instead of reading reality — iterate with the plan output until the diff is empty. This gate is non-negotiable and mechanical; do not accept "close enough."

6. 6.

   Only then improve. Once at zero-diff, security/cost improvements to newly-adopted resources go as normal PRs through the full chain (pb-08) — deliberately separated from the import so each plan is interpretable.

Tool variants

• Plain Terraform + chat assistant (shown): works everywhere; import blocks make brownfield far safer than legacy terraform import one-liners because they are reviewable in a PR.
• driftctl / Firefly / env0-class platforms: better discovery and continuous detection; still use the narrative-classify-order workflow on their output, and keep the zero-diff gate yours.
• Terraformer or repo-aware agents for bulk brownfield: Terraformer generates first-pass HCL mechanically; use AI to clean it into your module conventions, then the same zero-diff gate.

Verification

The chain applies with the zero-diff gate as the star:

• Validate: generated HCL passes terraform validate + TFLint.
• Plan (zero-diff): post-reconciliation plan shows No changes for every touched resource — screenshot/paste it into the PR.
• Policy: Checkov runs on the newly-adopted code; findings become tracked improvement PRs, not silent edits before import (which would break zero-diff).
• Cost: newly-imported resources appear in Infracost baseline — brownfield adoption often surfaces forgotten expensive resources; flag them.
• State safety: state backup exists and its timestamp precedes the first state-modifying command.

Pitfalls

• AI-guessed resource IDs. Import IDs have per-resource formats (ARNs, names, composite IDs). Every ID must come from your inventory, never model recall. A wrong ID imports the wrong resource into your state.
• "Improved" HCL breaking zero-diff. Assistants reflexively add encryption and tags while generating import HCL. Reality-first, improvements second — enforce it in the prompt and in review.
• Reverting incident mitigations. Drift created during incident response is load-bearing. Cross-check drift timestamps against incident history before reverting anything.
• Reconciling during active change windows. Someone else's apply mid-reconciliation corrupts your zero-diff signal. Lock or coordinate.

Restricted-environment variant

Inventory and state contain the client's entire infrastructure map — the most sensitive artifact in this track. Default to running everything inside the client boundary: OSS tools throughout, client's in-tenancy AI endpoint for the narrative/generation steps. If only public assistants are available, the narrative step can run on structurally-redacted plan JSON (resource types and change kinds, IDs hashed), but import-block generation needs real IDs — do that half without AI, or fully in-tenancy.

Success criteria

• •
  Every drifted/unmanaged resource has an explicit adopt/revert/investigate decision recorded in the PR.
• •
  terraform plan shows zero changes at reconciliation end — the gate passed mechanically, not by judgment call.
• •
  State backup taken; no state-modifying command was run by an AI agent.
• •
  Improvement PRs for adopted resources are queued separately through the full verification chain.