API Gateway — Architecture Overview
Audience: Engineers integrating new APIs or debugging request flow through the gateway.
Scope: Full tunnel + gateway architecture — from Cloudflare edge to Cloud Run.
Architecture overview
Every external API request passes through four layers before reaching a Cloud Run service. No backend is reachable from the public internet directly.
User
│
▼
Cloudflare Worker (platform-api-gateway)
│ • CORS, header sanitization, rate limiting
│ • Adds X-Internal-Auth-Token header
│
▼
Cloudflare Tunnel (iac-api-gateway / tunnel.tf)
│ • eigenoid-gateway-{env}
│ • Maps internal hostnames → localhost:8080 on the VM
│
▼
Gateway VM — cf-proxy :8080 (iac-api-gateway / vm.tf, cf_proxy.py)
│ • Validates X-Internal-Auth-Token
│ • Routes Host → Cloud Run URL via routes.json
│ • Injects GCP identity token (Bearer) for Cloud Run auth
│
▼
Cloud Run service (iac-access, svc-access / svc-access-public)
Full topology (mermaid)
Section guide
| Page | What's covered |
|---|---|
| Cloudflare Workers | Edge Workers: header stripping, token injection, CORS, wrangler config |
| Cloudflare Tunnel | Tunnel configuration, ingress rules, DNS records |
| Gateway VM | cf-proxy routing logic, cloudflared daemon, MIG configuration |
| Cloud Run Services | Backend services, IAM requirements for invoker access |
| Authentication | Two-layer auth flow: shared secret + GCP identity token |
| Secret Distribution | How INTERNAL_AUTH_TOKEN is provisioned to CF Secrets Store and GCP SM |
| Networking | Firewall rules, subnet, Cloud NAT, Private Google Access |
| Adding a New API | Step-by-step guide and checklist for onboarding a new service |
| Repository Map | Which repos own which gateway components |
| Operations | Debugging, VM replacement, environment promotion |
Related documentation
- ADR-0014 — CF Workers as API Gateway — decision record and alternatives considered
- IaC — Producer/consumer model — how Terraflow applies changes