GCS backend configuration in Terraform - Commands & Configuration

Introduction

When you use Terraform to manage your cloud resources, you need a safe place to store the information about what you created. The GCS backend lets you save this information in Google Cloud Storage, so your team can share it and avoid conflicts.

When you want to share Terraform state files safely among team members.

When you want to keep your Terraform state files backed up and secure in the cloud.

When you want to enable locking to prevent multiple people from changing infrastructure at the same time.

When you are working on Google Cloud Platform and want to use its storage service for Terraform state.

When you want to separate your state files by environment using different storage buckets or prefixes.

Config File - main.tf

main.tf

terraform {
  backend "gcs" {
    bucket  = "example-terraform-state"
    prefix  = "terraform/state"
    project = "example-project"
  }
}

provider "google" {
  project = "example-project"
  region  = "us-central1"
}

resource "google_storage_bucket" "example_bucket" {
  name     = "example-storage-bucket"
  location = "US"
}

This file configures Terraform to use Google Cloud Storage (GCS) as the backend to store state files.

• terraform.backend.gcs.bucket: The name of the GCS bucket where state files are saved.
• terraform.backend.gcs.prefix: A folder path inside the bucket to organize state files.
• terraform.backend.gcs.project: The Google Cloud project that owns the bucket.
• The provider "google" block sets up access to Google Cloud services.
• The example resource creates a storage bucket to show how Terraform manages resources.

Commands

This command initializes Terraform, sets up the GCS backend, and downloads required plugins.

Terminal

terraform init

Expected Output

Initializing the backend...



Successfully configured the backend "gcs"!



Terraform has been successfully initialized!



You may now begin working with Terraform. Try running "terraform plan" to see

any changes that are required for your infrastructure. All Terraform commands

should now work.



If you ever set or change backend configuration, run this command again to

reinitialize your working directory. If you forget, other commands will detect

it and remind you to do so if necessary.

This command shows what Terraform will create or change in your Google Cloud resources.

Terminal

terraform plan

Expected Output

Refreshing Terraform state in-memory prior to plan...



An execution plan has been generated and is shown below.

Resource actions are indicated with the following symbols:

  + create



Terraform will perform the following actions:



  # google_storage_bucket.example_bucket will be created

  + resource "google_storage_bucket" "example_bucket" {

      + location = "US"

      + name     = "example-storage-bucket"

    }



Plan: 1 to add, 0 to change, 0 to destroy.

This command applies the changes to create the resources in Google Cloud without asking for confirmation.

Terminal

terraform apply -auto-approve

Expected Output

google_storage_bucket.example_bucket: Creating...

google_storage_bucket.example_bucket: Creation complete after 2s [id=example-storage-bucket]



Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

→

-auto-approve - Skip manual approval to apply changes immediately

This command lists the files in the GCS bucket folder where Terraform stores the state files, verifying the backend storage.

Terminal

gsutil ls gs://example-terraform-state/terraform/state/

Expected Output

gs://example-terraform-state/terraform/state/default.tfstate

Key Concept

If you remember nothing else from this pattern, remember: the GCS backend safely stores Terraform state files in Google Cloud Storage so your team can share and lock infrastructure state.

Common Mistakes

Not creating the GCS bucket before initializing Terraform backend

Terraform backend initialization fails because the bucket does not exist yet.

Create the GCS bucket manually or with Terraform before running 'terraform init'.

Using incorrect bucket name or project ID in backend configuration

Terraform cannot connect to the correct storage location, causing errors.

Double-check the bucket name and project ID are correct and accessible.

Not running 'terraform init' after changing backend settings

Terraform does not update backend configuration, leading to inconsistent state storage.

Always run 'terraform init' after modifying backend configuration.

Summary

Configure Terraform backend in main.tf to use a GCS bucket for state storage.

Run 'terraform init' to initialize the backend and download plugins.

Use 'terraform plan' and 'terraform apply' to manage Google Cloud resources.

Verify state files are stored in the GCS bucket using 'gsutil ls'.