State Surgery

State surgery is editing what Terraform thinks exists without touching what actually exists. Three operations do it: terraform state rm drops a resource from state, terraform state mv renames its address, and the -replace= plan flag forces a recreate. You reach for them when the map — your state — and the territory — the real GCP API — have diverged, and no amount of HCL editing reconciles the two.

Every one of these commands is a loaded gun. The state file has no undo, so a wrong rm orphans a live resource that still bills and a wrong mv makes the next apply quietly delete and recreate something in production. Treat surgery as the fallback, not the first move, and reach for the declarative replacements — moved blocks and import — before you ever touch the CLI.

state rm — Forget, Don't Destroy

terraform state rm drops a resource from state without destroying it on GCP. Terraform simply stops managing it; the live resource keeps running, keeps billing, and is now invisible to your configuration. The legitimate uses are narrow: handing a resource off to a different configuration that will import it, or abandoning one you have decided to manage by hand from now on.

The danger is the opposite of what people expect. rm does not delete — it forgets. Run it on a resource you meant to destroy and the Cloud SQL instance is still there, still serving, still on the bill, and Terraform will never propose to clean it up because as far as state is concerned it does not exist. A forgotten resource is an unmanaged orphan that nobody tracks until the invoice arrives.

# Terraform forgets this SA; the live service account is untouched and still works
terraform state rm 'google_service_account.event_processor'

state mv — Rename the Address

terraform state mv changes a resource's address in state, which you need whenever you rename a resource in HCL or move it into a module. Done right, the plan afterward is empty — you told Terraform the new name points at the same real object. Skipped or done wrong, the next apply sees the old address gone and a new one appearing, so it destroys the old resource and creates the new.

For the Hatch event-processor service account, an un-mv'd rename is not cosmetic. Terraform destroys google_service_account.event_processor and creates a fresh google_service_account.processor with a new identity, which means every IAM binding that referenced the old account silently stops pointing at anything that has the permissions — a working pipeline broken by what looked like a rename.

# You renamed the resource in HCL from event_processor to processor
terraform state mv \
  'google_service_account.event_processor' \
  'google_service_account.processor'

-replace= — Force a Clean Recreate

-replace=ADDRESS is the modern replacement for the deprecated taint. It forces one resource to be destroyed and recreated on the next apply without editing state at all — you pass it to plan or apply and Terraform marks just that resource for replacement. Reach for it when a resource is wedged: a half-created Cloud SQL instance, a managed instance group that drifted into a state the provider cannot reconcile, anything where a clean recreate is the actual fix.

Because it triggers a real destroy-and-create, read the plan first. On a stateless resource the recreate is harmless; on a regional Cloud SQL primary it is an outage. The flag is a scalpel, not a reset button — it does exactly one recreate, but that recreate is as consequential as any other.

# Replaces the deprecated `terraform taint`; check the plan for downtime first
terraform apply -replace='google_sql_database_instance.replica'

Why Hand-Editing State Is the Last Resort

terraform state pull and push let you fetch the raw JSON, edit it, and write it back — and that bypasses every safety check the CLI gives you. Hand-editing can corrupt the serial (the write counter) or the lineage (the UUID identifying the state's history), and against a remote GCS backend it races every other writer. Get the serial wrong and the next remote write is rejected as out of order.

If you find yourself hand-editing JSON, you have almost always skipped a tool that would have done the change safely. A rename belongs in a moved block; pulling an existing resource under management belongs in import. Hand-editing is what you do when nothing else can express the change, and that situation is rarer than it feels in the moment.

The Safer, Declarative Replacements

moved blocks turn a rename or a module-move into a declarative, committed, reviewable change. You add the block to your configuration, it ships in a PR, and everyone's next plan applies the move — no one runs a one-off CLI command on one laptop. import (and import blocks) pulls an existing resource into state without any surgery at all. Reach for both of these before state mv or rm; they leave a trace in the code, and the CLI commands leave none.

# Committed to git, applied by everyone's next plan, reviewable in the PR
moved {
  from = google_service_account.event_processor
  to   = google_service_account.processor
}