50 lines
3.4 KiB
Markdown
50 lines
3.4 KiB
Markdown
# Google Cloud solution architecture guide
|
|
|
|
## Scope and status
|
|
This guide packages manifest steps 0 through 7 for `gcp_solution_architecture_agent`, derived from the workflow-agent template. It is a reference baseline because no application-specific workflow request was supplied. Product selection was deferred during discovery and then made explicitly from the documented assumptions.
|
|
|
|
## Requirements
|
|
See [`docs/requirements.md`](docs/requirements.md). It contains functional requirements, non-functional requirements, constraints, assumptions, and open questions. The principal unresolved items are identity, scale/SLOs, data model, edge exposure, compliance, DR, and delivery governance.
|
|
|
|
## Selected products
|
|
Cloud Run, Pub/Sub, Cloud Storage, Firestore, VPC, Serverless VPC Access, Cloud Logging, Cloud Monitoring, Artifact Registry, IAM, and Service Usage.
|
|
|
|
## Architecture
|
|
```mermaid
|
|
flowchart LR
|
|
C[External clients] -->|HTTPS| R[Cloud Run service]
|
|
R --> F[(Firestore)]
|
|
R --> S[(Cloud Storage)]
|
|
R --> P[Pub/Sub topic]
|
|
P --> W[Worker subscriber]
|
|
P --> DLQ[Dead-letter topic]
|
|
R --> L[Cloud Logging]
|
|
R --> M[Cloud Monitoring]
|
|
AR[Artifact Registry] --> R
|
|
R -. private egress .-> VPC[VPC / Serverless VPC Access]
|
|
```
|
|
|
|
Clients use the HTTPS service. The service persists structured state and objects, emits events, and relies on a separate idempotent worker for asynchronous processing. The runtime has a dedicated identity, controlled egress, and managed encryption defaults. Public invocation is a deliberate baseline pending the ingress and identity answers in the open questions.
|
|
|
|
## Infrastructure as code
|
|
The deployable Terraform root is in [`terraform/`](terraform/). It enables APIs, creates a custom VPC/subnet and serverless connector, runtime service account, uniformly private object bucket, Firestore database, event/dead-letter topics, Artifact Registry repository, and Cloud Run service. Variables keep project, region, image, and labels configurable. No credentials or backend state are committed.
|
|
|
|
Apply only after review:
|
|
```bash
|
|
terraform -chdir=terraform init
|
|
terraform -chdir=terraform plan -var='project_id=PROJECT_ID' -var='container_image=IMAGE_URI'
|
|
terraform -chdir=terraform apply
|
|
```
|
|
|
|
## Validation
|
|
See [`validation-results.md`](validation-results.md). The repository supplies formatting, initialization without a backend, Terraform validation, an opt-in refresh-free plan, and Python artifact tests. Resource deployment is not part of validation. In this generation environment, these commands are **not_run** because required executables, provider downloads, and credentials are unavailable; CI must run them and record the results.
|
|
|
|
## Repository verification
|
|
- Step 4 guide persistence: represented by this non-empty file at the required path.
|
|
- Step 5 template/workflow conformance: represented by `workflow.yaml`, four phase entries, Terraform, diagram, requirements, and validation artifacts.
|
|
- Step 6 publication: performed by the repository generation commit.
|
|
- Step 7 remote verification: must compare the published revision with this file and `workflow.yaml` in the source-control system.
|
|
|
|
## Risks and follow-up
|
|
Confirm the open questions before production. Add Secret Manager, stronger ingress/edge controls, CMEK, backups, alert policies, quota budgets, dead-letter IAM, and multi-region recovery where required. The Cloud Run public invoker and one-year bucket deletion rule are baseline choices, not universal policy.
|