Skip to content

Terraform Usage Guide

Complete guide to using Terraform for managing CAMARADES infrastructure.

Prerequisites

  • Terraform >= 1.6.0 installed
  • Google Cloud SDK configured
  • Access to camarades-net GCP project
  • Permissions: roles/container.admin, roles/iam.serviceAccountUser

Initial Setup

1. Authenticate with GCP

# Authenticate
gcloud auth login
gcloud auth application-default login

# Set project
gcloud config set project camarades-net

2. Create State Bucket (One-Time)

Terraform state is stored in a GCS bucket for collaboration and safety.

# Create bucket
gsutil mb -p camarades-net -l europe-west2 gs://camarades-terraform-state

# Enable versioning
gsutil versioning set on gs://camarades-terraform-state

# Verify
gsutil ls gs://camarades-terraform-state

3. Initialize Terraform

cd terraform/
terraform init

Expected output: 

Initializing the backend...
Successfully configured the backend "gcs"!

Terraform has been successfully initialized!

Daily Workflow

Making Infrastructure Changes

1. Update Terraform Configuration

Edit the relevant .tf files: - main.tf - Cluster and node pool configuration - variables.tf - Variable definitions - backend.tf - State backend (rarely changed)

Example: Change node count 

# terraform/variables.tf
variable "node_count" {
  default     = 4  # was: 3
}

2. Review Changes

terraform plan

Read the plan carefully! Look for: - ✅ Changes that match your intent - ⚠️ Unexpected changes (investigate before applying) - ❌ Resource destruction (ensure this is intentional)

3. Apply Changes

terraform apply

Type yes when prompted after reviewing the plan.

4. Verify Changes

# Check cluster
gcloud container clusters describe camaradesuk --zone=europe-west2-a

# Check nodes
kubectl get nodes

Common Operations

View Current State

terraform show

View Specific Resource

terraform state show google_container_cluster.camaradesuk

List All Resources

terraform state list

Output Values

# Show all outputs
terraform output

# Show specific output
terraform output cluster_endpoint

Format Code

terraform fmt

Validate Configuration

terraform validate

Advanced Operations

Import Existing Resources

If a resource exists in GCP but not in Terraform state:

# Import cluster
terraform import google_container_cluster.camaradesuk europe-west2-a/camaradesuk

# Import node pool
terraform import google_container_node_pool.primary_nodes europe-west2-a/camaradesuk/default-pool

Refresh State

Sync Terraform state with actual GCP resources:

terraform refresh

Replace a Resource

Force recreation of a resource:

terraform apply -replace="google_container_node_pool.primary_nodes"

Target Specific Resources

Apply changes to specific resources only:

terraform apply -target=google_container_node_pool.primary_nodes

⚠️ Warning: Use targets sparingly, as they can lead to inconsistent state.

State Management

Viewing State

# Show full state
terraform show

# Show JSON format (parseable)
terraform show -json

State Locking

GCS backend automatically handles state locking. If a lock gets stuck:

# Force unlock (use with caution)
terraform force-unlock <LOCK_ID>

State Backups

State is automatically backed up in GCS with versioning enabled.

# List versions
gsutil ls -a gs://camarades-terraform-state/gke/camaradesuk/

# Restore previous version if needed
gsutil cp gs://camarades-terraform-state/gke/camaradesuk/default.tfstate#<version> terraform.tfstate

Troubleshooting

Error: "Backend Initialization Required"

terraform init -reconfigure

Error: "State Lock Could Not Be Acquired"

Someone else is running Terraform, or a previous run crashed.

# Wait for lock to release, or
terraform force-unlock <LOCK_ID>

Error: "Provider Configuration Error"

# Re-authenticate
gcloud auth application-default login

# Verify project
gcloud config get-value project

Changes Not Applying

# Refresh state
terraform refresh

# Re-plan
terraform plan

Safety Guidelines

⚠️ CRITICAL Rules

  1. Always run plan before apply
  2. Never commit .tfvars files with secrets
  3. Coordinate with team before infrastructure changes
  4. Test in a non-production environment first (if possible)
  5. Have a rollback plan before applying destructive changes

Pre-Apply Checklist

  • Read the plan output carefully
  • Understand what will change and why
  • Verify no unexpected resource destruction
  • Have a backup/rollback plan
  • Coordinate with team if during business hours
  • Consider maintenance window for disruptive changes

External Resources