Demo Detecting State Drift with Refresh Only Mode

In this guide you’ll learn how to detect and handle state drift with the Terraform CLI. We’ll cover:

How Terraform discovers differences between your configuration, state, and real infrastructure.
How to either revert remote changes or accept them into Terraform state using a refresh-only apply.
How to update your configuration so configuration, state, and real infrastructure remain in sync.

This demo uses a minimal AWS example: a VPC, two subnets (public and private), and an EC2 instance acting as a web server.

Terraform configuration used in this demo

main.tf

# main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name        = "dev-main-vpc"
    Environment = "development"
  }
}

resource "aws_subnet" "private" {
  vpc_id = aws_vpc.main.id
  # ...other attributes...
}

resource "aws_subnet" "public" {
  vpc_id = aws_vpc.main.id
  # ...other attributes...
}

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  subnet_id     = aws_subnet.private.id

  tags = {
    Name        = "web-server"
    Environment = "development"
  }
}

variables.tf

# variables.tf
variable "ami_id" {
  description = "The AMI ID for the EC2 instance"
  type        = string
}

variable "instance_type" {
  description = "The instance type for the EC2 instance"
  type        = string
  default     = "t2.small"
}

Deploy the configuration

Initialize and apply:

terraform init
terraform apply -auto-approve

Example apply output (shortened):

aws_subnet.public: Creation complete after 11s [id=subnet-09d564c1e1609a06f]
aws_instance.web: Creation complete after 13s [id=i-0c4192b0347156b5c]

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Open the AWS EC2 console to verify the instance. You should see the instance tags (Name = web-server, Environment = development) and the instance type set by the instance_type variable (t2.small). I stopped the instance in the console and changed its instance type from t2.small to t3.small. Here is the “Change instance type” page showing that change:

A screenshot of the AWS EC2 console on the "Change instance type" page, showing an instance (i-0c4192b0347156b5c) with current type t2.small and a dropdown to change it to t3.small. The lower part of the page shows an instance type comparison table with pricing and specs.

After changing the instance type while stopped, I optionally updated the tags by adding a Team tag (Team = dev-app-001). The stopped instance with a successful “instance type changed” banner is shown below:

Screenshot of the AWS EC2 Instances console showing a single instance named "web-server" in the Stopped state with instance type t2.small. A green banner at the top reads "Instance type changed successfully."

I then saved tags via the console and added the Team tag:

A screenshot of the AWS EC2 "Manage tags" page showing tag entries: Name = web-server, Environment = development, and Team = dev-app-001, with Remove buttons and Save/Cancel actions. The browser window and AWS console header are visible at the top.

At this point, two manual changes were made outside of Terraform:

Instance type: t2.small → t3.small
Added tag: Team = dev-app-001

Detecting drift with Terraform

Terraform refreshes the state by default during terraform plan, so running a plan will reveal drift:

terraform plan

Example relevant output after the refresh step (shortened):

aws_subnet.private: Refreshing state... [id=subnet-002727a76951b6bc0]
aws_subnet.public: Refreshing state... [id=subnet-09d564c1e1609a06f]
aws_instance.web: Refreshing state... [id=i-0c4192b0347156b5c]

Note: Objects have changed outside of Terraform

Terraform detected the following changes made outside of Terraform since the last "terraform apply":

# aws_instance.web has changed
~ resource "aws_instance" "web" {
    ~ ebs_optimized   = false -> true
    ~ instance_type   = "t2.small" -> "t3.small"
    ~ tags            = {
        "Environment" = "development"
        "Name"        = "web-server"
      + "Team"        = "dev-app-001"
    }
    # (other attributes omitted)
}

This output shows exactly what Terraform detected as different between the configuration & state and the real resource.

Options after detecting drift

You have two primary choices after detecting drift:

Choice	Command	Result
Revert remote changes and make real infrastructure match Terraform config	`terraform apply`	Terraform plans and applies changes to restore resources to the configuration (Terraform remains the source of truth).
Accept remote changes into the Terraform state (no infrastructure actions)	`terraform apply -refresh-only`	Terraform updates the state file to reflect the real infrastructure without changing remote resources. Useful when external changes are intended.

Revert remote changes (make Terraform the source of truth)

If you want to overwrite the remote changes and enforce your Terraform configuration, run a normal apply:

terraform apply

Terraform will plan an in-place update to change the instance type back to t2.small and remove the Team tag (since the configuration doesn’t include that tag). Example plan summary:

Plan: 0 to add, 1 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

Approve to apply the changes and restore the resource to the declared state.

Accept remote changes into Terraform state (refresh-only apply)

If the manual changes are intentional and you want Terraform to record them without modifying infrastructure, run a refresh-only apply:

terraform apply -refresh-only

A refresh-only apply updates the Terraform state to match current real infrastructure but does not modify remote resources. Use this when external changes are desired and you want Terraform to record them in the state.

When you run terraform apply -refresh-only, Terraform shows a refresh-only plan and prompts:

This is a refresh-only plan, so Terraform will not take any actions to undo these.
If you were expecting these changes then you can apply this plan to record
the updated values in the Terraform state without changing any remote objects.

Would you like to update the Terraform state to reflect these detected changes?
  Terraform will write these changes to the state without modifying any real infrastructure.
  There is no undo. Only 'yes' will be accepted to confirm.

Confirming writes the updated values (for example, instance_type = "t3.small" and the new Team tag) into the state file while leaving the EC2 instance unchanged.

After accepting remote changes into state

The Terraform state now reflects the actual remote values (e.g., "instance_type": "t3.small" and the Team tag).
Your configuration files still define instance_type = "t2.small" and do not include the Team tag. If you later run a normal terraform apply, Terraform will detect that the configuration differs from the state and will plan to change real resources to match the configuration.

If you want to keep the manual changes going forward, update your Terraform configuration so configuration, state, and real infrastructure match.

Update configuration to match the desired state

Change the variable default and resource tags in your configuration to reflect the accepted remote changes. variables.tf

# variables.tf
variable "instance_type" {
  description = "The instance type for the EC2 instance"
  type        = string
  default     = "t3.small"
}

main.tf — update tags

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  subnet_id     = aws_subnet.private.id

  tags = {
    Name        = "web-server"
    Environment = "development"
    Team        = "dev-app-001"
  }
}

Then run:

terraform fmt
terraform apply

After updating both configuration and state, terraform apply should report no changes:

aws_vpc.main: Refreshing state... [id=vpc-0128cdde7431403fc]
aws_subnet.public: Refreshing state... [id=subnet-09d564c1e1609a06f]
aws_subnet.private: Refreshing state... [id=subnet-002727a76951b6bc0]
aws_instance.web: Refreshing state... [id=i-0c4192b0347156b5c]

No changes. Your infrastructure matches the configuration.

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Quick checklist

Detect drift: terraform plan (or terraform apply) — Terraform refreshes state during planning.
Revert remote changes: terraform apply — Terraform will change the remote resources to match configuration.
Accept remote changes (state-only): terraform apply -refresh-only — Terraform updates the state without touching remote resources.
To keep accepted remote changes permanently: update your Terraform configuration and run terraform apply.

References

Terraform CLI: apply — https://developer.hashicorp.com/terraform/cli/commands/apply
Terraform CLI: plan — https://developer.hashicorp.com/terraform/cli/commands/plan
Terraform State management — https://developer.hashicorp.com/terraform/language/state
AWS EC2 instance types — https://aws.amazon.com/ec2/instance-types/

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Detecting State Drift with Refresh Only Mode

Terraform configuration used in this demo

Deploy the configuration

Detecting drift with Terraform

Options after detecting drift

Revert remote changes (make Terraform the source of truth)

Accept remote changes into Terraform state (refresh-only apply)

After accepting remote changes into state

Update configuration to match the desired state

Quick checklist

References

Watch Video

​Terraform configuration used in this demo

​Deploy the configuration

​Detecting drift with Terraform

​Options after detecting drift

​Revert remote changes (make Terraform the source of truth)

​Accept remote changes into Terraform state (refresh-only apply)

​After accepting remote changes into state

​Update configuration to match the desired state

​Quick checklist

​References

Watch Video

Terraform configuration used in this demo

Deploy the configuration

Detecting drift with Terraform

Options after detecting drift

Revert remote changes (make Terraform the source of truth)

Accept remote changes into Terraform state (refresh-only apply)

After accepting remote changes into state

Update configuration to match the desired state

Quick checklist

References