Run terraform plan -refresh-only to see how remote objects differ from your state, then apply that plan to update the state without changing any infrastructure. HashiCorp describes the mode for changes made outside the usual workflow, such as during an incident response.
What refresh-only mode is
Terraform has a normal planning mode that changes remote systems to match your configuration. It also has two alternate modes. Destroy mode plans to remove everything. Refresh-only mode creates a plan whose goal is only to update the state and root module outputs to match changes made to remote objects outside Terraform.
The option exists from Terraform v0.15.4 onward and is available on both plan and apply.
When you would use it
Someone opens a security group during an outage at 2 a.m. The change helps, and the team keeps it for now. The next normal terraform plan wants to revert it. You have two honest choices: put the change into the code, or let Terraform revert it. Refresh-only mode is the step that records reality in the state so you can then decide.
Steps
- Run
terraform plan -refresh-onlyand read the proposed state changes. - Decide per item whether the outside change is wanted.
- If wanted, apply the refresh-only plan, then edit the configuration to match so a normal plan shows no diff.
- If not wanted, skip refresh-only and run a normal plan so Terraform reverts it.
- Record who changed what and why in the ticket or pull request.
Normal plan versus refresh-only
| Question | Normal plan | Refresh-only plan |
|---|---|---|
| Changes cloud resources | Yes, to match code | No |
| Updates state | As part of apply | Yes, to match reality |
| Good for | Delivering code changes | Recording outside changes |
A security angle
Drift can be a legitimate fix or an intrusion. Reading the refresh-only output is a cheap way to notice changes nobody announced, like a new access rule or a changed policy. Treat unexplained entries as findings, not noise.
Cautions
- Applying a refresh-only plan updates state only. Your code is still out of date until you edit it.
- Do not keep running refresh-only to silence a recurring diff. Find who or what keeps changing the resource.
Try it yourself
Click through it at your own pace, or open it full screen. Watch how changes are surfaced over time, which is the same idea as scheduling a refresh-only plan.
Quick check
Does refresh-only change my cloud resources?
No. Its goal is to update the state and outputs to match remote objects.
How is it different from terraform refresh?
It is a planning mode you can review before applying, so the state change is visible first.
Will my code change automatically?
No. You must update the configuration yourself if you want to keep the outside change.
Safeguard offers SBOM and dependency scanning and policy gates that can block a pull request on findings, and you can try a free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
