# Google Cloud Solution Architecture Guide

## Scope and product-neutral requirements

The design preserves the confirmed requirements before product selection: accept authenticated requests, route peer traffic through a platform gateway/proxy, keep secrets out of source and state inputs, run workloads without root or propagated user credentials, and provide observable, least-privilege execution. Provisioning is opt-in and must never occur merely because validation or planning runs.

Functional requirements:
- Receive requests through a single platform gateway and proxy peer-to-peer traffic; peers are not directly exposed.
- Resolve runtime secrets by reference at execution time; no literal secret values are inputs, files, or environment literals.
- Execute workload processes as a non-root identity and do not forward cloud/user credentials.
- Provide authenticated access, logging, metrics, and bounded autoscaling.

Non-functional requirements:
- Least privilege, defense in depth, auditable access, and no credential propagation.
- Repeatable Terraform, reviewable plans, and safe default behavior.
- Availability and scaling suitable for a stateless regional service.

Constraints:
- Google Cloud is the target platform; no resources may be provisioned during validation.
- `provision=false` is the default and is an explicit request gate.
- Secret values must be supplied by Secret Manager, not Terraform variables or source control.

Assumptions:
- An existing secret is granted only to the workload service account.
- An external identity/IAP or equivalent authentication layer fronts the gateway in production.
- The supplied container image is built to run as a non-root user and implements proxy-only peer routing.

Open questions:
- Which identity provider and organizational ingress policy should be used in production?
- What exact SLO, retention, egress, and peer allow-list are required?

## Selected Google Cloud products

- Cloud Run for the stateless gateway workload.
- Secret Manager for referenced runtime secrets.
- IAM service account and narrowly scoped `roles/secretmanager.secretAccessor` binding.
- Cloud Run ingress restricted to the internal load balancer path; the gateway is the only peer route.
- Terraform Google provider for reproducible infrastructure.

## Architecture

```mermaid
flowchart LR
  Client[Authenticated client] --> LB[Platform gateway / proxy]
  LB --> Run[Cloud Run gateway workload\nnon-root, no propagated credentials]
  Run --> Peer[Peer services via gateway/proxy]
  Run -. secret reference only .-> SM[Secret Manager]
  IAM[IAM least-privilege service account] --> Run
```

The gateway is the sole peer traffic path. Cloud Run ingress is limited to the internal load-balancer route, and the application must use the proxy endpoint rather than direct peer addresses. The runtime service account has only Secret Manager accessor permission for the named secret; it receives no caller token or service-account key. The container image is expected to declare a non-root user (the Terraform contract cannot change an image's Dockerfile), and the application must strip credentials before proxying.

## Provisioning and IaC safety

Terraform is in `terraform/`. Every resource has `count = var.provision ? 1 : 0`; `provision` defaults to `false`, so `terraform plan` and validation are non-provisioning unless an operator explicitly passes `-var=provision=true`. `service_image` and `secret_id` are references, not secret contents. Never place a secret value in tfvars, logs, or CI variables. Apply is an explicit, separately authorized operation and is not part of CI.

## World-impacting capabilities and controls

The gateway is world-impacting because it can accept internet-originated callers when the platform load balancer/authentication policy permits it, invoke workloads, and proxy traffic to peers. The `allUsers` Cloud Run invoker binding is therefore only a platform ingress hook—not an authorization decision—and must be paired with the documented identity layer, rate limits, audit logging, and an allow-list before production exposure. CI never applies this configuration; reviewers must approve `provision=true` and the resulting plan.

## Verification evidence

Executed against the committed Terraform and workflow artifacts (no cloud resources were created):

- `terraform fmt -check -recursive terraform` — **PASS**
- `terraform init -backend=false` — **PASS**
- `terraform validate` — **PASS**
- `terraform plan -var='project_id=example-project' -var='service_image=us-docker.pkg.dev/example/app@sha256:0' -var='secret_id=runtime-config'` — **PASS; 0 resources planned because provision defaults to false**
- Static review — **PASS**: resource counts are gated, secret values are not literals, the only runtime IAM grant is Secret Manager accessor, and the architecture routes peer calls through the gateway.

## SCM workflow gates

`.github/workflows/ci.yml` runs on both `push` and `pull_request`. It installs pinned tool versions and gates changes with Terraform formatting/validation plus application lint, type-check, and tests. The workflow has no apply step and does not require or propagate cloud credentials.

## Terraform

See the executable files under `terraform/variables.tf`, `terraform/main.tf`, and `terraform/outputs.tf`. The guide intentionally does not duplicate a second copy of the IaC, avoiding drift.