Terraform State and Refresh

In this lesson we’ll examine Terraform state: what it contains, how to inspect it, and how to refresh it when infrastructure changes outside of Terraform. We previously wrote configuration and applied it — Terraform’s true power comes from how it tracks resources in state. Here we’ll learn how to view that state, perform safe state maintenance, and reconcile Terraform’s view with the actual provider.

What is Terraform state?

Terraform stores a state file that serves as the authoritative record of resources Terraform manages. This file contains the mapping between resource addresses in your configuration and the actual provider-managed resources (IDs, computed attributes, metadata). Terraform relies on state to plan changes and detect drift.

Inspecting state

Use the terraform state family of commands to inspect and manage the state. To see all tracked resources:

$ terraform state list
azurerm_storage_account.example

To view detailed attributes for a single tracked resource:

$ terraform state show azurerm_storage_account.example
# azurerm_storage_account.example:
resource "azurerm_storage_account" "example" {
  access_tier                      = "Hot"
  account_kind                     = "StorageV2"
  account_replication_type         = "LRS"
  account_tier                     = "Standard"
  allow_nested_items_to_be_public  = true
  cross_tenant_replication_enabled = false
  default_to_oauth_authentication  = false
  dns_endpoint_type                = "Standard"
  https_traffic_only_enabled       = true

  id = "/subscriptions/548f7d26-b5b1-468e-ad45-6ee12accf7e7/resourceGroups/my-workshop-eus-rg/providers/Microsoft.Storage/storageAccounts/sadx98rgffe"
}

The state show output includes both configuration-declared attributes and provider-populated fields (IDs, defaults, and runtime properties). This detailed view is essential for debugging, auditing, and preparing precise state changes.

State management subcommands

The terraform state command exposes subcommands for advanced state maintenance. Terraform automatically creates a timestamped backup of state before any operation that modifies it. Below is a concise reference:

Subcommand	Purpose	Example
`list`	List resources recorded in state	`terraform state list`
`show`	Print detailed state for a single resource	`terraform state show azurerm_storage_account.example`
`mv`	Move a resource address within state (useful when refactoring)	`terraform state mv old.resource new.resource`
`rm`	Remove instances from state without destroying remote resources	`terraform state rm module.foo.azurerm_resource.bar`
`replace-provider`	Replace provider references in state (for provider namespace changes)	`terraform state replace-provider registry.terraform.io/old/provider registry.terraform.io/new/provider`
`pull`	Pull the current state and output to stdout (for manual inspection)	`terraform state pull`
`push`	Update remote state from a local state file (special workflows)	`terraform state push terraform.tfstate`

The commands are intentionally simple and script-friendly (work well with grep, awk, etc.) for advanced automation and auditing.

State modification commands can cause drift between Terraform and your real infrastructure if used incorrectly. Always work against a backup and prefer non-destructive commands unless you fully understand the implications.

Refreshing state

The image contains the text "Terraform Refresh" with a copyright notice for KodeKloud at the bottom left.

Terraform expects the state file to reflect reality. When resources are modified outside Terraform (console edits, manual CLI/API actions, other orchestration tools), the stored state can diverge — this is configuration drift. Use terraform refresh to reconcile Terraform’s state with the provider by re-querying resource attributes and updating the state file. Important: terraform refresh updates only the state file; it does not change infrastructure. Example configuration using a variable for the storage account name:

resource "azurerm_storage_account" "example" {
  name                          = var.storage_account_name
  location                      = "East US"
  resource_group_name           = "my-workshop-eus-rg"
  account_tier                  = "Standard"
  account_replication_type      = "LRS"
  public_network_access_enabled = false
}

Running a refresh (supplying the variable):

$ terraform refresh -var "storage_account_name=sadx98rgffe"
azurerm_storage_account.example: Refreshing state...
  [id=/subscriptions/548f7d26-b5b1-468e-ad45-6ee12accf7e7/resourceGroups/my-workshop-eus-rg/providers/Microsoft.Storage/storageAccounts/sadx98rgffe]

After running, Terraform has fetched the current resource attributes from Azure and updated the local state to match — no remote changes are made.

Modern Terraform performs an automatic refresh during operations like terraform plan and terraform apply, so manually running terraform refresh is less common. Still, it’s valuable when resolving drift or preparing for direct state edits.

Key takeaways

The Terraform state file is the authoritative record of managed infrastructure.
Inspect state with terraform state list and terraform state show.
Use terraform state subcommands for advanced maintenance — Terraform creates backups automatically for safety.
Run terraform refresh to update the state from provider data; it updates only the state file and does not alter resources.
Be cautious with state-modifying commands; test on non-production state or use backups to recover if needed.

Introduction

Infrastructure as Code Fundamentals

Terraform Cloud

Setting up environment

Azure Context for Terraform

HashiCorp Configuration Language

Terraform Providers

Variables

Outputs and Dependencies

Iteration and Logic

Advanced Constructs

Terraform State Fundamentals

Remote State

Terraform Workspaces

Terraform CLI

Lifecycle Meta-Arguments

Data Sources

Provisioners

Debugging Terraform

Terraform Modules

Azure DevOps Integration

Azure Pipelines for Terraform

Terraform State and Refresh

What is Terraform state?

Inspecting state

State management subcommands

Refreshing state

Key takeaways

Links and references

Watch Video

​What is Terraform state?

​Inspecting state

​State management subcommands

​Refreshing state

​Key takeaways

​Links and references

Watch Video

What is Terraform state?

Inspecting state

State management subcommands

Refreshing state

Key takeaways

Links and references