Terraform on GCP Complete Guide: IaC, Providers, Workload Identity & GitHub Actions

Terraform on GCP is the de facto Infrastructure as Code (IaC) standard for production GCP environments. This article covers provider setup, state management, Workload Identity Federation, module design, GitHub Actions integration, and cost estimation.

Initial Setup

# main.tf
terraform {
  required_version = ">= 1.6.0"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 6.0"
    }
    google-beta = {
      source  = "hashicorp/google-beta"
      version = "~> 6.0"
    }
  }
  backend "gcs" {
    bucket = "tfstate-PROJECT"
    prefix = "envs/prod"
  }
}

provider "google" {
  project = "my-project"
  region  = "asia-northeast1"
}

provider "google-beta" {
  project = "my-project"
  region  = "asia-northeast1"
}

Typical Resource Examples

# VPC
resource "google_compute_network" "vpc" {
  name                    = "main-vpc"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnet" {
  name          = "main-subnet"
  network       = google_compute_network.vpc.id
  ip_cidr_range = "10.0.0.0/24"
  region        = "asia-northeast1"
  private_ip_google_access = true
}

# GKE Autopilot
resource "google_container_cluster" "primary" {
  provider                 = google-beta
  name                     = "primary-cluster"
  location                 = "asia-northeast1"
  enable_autopilot         = true
  network                  = google_compute_network.vpc.id
  subnetwork               = google_compute_subnetwork.subnet.id
  release_channel { channel = "STABLE" }
}

# Cloud Run
resource "google_cloud_run_v2_service" "app" {
  name     = "my-app"
  location = "asia-northeast1"
  template {
    containers {
      image = "asia-northeast1-docker.pkg.dev/PROJECT/repo/app:v1"
      resources {
        limits = { cpu = "1", memory = "512Mi" }
      }
    }
  }
}

# BigQuery Dataset
resource "google_bigquery_dataset" "main" {
  dataset_id  = "analytics"
  location    = "asia-northeast1"
  description = "Main analytics dataset"
  labels      = { env = "prod", team = "data" }
}

State Management (GCS Backend)

# Create the state bucket up front (once, by hand)
gcloud storage buckets create gs://tfstate-PROJECT \
  --location=asia-northeast1 \
  --uniform-bucket-level-access
gcloud storage buckets update gs://tfstate-PROJECT --versioning

# CMEK encryption recommended
gcloud storage buckets update gs://tfstate-PROJECT \
  --default-encryption-key=projects/PROJECT/locations/.../cryptoKeys/tfstate

# Run terraform init after configuring the backend
terraform init

Module Design

# modules/vpc/main.tf
variable "name" { type = string }
variable "cidr" { type = string }

resource "google_compute_network" "vpc" {
  name                    = var.name
  auto_create_subnetworks = false
}

# Consumer side
module "vpc" {
  source = "./modules/vpc"
  name   = "prod-vpc"
  cidr   = "10.0.0.0/16"
}

# Use the official modules
module "gke" {
  source  = "terraform-google-modules/kubernetes-engine/google//modules/beta-autopilot-private-cluster"
  version = "~> 31.0"
  project_id        = var.project_id
  name              = "my-cluster"
  region            = "asia-northeast1"
  network           = module.vpc.network_name
  subnetwork        = module.vpc.subnet_name
  ip_range_pods     = "pods"
  ip_range_services = "services"
}

Per-Environment Directory Layout

terraform/
├── modules/           # reusable modules
│   ├── vpc/
│   ├── gke/
│   └── cloudsql/
├── envs/
│   ├── dev/
│   │   ├── main.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   └── prod/
└── global/            # shared across environments (IAM / Org Policy)
    └── main.tf

Workload Identity Federation (GitHub Actions)

# .github/workflows/terraform.yml
permissions:
  contents: read
  id-token: write   # required to obtain the OIDC token

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: projects/123/locations/global/workloadIdentityPools/github/providers/repo
          service_account: [email protected]
      - uses: hashicorp/setup-terraform@v3
      - run: terraform init
      - run: terraform plan
      - run: terraform apply -auto-approve
        if: github.ref == 'refs/heads/main'

GCP-side Pool / Provider Setup

gcloud iam workload-identity-pools create github --location=global

gcloud iam workload-identity-pools providers create-oidc repo \
  --location=global --workload-identity-pool=github \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repo=assertion.repository"

gcloud iam service-accounts add-iam-policy-binding [email protected] \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/github/attribute.repo/owner/repo"

Cost Estimation (Infracost)

# GitHub Action
- uses: infracost/actions/setup@v3
  with:
    api-key: ${{ secrets.INFRACOST_API_KEY }}
- run: infracost breakdown --path=. --format=json --out-file=infracost.json
- uses: infracost/actions/comment@v3
  with:
    path: infracost.json

Best Practices

• Always store state in a GCS backend (with Lock and Versioning)
• Use Workload Identity Federation; never use long-lived SA keys
• Make components reusable through modules
• Run terraform fmt and validate as a pre-commit hook
• Run static checks with tflint, checkov, and tfsec
• Drive operations from PRs via Atlantis or Terraform Cloud
• Encrypt state with CMEK
• Fully isolate environments by account or project

* Google Cloud is a trademark of Google LLC. Terraform is a registered trademark of HashiCorp. For the latest information, see the official Google Provider docs.