gcp_solution_architecture_agent/solution-architecture-guide.md

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

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.