Where Terraform refresh Stands Today: State Sync and Its Modern Alternatives

In Terraform, reconciling the drift between the real environment and the Terraform state file — what we call state sync — is a critical operation. Historically this was done with terraform refresh, but today the recommended workflow uses the -refresh-only flag.

This article walks through the correct way to perform state sync per the official recommendations, the common pitfalls, and the points commonly tested on the Associate / Pro exams, all from a practical operations perspective.

The Role of refresh and the Basics of State Sync

Terraform keeps the last known state of real resources in tfstate. When humans or external tools change the real environment, drift opens up between the state file and reality. State sync is the operation that overwrites that drift with the facts on the ground and corrects the state file.

The legacy terraform refresh reads real resources via the provider and updates only the state file. It does not touch your configuration (.tf) and does not create, update, or delete any infrastructure. It is now deprecated, and the -refresh-only flag described below is recommended.

• State sync is read-only and never writes to infrastructure
• plan/apply perform a state read (refresh) up front by default
• As a side effect of refresh, resources that no longer exist may be removed from state

The Deprecated terraform refresh and Its Replacements

The official documentation treats the legacy terraform refresh as deprecated. The replacements are terraform plan -refresh-only and terraform apply -refresh-only. They explicitly express plan and apply that only update state, and they are the recommended approach today.

Exact behavior, messages, and deprecation warnings can differ by version, so always confirm the local CLI spec in your environment with terraform version and terraform -help.

• terraform plan -refresh-only: visualizes the diff that would update state (does not apply it)
• terraform apply -refresh-only: applies the above diff to tfstate (does not change infrastructure)
• terraform plan -refresh=false: suppresses the refresh during planning to save API calls and time

Minimum set of replacement commands

terraform plan -refresh-only
terraform apply -refresh-only

# When you want to sync only some resources (kept minimal)
terraform plan  -refresh-only -target=aws_instance.web
terraform apply -refresh-only -target=aws_instance.web

# Suppress API reads during planning (cache-like usage). Validate with a normal plan/apply before the final apply
terraform plan -refresh=false

Execution Flow for Drift Detection

Terraform's planning engine first fetches the latest values of real resources through the provider, then computes the diff against the state file. With -refresh-only attached, that diff is restricted to state file updates, and no create, update, or delete actions are proposed against infrastructure.

The diagram below is a simplified path from user action through provider reads to the state update.

• Refresh hits the provider's Read operations intensively, so watch out for API limits and quotas
• If your backend supports locking, a lock is acquired during sync (to prevent concurrent apply conflicts)

High-level flow of state sync (refresh-only)

User CLI
   |
   v
Terraform Core -----> State Backend (lock)
   |
   v
Provider(s) -----> Cloud/API (Read only)
   |
   v
Diff Engine (refresh-only: state updates only)
   |
   v
Update tfstate (no infra changes)

Save the plan, then safely apply (state-only update)

terraform plan -refresh-only -out=refresh.plan
# Review the diff
terraform show refresh.plan
# Apply the state-only update
terraform apply refresh.plan

Practical Usage Patterns and Caveats

For audits, inventories, or checking whether manual changes occurred, first visualize with terraform plan -refresh-only. If nothing looks wrong, bring tfstate up to date with terraform apply -refresh-only. This is also useful for periodic drift detection in CI and post-incident state reconciliation.

A key caveat: resources whose real entities have disappeared will be removed from state by a refresh-only apply. If recovery is possible or the loss was unintended, do not run apply -refresh-only immediately; instead investigate the cause and consider re-importing with terraform import.

• Move forward safely in two stages: -plan first, then -apply
• Keep -target scoped to the absolute minimum (do not use it to permanently break dependencies)
• In large environments, account for provider API limits and rates, and tune schedules and parallelism
• Verify that backend locking is enabled and avoid concurrent runs

Options when you do not want deleted resources removed from state

# Do not apply right away. First just review the diff
terraform plan -refresh-only

# If accidental deletion is possible, recover and then re-import into state with import
terraform import aws_instance.web i-0123456789abcdef0

Command Comparison and Behavioral Differences

Commands with similar names differ in purpose and side effects. Here we untangle the easily-confused points for both exam prep and real-world operations.

• Only refresh and the -refresh-only family leave infrastructure unchanged
• The default plan/apply perform a pre-refresh (which can be suppressed with -refresh=false)

Exam Tips (Associate / Pro)

On the Associate exam, what matters is correctly picking the intent of state sync and the meaning of -refresh-only. On the Pro exam, you are tested on situation-aware workflow design: drift handling, scoped use of -target, and intentional use of -refresh=false.

Remember: a normal plan/apply also refreshes state, but refresh-only restricts the operation to a state update. Infrastructure is never modified.

• refresh is deprecated. The correct answer is apply/plan with -refresh-only
• Resources judged as nonexistent can be removed from state by a refresh-only apply
• -target is for emergency workarounds or scoped use. Routine use is discouraged
• Being able to talk about backend locking and concurrent-execution safety is a plus

Check with a Practice Question

Frequently Asked Questions