Resources and Resource Addressing

A resource block is the unit of everything Terraform manages — one block maps to one real object created through a GCP API, like the hatch-events-raw bucket or the event-processor service. It is the smallest thing Terraform creates, updates, and destroys, and almost every line of HCL you write either declares a resource or feeds one.

Every resource has an address of the form type.name, and that address is not cosmetic. It is the resource's identity in state, the handle you use in references, the argument you pass to CLI commands and import, and the thing that decides whether renaming a resource is a harmless no-op or a destroy-and-recreate that takes your data with it.

The Resource Block

A resource block has two labels and a body. The first label is the provider's resource type — google_storage_bucket — which the google provider knows how to create. The second is the local name you choose — raw — which is yours to pick and only has meaning inside this module. The body is the desired-state arguments: what the object should look like.

resource "google_storage_bucket" "raw" {
  name     = "hatch-events-raw"   # the GCP object's real, globally-unique name
  location = "US"
}

Read it as: declare a managed Cloud Storage bucket, refer to it locally as raw, and make its real GCP name hatch-events-raw. Notice that the second label and the name argument are two different things — one is Terraform's handle, the other is the cloud's name. That distinction is the heart of this topic.

The Address type.name

The address google_storage_bucket.raw uniquely identifies this resource within its module. You use it two ways. To read one of the resource's attributes elsewhere in config, you append the attribute: google_storage_bucket.raw.url gives the bucket's URL once it exists. And to operate on the resource from the CLI — terraform state show, terraform apply -replace, -target — you name it by this same address.

Because the address is how everything refers to the resource, it is a stable contract. Other resources, outputs, and your CLI muscle memory all depend on it. That is exactly why changing it is consequential, which the next sections make concrete.

Instance Keys

A plain resource has one instance and the bare address points at it. Add count and the resource becomes a list: google_pubsub_topic.t[0], google_pubsub_topic.t[1], addressed by integer index. Add for_each and it becomes a map: google_pubsub_topic.t["events-ingest"], addressed by string key. The bracketed key is part of the address and part of the identity in state.

That difference has teeth. With count, the index is positional — remove an element from the middle of the list and every later instance shifts down, so Terraform sees a cascade of destroys and creates. With for_each, the key is the meaningful identifier events-ingest itself, so adding or removing one topic touches only that one. This is why for_each is the default for any set of similar resources.

The Address Is Identity in State

Terraform tracks resources by address, not by the GCP object's name. The state file maps google_storage_bucket.raw to whatever real bucket it created. So when you rename the local name from raw to events_raw, Terraform sees an old address with no config and a new address with no state — and plans to destroy hatch-events-raw and create a fresh bucket under the new address.

That destroy takes the data with it, which is almost never what a rename was supposed to mean. The fix is to tell Terraform the resource moved rather than disappeared, using a moved block in config or terraform state mv on the CLI. Either one rewrites the address in state without touching the cloud object, turning a catastrophic destroy/create into a no-op.

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

Meta-Arguments Overview

Most arguments in a resource block are resource-specific — location, name, cidr_block. A handful are not: count, for_each, provider, depends_on, and lifecycle are meta-arguments, understood by the Terraform engine itself rather than the provider. They share one trait — each changes how a resource is managed rather than what it is — and each gets its own treatment in the topics ahead.