Terraform GCP

Terraform + GCP

File Organization

Per references/terraform-style-guide.md (HashiCorp):

For larger modules, split main.tf into purpose-grouped files (references/general-style-and-structure.md, Google):

# dns.tf — google_dns_managed_zone + google_dns_record_set together
# network.tf — VPC, subnets, firewall rules together

Formatting

• 2 spaces per nesting level, no tabs — always run terraform fmt -recursive
• Align = for consecutive arguments in the same block
• Block order within a resource:
  1. Meta-arguments (count, for_each, provider, depends_on)
  2. Arguments
  3. Nested blocks
  4. lifecycle last

Naming Conventions

• lowercase_underscores for all resource/variable/output names
• Descriptive nouns — no resource type in the name
• Singular, not plural
• Use main when there is only one of a type

# Bad
resource "google_compute_global_address" "main_global_address" {}
resource "google_storage_bucket" "buckets" {}

# Good
resource "google_compute_global_address" "main" {}
resource "google_storage_bucket" "artifacts" {}

Variables

Every variable needs type + description. Add validation for constrained inputs. Mark sensitive = true for secrets. Don't provide defaults for environment-specific values like project_id — force the caller to provide them.

GCP-specific naming:

• Numeric values: include units — ram_size_gb, disk_size_gib
• Storage: binary prefixes (kibi, mebi, gibi); all other measurements: decimal
• Booleans: positive names — enable_external_access, not disable_internal

variable "ram_size_gb" {
  description = "RAM per instance in gibibytes"
  type        = number
}

variable "environment" {
  description = "Deployment environment"
  type        = string

  validation {
    condition     = contains(["dev", "qa", "prod"], var.environment)
    error_message = "Must be dev, qa, or prod."
  }
}

Outputs

Every output needs description. Mark sensitive = true where appropriate.

Never pass an input variable directly as an output — always reference a resource attribute to preserve the dependency graph:

# Bad — breaks implicit dependencies
output "bucket_name" {
  value = var.bucket_name
}

# Good — reference the resource attribute
output "bucket_name" {
  description = "Name of the storage bucket"
  value       = google_storage_bucket.main.name
}

for_each vs count

• for_each — multiple named resources (stable identity, survives reordering)
• count — conditional creation only
• Use a separate enable_x boolean for conditional logic; don't drive count directly from resource attributes that may be unknown at plan time

# Multiple resources — use for_each
resource "google_storage_bucket" "regional" {
  for_each = toset(var.regions)
  name     = "data-${each.key}"
  location = each.key
}

# Conditional — use count
resource "google_monitoring_alert_policy" "latency" {
  count        = var.enable_alerts ? 1 : 0
  display_name = "High Latency Alert"
}

Dependency Management (CRITICAL)

Prefer implicit over explicit. Reference output attributes — not input args — to create real ordering. Input args are known at plan time and create no dependency; output attrs are only known after creation.

# Bad — .name is an input arg, Terraform sees no dependency
bucket = google_storage_bucket.main.name

# Good — .id is an output attr, creates real implicit dependency
bucket = google_storage_bucket.main.id

Module dependency — implicit via output reference:

# Bad — depends_on is a blunt instrument, slows planning
module "bigquery" {
  project_id = var.project_id
  depends_on = [module.project_services]
}

# Good — implicit dependency, Terraform tracks exactly what changed
module "bigquery" {
  project_id = module.project_services.project_id
}

Use depends_on only as a last resort. Always add a comment explaining why.

Cross-config dependencies: use terraform_remote_state (GCS backend). Don't use data sources to reference resources managed by another Terraform config.

IAM — Authoritative vs Additive (CRITICAL)

Authoritative resources silently remove Google's auto-managed service account roles, breaking Cloud services. Default to google_*_iam_member.

# Bad — removes all other IAM, including Google-managed bindings
resource "google_project_iam_policy" "main" {
  project     = var.project_id
  policy_data = data.google_iam_policy.admin.policy_data
}

# Good — additive, safe
resource "google_project_iam_member" "invoker" {
  project = var.project_id
  role    = "roles/run.invoker"
  member  = "serviceAccount:${google_service_account.worker.email}"
}

Stateful Resource Protection

Add lifecycle { prevent_destroy = true } to databases, buckets, and other stateful resources:

resource "google_sql_database_instance" "main" {
  name             = "primary"
  database_version = "POSTGRES_15"

  lifecycle {
    prevent_destroy = true
  }
}

Compute / VM

• Bake images with Packer — do NOT use provisioners for configuration
• Pass runtime config via instance metadata, not provisioner scripts

Version Pinning

Root modules — pin to minor, allow patch updates:

terraform {
  required_version = ">= 1.7"

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 6.0.0"
    }
  }
}

Reusable modules — permissive >=, let callers decide:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0.0"
    }
  }
}

Root Module Structure

service/
├── OWNERS
├── modules/
│   └── <service-name>/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── README.md
└── environments/
    ├── dev/
    │   ├── backend.tf        # GCS backend
    │   ├── main.tf           # Instantiates service module
    │   └── terraform.tfvars
    ├── qa/
    └── prod/

• Max ~100 resources per state (ideally a few dozen) — per references/root-modules.md (Google)
• One directory per application/service; nest all code under it
• Default workspace only — no multiple CLI workspaces
• Variables in terraform.tfvars; check in .terraform.lock.hcl
• Never commit: .terraform/, *.tfstate, *.tfstate.backup, *.tfplan

Reusable Module Rules

• No provider or backend config — root modules own these
• Expose labels = {} variable for every module
• Every resource defined in the module must have at least one output
• Enable APIs via google_project_service; expose enable_apis = true variable; always set disable_services_on_destroy = false
• Inline submodules in modules/<name>/
• Use moved blocks when refactoring to prevent destroy/recreate
• Release with SemVer; callers reference with ~> major.0

Testing

Two categories of .tftest.hcl tests:

run "bucket_name_follows_convention" {
  command = plan

  assert {
    condition     = google_storage_bucket.main.name == "myproject-artifacts"
    error_message = "Bucket name does not match expected pattern."
  }
}

Key practices:

• Randomize resource names/project IDs to avoid collisions
• Use a dedicated test project isolated from dev/prod
• Always destroy after tests: terraform destroy or project_cleanup module
• Run independent tests in parallel: test { parallel = true }
• Order: terraform validate → unit tests → integration tests → e2e

See references/terraform-test.md for full .tftest.hcl syntax, mock providers, expect_failures, and parallel execution rules.

Import / Export

Export existing GCP resources:

gcloud beta resource-config bulk-export \
  --project=MY_PROJECT \
  --resource-format=terraform \
  --path=./exported/

Import one resource:

terraform import google_storage_bucket.main my-project/my-bucket

Bulk import with generated config (Terraform 1.5+):

import {
  id = "projects/MY_PROJECT/global/networks/my-network"
  to = google_compute_network.main
}

terraform plan -generate-config-out=generated.tf

See references/import-google-cloud-resources.md and references/export-google-cloud-resources.md for full workflows.

Reference Files