GCP Deployment

1. Overview

All gateway components are deployed on Google Cloud Platform (GCP). This document covers the deployment topology, resource sizing, domain configuration, and operational procedures.

2. GCP Projects

Project	Purpose	Environment
`peakgateway-staging`	Development and staging	Staging
`pinpoint-gateway`	Production workloads and shared Artifact Registry	Production

Both projects are in the same GCP organization and use the same unsuffixed Cloud Run service names. Always supply --project on operational commands.

3. Deployment Topology

                    Internet
                       │
               ┌───────┴────────┐
               │  Cloud DNS     │
               │  *.peakgateway.co  │
               └───────┬────────┘
                       │
               ┌───────┴────────┐
               │  Cloud Load    │
               │  Balancer      │
               │  (Global L7)   │
               │  + Cloud Armor │
               └───────┬────────┘
                       │
           ┌────────────┼────────────┐
           │            │            │
    ┌──────┴─────┐ ┌────┴────┐ ┌─────┴─────┐
    │ api.peakgateway.co │ │ pay.peakgateway.co │ │ internal-only │
    └──────┬─────┘ └────┬────┘ └─────┬─────┘
           │            │            │
    ┌──────┴────────────┴────────────┴──────┐
    │          VPC (10.0.0.0/24)            │
    │                                       │
    │  ┌───────────────────────────────┐    │
    │  │       Private services        │    │
    │  │                               │    │
    │  │  Cloud Spanner (CMEK)         │    │
    │  │  Cloud Pub/Sub                │    │
    │  │  Secret Manager               │    │
    │  │  Identity Platform            │    │
    │  └───────────────────────────────┘    │
    └───────────────────────────────────────┘

4. Resource Sizing

Cloud Run Services

All eight services use 1 CPU and 2 GiB memory by default. Terraform applies the following source-controlled scaling defaults; Terrakube workspace variables can override them.

Service	Warm in staging	Warm in production	Max instances
auth	yes	yes	30
management	no	yes	30
online-txn	no	yes	30
processing	no	yes	20
card-present	no	no	20
merchant-onboarding	no	yes	10
status	no	no	10
mcp	no	no	10 (global fallback)

Warm services keep one minimum instance; request-based services scale from zero. Verify active Cloud Run settings before capacity or incident decisions.

Cloud Spanner

Property	Staging	Production
Instance Config	`regional-us-east1`	`regional-us-east1`
Dialect	PostgreSQL	PostgreSQL
Multi-regional	No	No (single-region HA)
Encryption	CMEK	CMEK

Processing units, autoscaling bounds, and backup retention are workspace configuration. Read the active Spanner instance and Terrakube variables rather than relying on static sizing numbers.

5. Domain & DNS Configuration

Domain	Points To	Purpose
`api.peakgateway.co`	Global external Application Load Balancer	Auth, management, status, MCP
`pay.peakgateway.co`	Global external Application Load Balancer	Online transaction and card-present APIs

Cloud Load Balancer URL Map (`api.peakgateway.co`)

Root /.well-known/* and /oauth2/* routes -> gateway-auth
/auth/* -> gateway-auth (prefix removed)
/management/* -> gateway-management (prefix removed)
/status/* -> gateway-status (prefix removed)
/mcp and /mcp/* -> gateway-mcp
default -> gateway-management

Cloud Load Balancer URL Map (`pay.peakgateway.co`)

/online-txn/* -> gateway-online-txn (prefix removed)
/card-present/* -> gateway-card-present (prefix removed)
default -> gateway-online-txn

NOTE: The gateway-processing and gateway-merchant-onboarding services have no external routes. They are reachable only through authenticated service-to-service calls. See Ops > Internal-Only Services for the verification checklist.

6. Cloud Armor WAF Rules

Cloud Armor is configured with the following rules:

Priority	Rule	Action	Description
850	request path contains `internal`	Deny (403)	Block public access to internal service routes
900	`cve-canary`	Deny (403)	Block CVE canary patterns
1000	`sqli-v33-stable`	Deny (403)	Block SQL injection attacks
1001	`xss-v33-stable`	Deny (403)	Block cross-site scripting attacks
1002	`lfi-v33-stable`	Deny (403)	Block local file inclusion attacks
1003	`rce-v33-stable`	Deny (403)	Block remote code execution attacks
2000	source-IP rate limit	Throttle	Coarse emergency limit, default 10,000 requests/minute
2147483647	Default	Allow	Default allow all

7. TLS Certificates

TLS uses Certificate Manager DNS authorizations, managed certificates, and a certificate map attached to the global HTTPS proxy:

resource "google_certificate_manager_certificate" "gateway_api" {
  name = "gateway-api-cert"
  managed {
    domains            = [var.gateway_domain]
    dns_authorizations = [google_certificate_manager_dns_authorization.gateway_api.id]
  }
}

resource "google_certificate_manager_certificate" "payment_api" {
  name = "payment-api-cert"
  managed {
    domains            = [var.pay_domain]
    dns_authorizations = [google_certificate_manager_dns_authorization.payment_api.id]
  }
}

8. Monitoring & Alerts

Uptime Checks

No Cloud Monitoring uptime checks are currently provisioned by Terraform. Service availability is measured by the per-service Cloud Monitoring SLOs.

Alert Policies

Alert	Condition	Notification
Per-service SLO fast burn	Burn rate > 10× over 5 minutes	Slack (`#gateway-alerts`) + managed email fallback
Per-service SLO slow burn	Burn rate > 2× over 1 hour	Slack (`#gateway-alerts`) + managed email fallback
Pub/Sub DLQ has messages	Configured DLQ depth > 0 for 5 minutes	Slack (`#gateway-alerts`) + managed email fallback
Webhook DLQ depth	`webhook_dlq_depth` > 0 for any organization for 15 minutes	Slack (`#gateway-alerts`) + managed email fallback
Per-service SLO error budget low	Less than 10% remaining for 15 minutes	Cloud Monitoring only unless `slo_budget_alert_channels` is configured

These notifications do not trigger automated paging, acknowledgement, or escalation. Operators coordinate the response manually in Slack.

9. Operational Procedures

Deploy New Version

Merge PR to main
CI builds and tests
Staging auto-deploys via GitHub Actions
Verify staging health checks
Trigger production deploy via GitHub Actions workflow dispatch
Monitor production health post-deploy

Rollback

# List revisions
gcloud run revisions list --service gateway-processing --region us-east1 --project pinpoint-gateway

# Route traffic back to a known-good revision
gcloud run services update-traffic gateway-processing \
  --to-revisions=gateway-processing-PREVIOUS_REVISION=100 \
  --region us-east1 \
  --project pinpoint-gateway

Database Migration

Schema changes are published as bounded, immutable, forward-only revisions under db/schema-revisions/
Staging applies and verifies the revision before production
Each DDL operation must reach terminal success before the schema lease is released
Migrations must be resumable because earlier statements in a failed Spanner DDL batch remain committed

10. Cost and Capacity

Static monthly estimates age quickly and are not an operational source of truth. Use Cloud Billing reports for actual spend, Cloud Run revision settings for active capacity, and the target Terrakube workspace for intended scaling and Spanner configuration.

1. Overview​

2. GCP Projects​

3. Deployment Topology​

4. Resource Sizing​

Cloud Run Services​

Cloud Spanner​

5. Domain & DNS Configuration​

Cloud Load Balancer URL Map (api.peakgateway.co)​

Cloud Load Balancer URL Map (pay.peakgateway.co)​

6. Cloud Armor WAF Rules​

7. TLS Certificates​

8. Monitoring & Alerts​

Uptime Checks​

Alert Policies​

9. Operational Procedures​

Deploy New Version​

Rollback​

Database Migration​

10. Cost and Capacity​