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)

# State 用 Bucket 事前作成 (1 回だけ手動)
gcloud storage buckets create gs://tfstate-PROJECT \
  --location=asia-northeast1 \
  --uniform-bucket-level-access
gcloud storage buckets update gs://tfstate-PROJECT --versioning

# CMEK 暗号化推奨
gcloud storage buckets update gs://tfstate-PROJECT \
  --default-encryption-key=projects/PROJECT/locations/.../cryptoKeys/tfstate

# Backend 設定後 terraform init で初期化
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
}

# 利用側
module "vpc" {
  source = "./modules/vpc"
  name   = "prod-vpc"
  cidr   = "10.0.0.0/16"
}

# 公式 Module 活用
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/           # 再利用 Module
│   ├── vpc/
│   ├── gke/
│   └── cloudsql/
├── envs/
│   ├── dev/
│   │   ├── main.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   └── prod/
└── global/            # 全環境共通 (IAM / Org Policy)
    └── main.tf

Workload Identity Federation (GitHub Actions)

# .github/workflows/terraform.yml
permissions:
  contents: read
  id-token: write   # 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.