gcp_solution_architecture_agent/solution-architecture-guide.md

Google Cloud Solution Architecture Guide

Delivery status

This is the revised, operator-reviewable guide. It preserves the requirements, product architecture, Mermaid view, Terraform IaC, and pre-deployment validation artifacts. No infrastructure or workload is created by reading this guide or running terraform plan; creation requires an explicit opt-in.

Phase 0 — confirmed requirements (product selection deferred in this phase)

Functional requirements

• Accept application requests through a controlled gateway/proxy rather than exposing the workload directly.
• Route peer/service traffic through an authenticated, policy-enforcing gateway or proxy.
• Run the application as a Cloud Run workload and retrieve sensitive configuration from a managed secret reference.
• Provide repeatable infrastructure as code.
• Give operators an explicit, reviewable deployment/provisioning control.

Non-functional requirements

• Workload execution uses a dedicated, least-privilege service identity and a non-root container user.
• No end-user, operator, CI, or local credential is copied into a created workload.
• Secrets are referenced by name/version and never embedded as Terraform literals, environment values, or source code.
• Direct public access to the workload is denied; gateway/proxy policy is the traffic boundary.
• Changes are planable, auditable, and safe to validate without provisioning.

Constraints

• Google Cloud and Terraform are the target platform/tooling.
• This deliverable must not provision resources during validation.
• The runtime image must be pinned by digest and must be built with a non-root USER.

Assumptions

• A pre-existing Secret Manager secret is supplied by name; its value is populated out of band by an authorized operator.
• The selected runtime image already contains the application and listens on the Cloud Run port.
• A gateway/proxy is the only supported client path to the service.

Open questions

• Which organization-specific API Gateway authentication policy and allowed peer identities should be added before production?
• Which pre-existing secret name and runtime image digest will be supplied for the target environment?
• What gateway hostname, certificate, and DNS ownership are required?

Phase 1 — selected architecture and IaC

Selected Google Cloud products

• Cloud Run (managed workload), with internal-and-cloud-load-balancing ingress.
• API Gateway (authenticated gateway/proxy boundary).
• Secret Manager (secret reference only).
• Artifact Registry (pinned container image source).
• Dedicated user-managed service account with narrowly scoped runtime access.
• Serverless VPC Access connector (optional private egress path for peer dependencies).
• Terraform Google provider.

Architecture diagram

flowchart LR
  C[Approved client/peer] -->|TLS + gateway auth| G[API Gateway\npolicy + proxy]
  G -->|authenticated HTTPS| R[Cloud Run\ningress: internal + LB only\nnon-root image]
  R -->|secret reference, runtime identity| S[Secret Manager]
  R -. optional private peer egress .-> V[Serverless VPC Access]
  V -.-> P[Private peer service]
  I[Artifact Registry\npinned digest] --> R
  O[Operator] -->|set deploy_enabled=true\nwith approved vars| T[Terraform plan/apply]
  T --> G
  T --> R

Traffic, identity, and credential rules

1. API Gateway is the public/client-facing proxy. Its OpenAPI backend points at the Cloud Run URL and requires the gateway service account to invoke the service. Direct Cloud Run ingress is restricted to internal and Google Cloud load-balancing paths; clients do not receive a direct workload endpoint as an approved route.
2. Peer-to-peer calls use the gateway/proxy route (or the explicitly documented private VPC egress path), never an ad-hoc public workload URL. Authorization and audit policy belong at the gateway and workload identity boundary.
3. Cloud Run uses a dedicated service account with only roles/secretmanager.secretAccessor on the named secret. Terraform's caller identity is not passed into the service, and no access token, key, refresh token, or local credential is placed in environment variables, files, metadata, or secrets.
4. The image reference is digest-pinned. The image build contract must contain USER 65532:65532 (or another non-root numeric UID); the application therefore executes as non-root with no root privilege. The Terraform input validation rejects mutable tags.
5. secret_data is intentionally absent. secret_id and secret_version are references; the secret value is created/populated separately by an authorized secret-management process.

Explicit provisioning gate and operator disclosure

All managed resources have count = var.deploy_enabled ? 1 : 0; the default is false. terraform validate and terraform plan with the default do not create infrastructure or workloads. An operator must deliberately set deploy_enabled=true, review the plan, authenticate with the approved deployment identity, and run terraform apply. Terraform prints a warning naming the resources that will be created when the gate is enabled. The operator is responsible for disclosing that apply creates gateway configuration, service identity/bindings, network connector, and Cloud Run infrastructure/workload.

Terraform IaC

The authoritative Terraform source is terraform/main.tf. It implements the gate, least-privilege identity, secret reference, gateway policy, restricted Cloud Run ingress, and digest pinning. It deliberately does not create a secret value or propagate credentials.

Phase 2 — validation without deployment

Validation commands:

terraform -chdir=terraform fmt -check -diff
terraform -chdir=terraform init -backend=false
terraform -chdir=terraform validate
terraform -chdir=terraform plan -refresh=false -input=false -var='deploy_enabled=false'

The plan-oriented check is intentionally performed with the default gate disabled. It must show no resource creation. A production plan/apply is a separately approved operator action, not an incidental validation side effect.

Validation evidence recorded for this revision:

• Terraform formatting: valid by source formatting review; run terraform fmt -check -diff in CI.
• Terraform configuration: validation command specified; requires the pinned Google provider and project credentials only for provider schema discovery, not workload credential propagation.
• Dry run: gate-off plan is the required no-provisioning check.
• Security review: gateway/proxy path, non-root image contract, secret references, no credential propagation, and explicit operator gate are documented and represented in IaC.

Phase 3 — packaging and publication

This guide is the packaged architecture artifact. The repository also retains the workflow configuration, Terraform source, Mermaid architecture, and validation/publication records from the other phases. Reviewers should inspect the commit, run the commands above, and treat a gate-on apply as a separately disclosed change that creates infrastructure and the Cloud Run workload.

Operator runbook

1. Supply a digest-pinned image and an existing secret ID/version; do not put secret values in .tfvars or command history.
2. Authenticate Terraform using the approved deployment mechanism (for example, short-lived CI identity); never add that credential to Cloud Run.
3. Run the gate-off validation commands.
4. Set deploy_enabled=true only after reviewing the plan and obtaining change approval.
5. Disclose to operators and stakeholders that apply creates/updates the gateway, IAM bindings, network connector, and workload infrastructure.
6. Verify gateway authentication and Cloud Run audit logs before admitting peer traffic.