The Plan/Apply Lifecycle

Every change you make on GCP through Terraform runs the same three-phase loop: refresh reads the live state of your resources from the Google Cloud APIs, plan computes the diff between that reality and your HCL, and apply executes the API calls that close the gap. The loop is identical whether you are adding a label to the hatch-events-raw bucket or replacing the event-processor Cloud Run service.

Mastering this loop — and learning to read a plan the way you read a code review — is the difference between confidently shipping a change and praying after you type yes. The plan is a contract: it tells you exactly which API calls Terraform is about to make, in symbols you can scan in seconds once you know them. Reading it carefully is the single most valuable habit in the whole workflow.

Refresh, Plan, Apply

When you run terraform plan, the first thing it does is refresh: for every resource in state it queries that resource's API and asks what is true right now. Does hatch-events-raw still exist? What are its current labels? That refreshed picture of reality is then compared to your configuration, and the difference becomes the list of actions Terraform prints. The plan is read-only — it changes nothing on GCP.

terraform apply re-runs that whole computation — refresh, then diff — and then executes the resulting API calls, prompting you to confirm first. The double computation matters: a bare apply does not blindly trust an earlier plan, it builds a fresh one against current reality. That is safe at a laptop and, as you will see, exactly the property you must pin down in CI.

Reading a Plan

A plan is a list of resources, each prefixed with an action symbol, and under each one a per-attribute diff. Five symbols carry the whole vocabulary. + means create, - means destroy, ~ means update in place, -/+ means replace — destroy the old object and create a new one — and <= marks a data source being read. The -/+ is the one to fear on anything stateful, because replace means the data goes with the old object.

Inside a resource's diff, an attribute shown as (known after apply) is a value GCP assigns at create time and cannot be known in advance — a Cloud Run service's uri, a project number, a generated key. It is not Terraform being uncertain; it is honestly admitting the cloud has not handed back that value yet. The plan below adds one label to the bucket and reads the topic's auto-assigned id.

  # google_storage_bucket.raw will be updated in-place
  ~ resource "google_storage_bucket" "raw" {
        name   = "hatch-events-raw"
      ~ labels = {
          + "pipeline" = "hatch"
        }
    }

  # google_cloud_run_v2_service.processor will be created
  + resource "google_cloud_run_v2_service" "processor" {
        name = "event-processor"
        uri  = (known after apply)
    }

Read top to bottom, the symbol in the left gutter tells you the verb and the indented lines tell you the exact attributes. A disciplined review is mechanical: scan the gutter for any - or -/+, confirm each one is intended, then approve.

Saved Plan Files

terraform plan -out=tfplan writes the exact computed plan to a file on disk. Hand that file to terraform apply tfplan and Terraform executes precisely those actions with no re-computation and no confirmation prompt — it already has an approved plan, so it just runs it. This two-step is the backbone of safe automation.

The reason it matters is timing. Between the moment a plan is reviewed and the moment it is applied, reality can move — someone edits a resource in the Console, another pipeline runs. A bare apply would re-plan against that moved reality and could execute actions nobody approved. A saved plan file guarantees the change that merges is provably the change that was reviewed.

Refresh-Only Runs

Sometimes someone changes a resource outside Terraform — adds a label to hatch-events-raw in the Console, resizes a disk by hand. A normal plan sees that drift as a difference from config and proposes to revert it. terraform plan -refresh-only and terraform apply -refresh-only do the opposite: they reconcile state to match reality without proposing any config changes, absorbing the out-of-band edit into state instead of fighting it.

Use a refresh-only run when the manual change was intentional and you want state to catch up, then decide separately whether to bring that change into your HCL. It is the correct, non-destructive way to handle drift; reverting someone's deliberate Console fix by running a normal apply is how you cause a second incident.

Targeted Operations and Why They Smell

terraform apply -target=google_pubsub_topic.events_ingest restricts the run to one resource and the things it depends on, ignoring the rest of the configuration. It exists as a break-glass tool: when an apply fails partway and leaves state inconsistent, targeting the broken resource lets you recover without re-running everything. That is a legitimate, occasional use.

Routine -target use is a smell. If you reach for it to "just fix this one resource" as a habit, you are applying a subset of your config, leaving state internally inconsistent, and the next full plan surfaces a pile of deferred changes at once. Frequent targeting almost always means your config is too coupled or you are papering over a dependency problem the graph would have caught.