gcp-architecture

name	gcp-architecture
description	Google Cloud Platform architecture patterns and best practices. Use when designing, deploying, or reviewing GCP infrastructure including GKE, Cloud Run, Cloud Functions, BigQuery, and IAM.

Google Cloud Platform Architecture

Comprehensive guide for building secure, scalable infrastructure on Google Cloud Platform.

When to Use

• Designing GCP architecture for new projects
• Deploying applications to GCP services
• Setting up networking (VPC, firewall rules)
• Configuring IAM policies and service accounts
• Working with GKE (Google Kubernetes Engine)
• Optimizing costs and performance

Core Services Overview

Compute

Service	Use Case	Key Features
Compute Engine	Virtual machines	Full control, custom images
GKE	Managed Kubernetes	Autopilot mode, node auto-provisioning
Cloud Run	Serverless containers	Scale to zero, any container
Cloud Functions	Serverless functions	Event-driven, 2nd gen
App Engine	PaaS	Standard/Flexible environments

Storage

Service	Use Case	Key Features
Cloud Storage	Object storage	Multi-regional, lifecycle
Persistent Disk	Block storage (GCE)	SSD/HDD, snapshots
Filestore	Managed NFS	High performance
Cloud SQL	Managed SQL	MySQL, PostgreSQL, SQL Server
Firestore	NoSQL document	Serverless, realtime
BigQuery	Data warehouse	Serverless, petabyte-scale
Cloud Spanner	Global SQL	Horizontal scaling
Memorystore	Managed Redis	In-memory cache

Networking

Service	Use Case	Key Features
VPC	Virtual network	Global, shared VPC
Cloud Load Balancing	Global LB	Layer 4/7, anycast IPs
Cloud CDN	Content delivery	Edge caching
Cloud DNS	DNS management	100% SLA
Cloud NAT	Outbound NAT	No external IPs needed

VPC Architecture

Shared VPC Pattern

┌──────────────────────────────────────────────────────────────────┐
│ Host Project (Shared VPC)                                        │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │ VPC Network: shared-vpc                                    │  │
│  │                                                            │  │
│  │  ┌─────────────────────┐    ┌─────────────────────┐       │  │
│  │  │ Subnet: prod-app    │    │ Subnet: prod-data   │       │  │
│  │  │ 10.0.0.0/20         │    │ 10.0.16.0/20        │       │  │
│  │  │ us-central1         │    │ us-central1         │       │  │
│  │  └─────────────────────┘    └─────────────────────┘       │  │
│  │                                                            │  │
│  │  ┌─────────────────────┐    ┌─────────────────────┐       │  │
│  │  │ Subnet: staging-app │    │ Subnet: staging-data│       │  │
│  │  │ 10.1.0.0/20         │    │ 10.1.16.0/20        │       │  │
│  │  │ us-central1         │    │ us-central1         │       │  │
│  │  └─────────────────────┘    └─────────────────────┘       │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
         │                              │
         ▼                              ▼
┌─────────────────────┐      ┌─────────────────────┐
│ Service Project A   │      │ Service Project B   │
│ (Production)        │      │ (Staging)           │
│                     │      │                     │
│ GKE, Cloud Run      │      │ GKE, Cloud Run      │
│ Cloud SQL           │      │ Cloud SQL           │
└─────────────────────┘      └─────────────────────┘

Terraform VPC

# VPC Network
resource "google_compute_network" "main" {
  name                    = "${var.project_id}-vpc"
  auto_create_subnetworks = false
  routing_mode            = "GLOBAL"
}

# Subnets
resource "google_compute_subnetwork" "app" {
  name          = "${var.project_id}-app-subnet"
  ip_cidr_range = "10.0.0.0/20"
  region        = var.region
  network       = google_compute_network.main.id

  secondary_ip_range {
    range_name    = "pods"
    ip_cidr_range = "10.100.0.0/16"
  }

  secondary_ip_range {
    range_name    = "services"
    ip_cidr_range = "10.200.0.0/20"
  }

  private_ip_google_access = true

  log_config {
    aggregation_interval = "INTERVAL_5_SEC"
    flow_sampling        = 0.5
    metadata             = "INCLUDE_ALL_METADATA"
  }
}

# Cloud NAT
resource "google_compute_router" "main" {
  name    = "${var.project_id}-router"
  region  = var.region
  network = google_compute_network.main.id
}

resource "google_compute_router_nat" "main" {
  name                               = "${var.project_id}-nat"
  router                             = google_compute_router.main.name
  region                             = var.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

  log_config {
    enable = true
    filter = "ERRORS_ONLY"
  }
}

# Firewall Rules
resource "google_compute_firewall" "allow_internal" {
  name    = "${var.project_id}-allow-internal"
  network = google_compute_network.main.name

  allow {
    protocol = "tcp"
  }
  allow {
    protocol = "udp"
  }
  allow {
    protocol = "icmp"
  }

  source_ranges = ["10.0.0.0/8"]
}

resource "google_compute_firewall" "allow_health_checks" {
  name    = "${var.project_id}-allow-health-checks"
  network = google_compute_network.main.name

  allow {
    protocol = "tcp"
  }

  source_ranges = [
    "35.191.0.0/16",   # GCP Health Checks
    "130.211.0.0/22",  # GCP Health Checks
  ]

  target_tags = ["allow-health-checks"]
}

IAM & Service Accounts

Service Account Best Practices

# Application Service Account
resource "google_service_account" "app" {
  account_id   = "${var.project_id}-app-sa"
  display_name = "Application Service Account"
}

# Workload Identity for GKE
resource "google_service_account_iam_binding" "workload_identity" {
  service_account_id = google_service_account.app.name
  role               = "roles/iam.workloadIdentityUser"
  members = [
    "serviceAccount:${var.project_id}.svc.id.goog[${var.namespace}/${var.k8s_service_account}]"
  ]
}

# Grant specific permissions
resource "google_project_iam_member" "app_storage" {
  project = var.project_id
  role    = "roles/storage.objectUser"
  member  = "serviceAccount:${google_service_account.app.email}"

  condition {
    title      = "Only app bucket"
    expression = "resource.name.startsWith('projects/_/buckets/${var.project_id}-app-data')"
  }
}

resource "google_project_iam_member" "app_secretmanager" {
  project = var.project_id
  role    = "roles/secretmanager.secretAccessor"
  member  = "serviceAccount:${google_service_account.app.email}"
}

resource "google_project_iam_member" "app_cloudsql" {
  project = var.project_id
  role    = "roles/cloudsql.client"
  member  = "serviceAccount:${google_service_account.app.email}"
}

Custom IAM Role

resource "google_project_iam_custom_role" "app_deployer" {
  role_id     = "appDeployer"
  title       = "Application Deployer"
  description = "Can deploy applications to Cloud Run and GKE"

  permissions = [
    "run.services.create",
    "run.services.update",
    "run.services.delete",
    "run.services.get",
    "container.deployments.create",
    "container.deployments.update",
    "container.services.create",
    "container.services.update",
  ]
}

GKE (Google Kubernetes Engine)

GKE Autopilot Cluster

resource "google_container_cluster" "main" {
  name     = "${var.project_id}-gke"
  location = var.region

  # Autopilot mode
  enable_autopilot = true

  network    = google_compute_network.main.name
  subnetwork = google_compute_subnetwork.app.name

  ip_allocation_policy {
    cluster_secondary_range_name  = "pods"
    services_secondary_range_name = "services"
  }

  private_cluster_config {
    enable_private_nodes    = true
    enable_private_endpoint = false
    master_ipv4_cidr_block  = "172.16.0.0/28"
  }

  master_authorized_networks_config {
    cidr_blocks {
      cidr_block   = var.authorized_network
      display_name = "Authorized Network"
    }
  }

  release_channel {
    channel = "REGULAR"
  }

  workload_identity_config {
    workload_pool = "${var.project_id}.svc.id.goog"
  }

  # Security
  binary_authorization {
    evaluation_mode = "PROJECT_SINGLETON_POLICY_ENFORCE"
  }

  deletion_protection = var.environment == "prod"
}

GKE Standard Cluster

resource "google_container_cluster" "standard" {
  name     = "${var.project_id}-gke-standard"
  location = var.region

  # Remove default node pool
  remove_default_node_pool = true
  initial_node_count       = 1

  network    = google_compute_network.main.name
  subnetwork = google_compute_subnetwork.app.name

  ip_allocation_policy {
    cluster_secondary_range_name  = "pods"
    services_secondary_range_name = "services"
  }

  workload_identity_config {
    workload_pool = "${var.project_id}.svc.id.goog"
  }

  addons_config {
    http_load_balancing {
      disabled = false
    }
    horizontal_pod_autoscaling {
      disabled = false
    }
    gce_persistent_disk_csi_driver_config {
      enabled = true
    }
  }
}

resource "google_container_node_pool" "primary" {
  name       = "primary-pool"
  cluster    = google_container_cluster.standard.name
  location   = var.region

  node_count = var.environment == "prod" ? 3 : 1

  autoscaling {
    min_node_count = var.environment == "prod" ? 3 : 1
    max_node_count = 10
  }

  management {
    auto_repair  = true
    auto_upgrade = true
  }

  node_config {
    machine_type = "e2-standard-4"
    disk_size_gb = 100
    disk_type    = "pd-ssd"

    oauth_scopes = [
      "https://www.googleapis.com/auth/cloud-platform"
    ]

    service_account = google_service_account.gke_nodes.email

    workload_metadata_config {
      mode = "GKE_METADATA"
    }

    shielded_instance_config {
      enable_secure_boot          = true
      enable_integrity_monitoring = true
    }

    labels = {
      environment = var.environment
    }

    tags = ["gke-node", var.environment]
  }
}

Cloud Run

Cloud Run Service

resource "google_cloud_run_v2_service" "app" {
  name     = "${var.project_id}-app"
  location = var.region
  ingress  = "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER"

  template {
    service_account = google_service_account.app.email

    scaling {
      min_instance_count = var.environment == "prod" ? 1 : 0
      max_instance_count = 100
    }

    containers {
      image = "${var.region}-docker.pkg.dev/${var.project_id}/app/myapp:${var.image_tag}"

      ports {
        container_port = 8080
      }

      resources {
        limits = {
          cpu    = "2"
          memory = "1Gi"
        }
        cpu_idle = true  # Scale to zero
      }

      env {
        name  = "PROJECT_ID"
        value = var.project_id
      }

      env {
        name = "DATABASE_URL"
        value_source {
          secret_key_ref {
            secret  = google_secret_manager_secret.db_url.secret_id
            version = "latest"
          }
        }
      }

      startup_probe {
        http_get {
          path = "/health"
        }
        initial_delay_seconds = 10
        period_seconds        = 3
        failure_threshold     = 3
      }

      liveness_probe {
        http_get {
          path = "/health"
        }
        period_seconds    = 30
        failure_threshold = 3
      }
    }

    vpc_access {
      network_interfaces {
        network    = google_compute_network.main.name
        subnetwork = google_compute_subnetwork.app.name
      }
      egress = "PRIVATE_RANGES_ONLY"
    }
  }

  traffic {
    type    = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST"
    percent = 100
  }
}

# IAM - Allow unauthenticated (public API)
resource "google_cloud_run_v2_service_iam_member" "public" {
  count    = var.public_access ? 1 : 0
  location = google_cloud_run_v2_service.app.location
  name     = google_cloud_run_v2_service.app.name
  role     = "roles/run.invoker"
  member   = "allUsers"
}

# Custom domain
resource "google_cloud_run_domain_mapping" "app" {
  location = var.region
  name     = var.domain

  metadata {
    namespace = var.project_id
  }

  spec {
    route_name = google_cloud_run_v2_service.app.name
  }
}

Cloud SQL

PostgreSQL Instance

resource "google_sql_database_instance" "main" {
  name             = "${var.project_id}-postgres"
  database_version = "POSTGRES_15"
  region           = var.region

  settings {
    tier              = var.environment == "prod" ? "db-custom-4-16384" : "db-f1-micro"
    availability_type = var.environment == "prod" ? "REGIONAL" : "ZONAL"
    disk_size         = 100
    disk_type         = "PD_SSD"
    disk_autoresize   = true

    backup_configuration {
      enabled                        = true
      start_time                     = "03:00"
      point_in_time_recovery_enabled = var.environment == "prod"
      transaction_log_retention_days = 7
      backup_retention_settings {
        retained_backups = var.environment == "prod" ? 30 : 7
      }
    }

    ip_configuration {
      ipv4_enabled    = false
      private_network = google_compute_network.main.id
      require_ssl     = true
    }

    database_flags {
      name  = "log_checkpoints"
      value = "on"
    }
    database_flags {
      name  = "log_connections"
      value = "on"
    }
    database_flags {
      name  = "log_disconnections"
      value = "on"
    }

    maintenance_window {
      day          = 7  # Sunday
      hour         = 3
      update_track = "stable"
    }

    insights_config {
      query_insights_enabled  = true
      query_string_length     = 1024
      record_application_tags = true
      record_client_address   = true
    }
  }

  deletion_protection = var.environment == "prod"
}

resource "google_sql_database" "main" {
  name     = var.database_name
  instance = google_sql_database_instance.main.name
}

resource "google_sql_user" "app" {
  name     = "app"
  instance = google_sql_database_instance.main.name
  password = random_password.db.result
}

Cloud Storage

Secure Bucket

resource "google_storage_bucket" "data" {
  name          = "${var.project_id}-data"
  location      = var.region
  force_destroy = var.environment != "prod"

  uniform_bucket_level_access = true

  versioning {
    enabled = true
  }

  encryption {
    default_kms_key_name = google_kms_crypto_key.storage.id
  }

  lifecycle_rule {
    condition {
      age = 90
    }
    action {
      type          = "SetStorageClass"
      storage_class = "NEARLINE"
    }
  }

  lifecycle_rule {
    condition {
      age = 365
    }
    action {
      type          = "SetStorageClass"
      storage_class = "COLDLINE"
    }
  }

  lifecycle_rule {
    condition {
      num_newer_versions = 3
    }
    action {
      type = "Delete"
    }
  }

  cors {
    origin          = ["https://${var.domain}"]
    method          = ["GET", "PUT", "POST"]
    response_header = ["*"]
    max_age_seconds = 3600
  }

  labels = local.common_labels
}

# Prevent public access
resource "google_storage_bucket_iam_binding" "prevent_public" {
  bucket = google_storage_bucket.data.name
  role   = "roles/storage.objectViewer"
  members = [
    "serviceAccount:${google_service_account.app.email}",
  ]
}

Cost Optimization

Committed Use Discounts

Commitment	Discount
1-year CUD	37%
3-year CUD	55%
Spot VMs	60-91%

Budget Alerts

resource "google_billing_budget" "main" {
  billing_account = var.billing_account_id
  display_name    = "${var.project_id} Budget"

  budget_filter {
    projects = ["projects/${var.project_id}"]
  }

  amount {
    specified_amount {
      currency_code = "USD"
      units         = var.monthly_budget
    }
  }

  threshold_rules {
    threshold_percent = 0.5
    spend_basis       = "CURRENT_SPEND"
  }

  threshold_rules {
    threshold_percent = 0.8
    spend_basis       = "CURRENT_SPEND"
  }

  threshold_rules {
    threshold_percent = 1.0
    spend_basis       = "FORECASTED_SPEND"
  }

  all_updates_rule {
    pubsub_topic = google_pubsub_topic.budget_alerts.id
  }
}

CLI Reference

# Auth
gcloud auth login
gcloud auth application-default login
gcloud config set project PROJECT_ID

# Compute
gcloud compute instances list
gcloud compute instances start INSTANCE
gcloud compute ssh INSTANCE --zone ZONE

# GKE
gcloud container clusters get-credentials CLUSTER --region REGION
gcloud container clusters list

# Cloud Run
gcloud run services list
gcloud run deploy SERVICE --image IMAGE --region REGION
gcloud run services update-traffic SERVICE --to-latest

# Cloud SQL
gcloud sql instances list
gcloud sql connect INSTANCE --user USER

# Storage
gsutil ls gs://BUCKET/
gsutil cp FILE gs://BUCKET/
gsutil rsync -r ./folder gs://BUCKET/folder

# Secrets
gcloud secrets list
gcloud secrets versions access latest --secret SECRET_NAME

# Logs
gcloud logging read "resource.type=cloud_run_revision" --limit 100

Security Checklist

• VPC Service Controls enabled
• Private Google Access enabled
• Cloud NAT for outbound traffic
• Workload Identity for GKE
• Binary Authorization enabled
• Cloud Armor for DDoS protection
• Secret Manager for credentials
• Cloud Audit Logs enabled
• Security Command Center enabled

Integration

Works with:

• /terraform - GCP provider configuration
• /k8s - GKE deployments
• /devops - GCP deployment pipelines
• /security - GCP security review