Refactoring with moved Blocks

Rename google_storage_bucket.raw to google_storage_bucket.events_raw and Terraform, seeing an old address disappear and a new one appear, plans to destroy and recreate the bucket. For a bucket holding pipeline data, that is a disaster: the rename you meant as a cosmetic change becomes a data loss. The moved block is the fix.

A moved block tells Terraform that the resource did not disappear — it just changed address. With it, the plan becomes a no-op state rename instead of a destroy-and-create, and not a single byte of the bucket is touched. It is the difference between a safe refactor and an accidental deletion, and it belongs in every rename and every move into or out of a module.

Why Renames Look Like Destroys

Terraform keys state by resource address, not by GCP identity. When you change the address in HCL, the old address google_storage_bucket.raw now has no config behind it — which reads as "destroy this" — while the new address google_storage_bucket.events_raw has no state behind it, which reads as "create this." Terraform sees a deletion and an addition, even though the same bucket is meant by both.

Nothing about the actual GCP resource has changed; the only thing that moved is the label in your config. But Terraform has no way to know that the two addresses refer to one object unless you tell it — and that is exactly what the moved block does.

The moved Block

A moved block records the rename in config: it names the from address and the to address, and the next plan shows a state move with no resource change. Because it lives in the config and is committed, every teammate and CI run replays the same rename automatically when they apply — nobody has to be told to run anything by hand.

moved {
  from = google_storage_bucket.raw
  to   = google_storage_bucket.events_raw
}

resource "google_storage_bucket" "events_raw" {   # the new address
  name     = "hatch-events-raw"
  location = "US"
}

The to address must match the renamed resource exactly. With the block in place, the plan reports a move and zero changes to the bucket itself — Terraform rewrites the address in state and leaves the GCP object alone.

moved vs terraform state mv

Both moved and the imperative terraform state mv rewrite an address in state. The difference is who sees it. A moved block is declarative: it appears in the plan diff, is reviewable in a pull request, and is replayed automatically by anyone who applies the config. state mv is a one-shot you run locally — it moves the address in your state and nobody else's, with no record in the config for others to replay.

For a shared config, that gap is the whole problem. Run state mv on your machine, and your state is moved while the committed config and every teammate's state still show the old address — so the next person's plan proposes the destroy-and-create you thought you had prevented. For anything in a shared repo, prefer moved.

Refactoring Into and Out of Modules

A resource's address also changes when you pull it into a module or push it out. Extract the Hatch ingest resources into a module and google_storage_bucket.raw becomes module.ingest.google_storage_bucket.raw — a new address, which without a moved block reads as destroy-the-old, create-the-new. The moved block handles the module-prefix change exactly as it handles a flat rename.

This is what makes "extract a module from existing resources" a safe operation rather than a rebuild. You write the module, write a moved block per resource mapping the old flat address to the new module-qualified one, and the plan is a set of state moves with no infrastructure change. The same works in reverse when you inline a module back into the root.

Lifecycle and Cleanup

moved blocks are cheap to leave in place — they document the history of a refactor and cost nothing on a plan once applied. But they are not permanent fixtures: once every environment's state has applied the move, you can remove them in a later cleanup. The one rule is to keep them until every state has caught up, because a stale state that never saw the move will run the destroy-and-create the block was preventing.

For risky refactors on data-bearing resources, pair the move with a seatbelt. Put prevent_destroy on the state bucket, hatch-events-raw, and any database, so that if a moved block is missing or mistyped, the plan fails loudly on the attempted destroy instead of quietly deleting data. The lifecycle guard turns a missed moved from an outage into an error message.