Terraform State Commands
The state file works like a ledger. It records every resource Terraform manages and the real-world ID behind each one. Editing that ledger by hand risks corruption, so Terraform ships a set of terraform state commands for safe changes. These commands inspect, rename, and remove records. None of them touches real infrastructure, which makes them gentle tools for housekeeping.
What State Commands Touch
State commands change the ledger only. Your servers, buckets, and networks stay exactly as they are.
Diagram: Ledger Versus Real World
+-------------------+ +----------------------+
| Your .tf files | | Real cloud account |
+---------+---------+ +-----------+----------+
| |
| +---------------+ |
+----->| State file |<------+
| (ledger) |
+-------+-------+
^
|
terraform state commands edit this box onlyList Everything: terraform state list
The list command prints the address of every resource in the state.
terraform state list
aws_instance.web
aws_s3_bucket.logs
module.network.aws_vpc.mainAdd a filter to narrow the output.
terraform state list aws_instanceInspect One Item: terraform state show
The show command prints every recorded attribute of a single resource.
terraform state show aws_instance.webUse it to find an ID, an IP address, or a setting without opening the raw file.
Rename or Move: terraform state mv
Suppose you rename a resource in code from web to app. Terraform sees an old resource that vanished and a new resource that appeared. Without help, it destroys the old server and builds a new one. The move command updates the ledger so Terraform recognizes the same server under the new name.
terraform state mv aws_instance.web aws_instance.appMoving Into a Module
terraform state mv aws_instance.web module.compute.aws_instance.webRun the move command first. Rename the resource in code second. A follow-up terraform plan should show no changes.
The Modern Alternative: Moved Blocks
Newer Terraform versions record renames inside the code with a moved block. Teammates and pipelines then apply the rename automatically.
moved {
from = aws_instance.web
to = aws_instance.app
}Forget a Resource: terraform state rm
The remove command deletes a record from the ledger. Terraform stops managing that resource, and the real resource keeps running.
terraform state rm aws_s3_bucket.legacyUse it when another team takes ownership of a resource or when you plan to import it into a different configuration. Delete the matching block from your code too. A leftover block makes Terraform try to create the resource again.
Download the State: terraform state pull
The pull command prints the current state as JSON. It works with remote backends too.
terraform state pull > backup.tfstateTake a backup before any risky change.
Upload the State: terraform state push
The push command overwrites the remote state with a local file. Treat it as a last-resort tool. A wrong push replaces the truth with an older copy. Pull a fresh backup first and confirm nobody else is running Terraform.
Replace a Resource: terraform apply -replace
A resource sometimes misbehaves and needs a rebuild. The replace option marks one resource for destroy and create during the next apply.
terraform apply -replace="aws_instance.web"This option replaces the older terraform taint command.
Command Summary
| Command | What It Does | Risk Level |
|---|---|---|
state list | Shows all resource addresses | None |
state show | Shows one resource in detail | None |
state pull | Downloads the state | None |
state mv | Renames or moves a record | Low |
state rm | Removes a record | Medium |
state push | Uploads a state file | High |
Safety Habits
- Pull a backup before every
mv,rm, orpush. - Run
terraform planafter each change and confirm it shows no surprises. - Coordinate with teammates so nobody applies during the edit.
- Never open and edit the raw state file in a text editor.
Key Points
- State commands edit the ledger and leave real infrastructure alone.
state listandstate showinspect resources safely.state mvpreserves a resource after a rename or a move into a module.state rmmakes Terraform forget a resource without deleting it.state pullcreates backups, andstate pushneeds extreme care.movedblocks andapply -replacecover the modern workflows.
