Pinpointing Terraform State Drift That Breaks Deploys Without Warning

Your Terraform plan shows no changes. You run apply, everything turns green, and then your service starts misbehaving — or worse, a deploy in another pipeline silently fails with a cryptic error that has nothing to do with the code you just shipped. The culprit is often state drift: the gap between what Terraform thinks exists and what actually lives in your cloud account.

Drift is inevitable in any environment touched by more than one person or one automation tool. The question is whether you find it on your terms or at 2 AM during an incident.

• What Terraform state drift is and how it happens
• How to detect drift using built-in Terraform commands
• How to read and interpret drift in a plan output
• Strategies to reconcile drifted resources without destroying live infrastructure
• How to build a lightweight drift-detection workflow that runs automatically

What State Drift Actually Is

Terraform keeps a state file — by default terraform.tfstate — that records the last-known configuration of every resource it manages. When you run terraform plan, it compares three things: your .tf files (desired state), the state file (recorded state), and optionally the real infrastructure (actual state).

Drift is the mismatch between the recorded state and the real infrastructure. It usually shows up in one of three ways:

• Out-of-band changes — someone edited a security group rule, resized an RDS instance, or tagged an S3 bucket manually in the AWS console.
• External automation — another tool (an autoscaler, a configuration management script, another Terraform workspace) modified a resource Terraform owns.
• Partial applies — a terraform apply was interrupted mid-run, leaving the state file partially updated but the real resources in an inconsistent state.

The tricky part is that a basic terraform plan does not always catch drift. By default, Terraform reads the state file but does not call the cloud APIs to verify that the recorded state matches reality. You need to explicitly ask it to refresh.

Reproducing the Problem: A Concrete Example

Say you have an AWS security group defined in Terraform that allows inbound traffic on port 443. Someone on your team added port 8080 directly in the console because they were debugging and forgot to remove it. Your state file still says only port 443 is open.

When you run terraform plan, Terraform compares your .tf file to the state file. Both agree on port 443 only. Plan shows no changes. But the real resource has port 8080 open. That undocumented port is your drift — invisible to Terraform until you force a refresh.

Detecting Drift with terraform refresh and terraform plan -refresh-only

The oldest approach is terraform refresh, which pulls the current state of all resources from the provider and updates the state file to match. This is now considered a legacy command because it writes changes to state without giving you a chance to review them first.

The modern, safer approach is:

terraform plan -refresh-only

This command tells Terraform to query every managed resource from the provider and show you what it would need to update in the state file to match reality — without touching your actual infrastructure and without applying anything. It is a read-only diff between your recorded state and the real world.

A typical output looks like this:

~ update in-place

  # aws_security_group.app will be updated in-place
  ~ resource "aws_security_group" "app" {
        id   = "sg-0abc123"
      ~ ingress = [
          + {
              + cidr_blocks      = ["0.0.0.0/0"]
              + from_port        = 8080
              + protocol         = "tcp"
              + to_port          = 8080
            },
            # (1 unchanged element hidden)
        ]
    }

That + block is the drift. Terraform is telling you: