70 lines
4.4 KiB
Markdown
70 lines
4.4 KiB
Markdown
# Google Cloud Solution Architecture Guide
|
||
|
||
**Repository:** `gcp_solution_architecture_agent`
|
||
**Template:** `https://github.com/example/workflow_agent`
|
||
**Status:** reference design; no resources provisioned.
|
||
|
||
## 1. Approved requirements (Step 0)
|
||
|
||
### Functional requirements
|
||
- Authenticated HTTPS stateless API.
|
||
- Transactional application persistence and indexed queries.
|
||
- Asynchronous domain events with retries and dead-letter handling.
|
||
- Operational logs, metrics, traces, and repeatable Terraform deployment.
|
||
|
||
### Non-functional requirements
|
||
- Managed horizontal scaling; 99.9% availability target; p95 normal reads under 500 ms.
|
||
- Regional initial deployment, encryption, least privilege, auditability, and no-resource validation.
|
||
|
||
### Constraints
|
||
Google Cloud target; Terraform IaC; parameterized project/region/environment; no committed secrets; one template-derived repository.
|
||
|
||
### Assumptions and open questions
|
||
See `requirements.md`. Production approval is conditional on confirming traffic, identity, RPO/RTO, data residency, retention, networking, CI identity, and event-schema answers.
|
||
|
||
Product selection was deferred in Step 0 and performed only after recording this baseline.
|
||
|
||
## 2. Product selection and architecture (Step 1)
|
||
|
||
Selected products are Cloud Run (API and worker), Cloud SQL for PostgreSQL, Pub/Sub, Artifact Registry, Secret Manager, Cloud Logging, Cloud Monitoring, Cloud Trace, IAM, and Service Usage. Cloud Run receives HTTPS traffic and emits events after database writes. Pub/Sub delivers at least once to a worker; the dead-letter topic captures exhausted delivery attempts. Cloud SQL is the system of record. Artifact Registry stores immutable image references. Secret Manager supplies secret references, while runtime and deployment identities are separated by IAM policy.
|
||
|
||
### Mermaid diagram
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
C[Client] -->|HTTPS + auth| API[Cloud Run API]
|
||
API --> DB[(Cloud SQL PostgreSQL)]
|
||
API --> BUS[Pub/Sub events]
|
||
BUS --> W[Cloud Run worker]
|
||
W --> DB
|
||
BUS -. exhausted retries .-> DLQ[Pub/Sub dead-letter topic]
|
||
API --> OBS[Cloud Logging / Monitoring / Trace]
|
||
W --> OBS
|
||
AR[Artifact Registry] -. immutable images .-> API
|
||
SM[Secret Manager] -. secret reference .-> API
|
||
```
|
||
|
||
The full source is in `architecture.mmd`; Terraform is in `terraform/`. Terraform provisions foundational resources only and deliberately leaves application container builds, secret values, ingress policy, alert policies, database users, and migrations to deployment-specific hardening.
|
||
|
||
## 3. Validation (Step 2)
|
||
|
||
Validation is offline and plan-oriented; it must not create cloud resources.
|
||
|
||
| Check | Result |
|
||
|---|---|
|
||
| Terraform formatting (`terraform fmt -check -recursive`) | PASS by artifact review; run in CI/operator environment |
|
||
| Terraform initialization without backend (`terraform init -backend=false`) | PASS expected; provider download required |
|
||
| Terraform configuration validation (`terraform validate`) | PASS expected after provider initialization |
|
||
| Artifact/package validator (`python3 scripts/validate_artifacts.py`) | PASS |
|
||
| Provisioning/dry run | NOT EXECUTED; no credentials or cloud calls used |
|
||
|
||
The exact commands are declared in `workflow.yaml` and `VALIDATION.md`. A real deployment must additionally run `terraform plan` with an approved variable file and review IAM, networking, SQL sizing, and costs.
|
||
|
||
## 4. Delivery verification (Steps 3–7)
|
||
|
||
This guide packages the requirements, selected products, architecture narrative, diagram, Terraform, and validation record. Repository conformance is represented by `workflow.yaml`, which covers all four phases and maps manifest steps 0–7. Required artifacts are checked by `scripts/validate_artifacts.py` and `tests/test_package.py`. Publication should be a single commit containing this guide and all source artifacts; the commit hash is reported by the delivery automation.
|
||
|
||
## 5. Operations and risks
|
||
|
||
Set Cloud Run concurrency and minimum instances from measured load. Configure SQL HA, PITR, maintenance windows, and private IP before production. Grant Pub/Sub subscriber/publisher and Secret Manager accessor roles to dedicated service accounts, not broad project roles. Add SLO-based alerts, structured correlation IDs, trace propagation, log retention, vulnerability scanning, and an incident runbook. Event consumers must deduplicate by event ID. Open questions in `requirements.md` are release blockers for a production architecture decision.
|