State Commands: Reading and Operating on State

The terraform state commands are the operators interface to the state. The read-only commands are safe. The state-mutating commands are powerful and dangerous. The lesson teaches the commands and the production risks.

Read-only commands

terraform state list

terraform state list

The output:

aws_instance.web
aws_security_group.web
module.network.aws_vpc.main

The list command shows every resource in the state. The output is the resource address.

The list command supports filters:

# List only AWS instances
terraform state list | grep aws_instance

# List a specific modules resources
terraform state list module.network

terraform state show

terraform state show aws_instance.web

The output:

# aws_instance.web:
resource "aws_instance" "web" {
  ami           = "ami-0e1bed4f"
  instance_type = "t3.medium"
  id           = "i-0abc123def456789"
  tags = {
    Name = "web-01"
  }
}

The show command shows the attributes of a single resource. The attributes are the providers response.

terraform state pull

terraform state pull

The output is the raw state JSON. The state is fetched from the backend and printed to stdout.

The pull command is useful for:

• Inspecting the state in scripts.
• Backing up the state.
• Comparing states across environments.

The pull command does not modify the state.

State-mutating commands

terraform state mv

terraform state mv aws_instance.web aws_instance.app_server

The mv command renames a resource in the state. The real-world resource is unchanged.

The mv command is appropriate for:

• Renaming a resource after a refactor that did not use moved.
• Moving a resource to a module path.
• Reconciling the state with the configuration.

The mv command is dangerous if used to bind the wrong attributes to the wrong resource. The fix is to verify the plan is empty after the mv.

terraform state rm

terraform state rm aws_instance.web

The rm command removes a resource from the state. The real-world resource is unchanged.

The rm command is appropriate for:

• Removing a resource from Terraform management (the resource will be left in the real world).
• Recovering from a partial apply failure.
• Reconciling a state that has drifted.

The rm command is very dangerous if used to remove a resource that should be managed. The next apply will propose to recreate the resource.

terraform state replace-provider

terraform state replace-provider \
  "registry.terraform.io/hashicorp/aws" \
  "registry.terraform.io/myorg/aws"

The replace-provider command replaces the provider in the state. The command is used when migrating from one provider namespace to another.

The replace-provider command is appropriate for:

• Migrating from a community provider to a HashiCorp provider.
• Migrating from one provider namespace to another.
• Migrating from terraform-provider-X to the new registration.

The command is destructive if the new provider has a different schema. The apply after the replace-provider may propose to recreate every resource.

The production rules

The state-mutating commands are operator tools. The production rules:

1. Backup the state before any state-mutating command.
2. Verify the plan is empty after the command.
3. Document the command in the change log.
4. Run the command in a maintenance window.
5. Have a second engineer review the command.

The state-mutating commands can fix problems that the plan/apply workflow cannot. They can also create problems that the plan/apply workflow cannot fix.

The state-lock mechanism

The state-lock is for the plan/apply workflow. The state-mutating commands also acquire the lock:

# This will fail if the state is locked by another operation
terraform state mv aws_instance.web aws_instance.app_server

# Output: "Error acquiring the state lock"

The state-mutating commands are designed to be safe in the sense that they do not modify the real world. They are not safe in the sense that they modify the state without the plan/apply workflow.

The state operations in CI

The state-mutating commands should not be in CI:

# Bad: state mv in CI
terraform state mv aws_instance.web aws_instance.app_server

# Good: CI uses plan/apply only
terraform plan
terraform apply

The state-mutating commands are operator tools. CI should use the plan/apply workflow.

What comes next

The next lesson is state backup and recovery — the production control for state loss.

Verification