The GCS Backend & Native Locking

The gcs backend stores Terraform state in a Cloud Storage bucket, and the single most important thing to know is that it locks state natively, using GCS object-generation preconditions. There is no DynamoDB-style lock table to provision, as there is on AWS. You declare a backend "gcs" block with a bucket and a prefix, point it at a versioned, CMEK-encrypted bucket, and you have remote state, locking, and history from one resource instead of two.

This is the moment the Hatch pipeline's state leaves the laptop. The hatch-pipeline-dev config has been running on a local terraform.tfstate file; now it moves into the shared hatch-tfstate bucket where a team and CI can run against the same record. The migration is a few lines of configuration, and the GCS backend's native locking is why those few lines are all it takes.

The Backend Block

The backend is declared inside the terraform block. It names the bucket that holds state and a prefix — note prefix, not S3's key — which is a folder-like path under which Terraform writes default.tfstate. The prefix is what lets one bucket hold many configs side by side: each gets its own path and never collides with another.

terraform {
  backend "gcs" {
    bucket = "hatch-tfstate"      # dedicated, versioned state bucket
    prefix = "pipeline-dev"       # folder-like path, not S3's "key"
  }
}

After adding this block you run terraform init, and Terraform offers to migrate the existing local state into the bucket. From then on, state lives in gs://hatch-tfstate/pipeline-dev/default.tfstate, and every plan and apply reads and writes there.

Native Object-Based Locking

Before any write, the backend creates a <prefix>/default.tflock object using an object-generation precondition — a conditional create that succeeds only if the object does not already exist. If the lock object is already there, the lock is held, and the run blocks until it clears. The lock is just an object in the same state bucket, so there is nothing extra to run, pay for, or keep in sync.

This is the whole GCP story on locking, and it is genuinely simpler than the AWS one. On AWS, S3 stores state but cannot lock itself, so the classic setup adds a separate DynamoDB table for the lock. On GCP that second resource does not exist: the bucket that stores state also locks it. One resource, locking included.

Object Versioning for History and Recovery

Enable object versioning on the state bucket and every apply leaves the prior state as a non-current version of the object. Recovering from a bad apply is then a matter of restoring the previous generation of the state object — not hunting for a separate backup you hopefully remembered to take.

This is not on by default, and the time you discover it was off is exactly the time you needed it. A corrupt or truncated state write with versioning enabled is a one-command rollback; the same write without versioning can be unrecoverable. Turn it on when you create the bucket, before the first apply ever runs against it.

CMEK Encryption of the Bucket

State is encrypted at rest by default with Google-managed keys, but the state bucket is a high-value target that warrants more. Set a customer-managed encryption key (CMEK) on the bucket so that reading the state bytes also requires access to the key — and key access is itself an IAM-governed, auditable control with its own logs. The crown jewels deserve a second lock whose every use is recorded.

resource "google_storage_bucket" "tfstate" {
  name     = "hatch-tfstate"
  location = "US"

  versioning { enabled = true }       # every apply leaves a recoverable prior version

  uniform_bucket_level_access = true   # IAM only, no per-object ACLs

  encryption {
    default_kms_key_name = google_kms_crypto_key.tfstate.id   # CMEK
  }
}

This is the bucket the Hatch pipeline points its backend at: versioned for recovery, CMEK-encrypted so key access is logged, and locked to uniform IAM. It is created in a separate bootstrap step, never by the config it backs.

Uniform Bucket-Level Access and the prefix Layout

Turn on uniform bucket-level access so the bucket is governed purely by IAM, with no per-object ACLs that can be mis-set and leak a single state object while the bucket as a whole looks locked down. With uniform access, there is exactly one place access is decided — the bucket's IAM policy — and exactly one place to audit it.

The prefix is then how multiple states share that one hardened bucket. Give each environment and layer its own prefix — pipeline-dev, pipeline-staging, org — and they coexist in hatch-tfstate without ever touching each other's state. Reusing one prefix for two different configs is the one thing to avoid: they would share default.tfstate and overwrite each other.