78 lines
5.3 KiB
Markdown
78 lines
5.3 KiB
Markdown
# 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.
|