Skip to content

Store Terraform state in GCS

When you finish, every terraform apply for your GCP cluster reads and writes its state in a versioned bucket that your operator group manages.

GCS locks state on its own, so you need no lock table.

Before you start

  • A GCP project with billing enabled
  • IAM permissions for storage.buckets.create and storage.objects.* on the state bucket
  • gcloud signed in with Application Default Credentials (gcloud auth application-default login)
  • Terraform 1.11 or later

1. Create a versioned bucket

gcloud storage buckets create gs://my-terraform-state-bucket \
  --project=my-tfstate-project \
  --location=us-central1 \
  --uniform-bucket-level-access

gcloud storage buckets update gs://my-terraform-state-bucket --versioning

Both commands finish without an error, and the bucket keeps every prior revision of your state.

2. Point Terraform at the bucket

terraform {
  backend "gcs" {
    bucket = "my-terraform-state-bucket" # <-- Replace with your bucket name
    prefix = "qumulo/gcp/prod"           # <-- Replace with your path in the bucket
  }
}

Run terraform init -upgrade. If local state already exists, Terraform offers to migrate it into the bucket.

The output ends with Successfully configured the backend "gcs"!

3. Lock down the bucket

Grant your operator group object access on the bucket and nothing wider. Replace tf-operators@example.com with your group.

gcloud storage buckets add-iam-policy-binding gs://my-terraform-state-bucket \
  --member=group:tf-operators@example.com \
  --role=roles/storage.objectAdmin

Save this as lifecycle.json to delete non-current state versions after 90 days, then apply it.

{
  "rule": [
    {"action": {"type": "Delete"}, "condition": {"daysSinceNoncurrentTime": 90}}
  ]
}

gcloud storage buckets update gs://my-terraform-state-bucket --lifecycle-file=lifecycle.json

Confirm that versioning is on.

gcloud storage buckets describe gs://my-terraform-state-bucket --format="value(versioning_enabled)"

The command prints True.

Next

Deploy your cluster with the basic GCP cluster example. When you need another backend option, see the Terraform gcs backend reference.