Chapter 38: Terraform CLI Commands fmt validate plan apply state and more

38.7 refresh-only and graph

By Ravindra Bagale · Last updated: 25 October 2026

Story. An Infosys client support engineer changed a tag in the console during an incident, and the team wanted state to record reality without changing AWS. apply -refresh-only updates state from the real resources and makes no infrastructure changes. terraform graph prints the dependency graph so you can see why things build in a certain order.

terraform plan -refresh-only
terraform apply -refresh-only
terraform graph | dot -Tsvg > graph.svg

What each line does

• terraform plan -refresh-only — Shows what changed in AWS since the last apply, without proposing fixes.
• terraform apply -refresh-only — Writes those real values into state; AWS is not changed.
• terraform graph | dot -Tsvg > graph.svg — Turns the dependency graph into a picture with Graphviz.

When it is green.

Note: Objects have changed outside of Terraform
  # aws_instance.web has changed
  ~ tags = { + "Incident" = "INC-1042" }
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

When it is red.

dot: command not found

Fix. Install Graphviz with sudo apt install graphviz or sudo dnf install graphviz. Remember: after refresh-only, the next normal plan will propose removing the console tag unless you also add it to code.

What: every term in plain English

• refresh — Terraform reads real AWS values into state.
• -refresh-only — A plan or apply that only updates state from AWS. It never changes AWS.
• drift — AWS changed outside Terraform, for example a console click.
• terraform graph — Prints the dependency graph in DOT format.
• dot — A Graphviz tool that turns DOT into a picture.

Example 1: See drift with plan -refresh-only

Someone added a tag in the console at night. Find out what changed.

1. Add a tag Owner=ravi to the instance in the console.
2. Run plan -refresh-only.

terraform plan -refresh-only

Output

Note: Objects have changed outside of Terraform

  # aws_instance.web has changed
  ~ resource "aws_instance" "web" {
      ~ tags = {
          + "Owner" = "ravi"
            # (1 unchanged element hidden)
        }
    }

This is a refresh-only plan, so Terraform will not take any actions to undo these.

What it shows: It only reports. Nothing is changed in AWS or state.

Example 2: Accept the drift into state, then decide

First record reality, then fix the code or revert.

terraform apply -refresh-only -auto-approve
terraform plan

Output

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

  # aws_instance.web will be updated in-place
  ~ tags = {
      - "Owner" = "ravi" -> null
    }
Plan: 0 to add, 1 to change, 0 to destroy.

What it shows: Now a normal plan wants to remove the tag. Either add Owner to the code, or apply to revert.

Example 3: Draw the dependency graph

A new teammate asks why the instance waits for the security group. Show a picture.

sudo apt-get install -y graphviz
terraform graph | dot -Tsvg > graph.svg
terraform graph | grep -- '->' | head -3

Output

"[root] aws_instance.web (expand)" -> "[root] aws_security_group.web (expand)"
"[root] aws_instance.web (expand)" -> "[root] data.aws_ami.al2023 (expand)"
"[root] aws_security_group.web (expand)" -> "[root] data.aws_vpc.default (expand)"

What it shows: Each arrow means depends on. Open graph.svg in a browser to see the boxes.

Example 4: Nightly drift job

Catch console changes the next morning, not during an outage.

terraform plan -refresh-only -detailed-exitcode -no-color > drift.txt
if [ $? -eq 2 ]; then echo "DRIFT in prod"; grep 'has changed' drift.txt; fi

Output

DRIFT in prod
  # aws_instance.web has changed

What it shows: Run it from Jenkins or GitHub Actions on a schedule and send the result to Slack.

Example 5: Graph only one change, from a saved plan

A full graph is crowded. A plan graph shows only what will change.

terraform plan -out=tfplan
terraform graph -type=plan tfplan | dot -Tpng > plan.png
terraform graph -type=plan tfplan | grep -c -- '->'

Output

Plan: 2 to add, 0 to change, 0 to destroy.
6

What it shows: Open plan.png. Fewer boxes, easier to explain to a reviewer.

Command cheat sheet

Verify: did it work?

1. Drift is gone

   terraform plan -refresh-only -detailed-exitcode; echo $?
   

   Output

   No changes. Your infrastructure still matches the configuration.
   0
   

2. The picture was made

   ls -l graph.svg
   

   Output

   -rw-r--r-- 1 ravi ravi 18342 Oct 25 11:05 graph.svg
   

When it is red 1

Error: Unsupported argument: refresh-only cannot be combined with -replace

Cause. refresh-only never changes resources, so -replace makes no sense with it.

Fix, step by step

1. Run them as two separate commands.

When it is red 2

bash: dot: command not found

Cause. Graphviz is not installed.

Fix, step by step

1. Install graphviz with your package manager.
2. Run the graph command again.

When it is red 3

Warning: The terraform refresh command is deprecated

Cause. Old command. It updates state with no review.

Fix, step by step

1. Use terraform apply -refresh-only, which shows changes first.

When it is red 4

Note: Objects have changed outside of Terraform
  # aws_autoscaling_group.web has changed
      ~ desired_capacity = 2 -> 4

Cause. Not a real problem. Auto Scaling changes desired_capacity on its own, so it shows as drift every day.

Fix, step by step

1. Add lifecycle { ignore_changes = [desired_capacity] } to the group.
2. Run plan -refresh-only again and the noise is gone.

Cleanup

terraform destroy -auto-approve
rm -f graph.svg drift.txt

Practice tasks

Homework: try at home

Recap

• Every plan refreshes state first.
• plan -refresh-only shows drift and changes nothing.
• apply -refresh-only accepts AWS values into state.
• A normal apply reverts drift to match code.
• terraform graph plus dot draws dependencies.
• Use ignore_changes for values AWS changes on purpose, such as desired_capacity.

FAQ

Does refresh-only change AWS?

Never. Only state.

Should I always accept drift?

No. Decide: add it to code, or revert it.

Can I skip refresh?

plan -refresh=false is faster but can be wrong. Use rarely.

Is graph useful for big stacks?

It gets crowded. Graph one module folder at a time.

What causes drift most?

Console clicks, scripts and auto-scaling.

Does plan -refresh-only need AWS access?

Yes. It reads AWS.

Why does Auto Scaling always show drift?

AWS changes desired_capacity when load changes. Use ignore_changes for that one argument.

How often should a drift job run?

Once a night for most teams. Every hour for strict prod accounts.

Interview questions

1. How do you detect drift?

   plan -refresh-only with -detailed-exitcode on a schedule.

2. Why was terraform refresh deprecated?

   It changed state without review. apply -refresh-only shows a plan first.

3. How do you fix drift?

   Either update code to match, or apply to restore the code values.

4. What does terraform graph show?

   Resource dependencies in DOT format.

5. How do you stop drift?

   Limit console write access and change only through pipelines.

6. Your drift job fires every night for the same resource. What do you do?

   Find who or what changes it. If it is expected, such as Auto Scaling, add ignore_changes for that argument. If it is a person, remove their console write access and route changes through the pipeline.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards