decomposer: generate deliverable files for Discover and structure the solution's functional requirements, non-functional requirements, constraints, assumptions, and open questions without selecting cloud products.; Select Google Cloud products from the confirmed requirements and produce the solution architecture, Mermaid diagram, architecture description, and Terraform infrastructure-as-code.; Validate the Terraform infrastructure and architecture artifacts without deploying resources by running formatting checks, Terraform validation, and a dry-run or plan-oriented deployment check.; Package the approved requirements, architecture, Mermaid diagram, Terraform IaC, and validation results into solution-architecture-guide.md in the gcp_solution_architecture_agent repository.; Verify that the gcp_solution_architecture_agent repository contains the packaged solution-architecture-guide.md with the approved workflow outputs.; Verify that the repository is derived from the workflow_agent template and implements the complete four-phase Google Cloud solution architecture workflow alongside the packaged guide.; Publish the verified gcp_solution_architecture_agent repository with its completed workflow implementation and solution architecture guide.; Verify that the published repository revision contains the completed workflow implementation and solution architecture guide.
This commit is contained in:
@@ -1,95 +1,79 @@
|
||||
# Google Cloud Solution Architecture Guide
|
||||
|
||||
## Delivery status
|
||||
Repository: `gcp_solution_architecture_agent`
|
||||
Template: `https://github.com/example/workflow_agent`
|
||||
Workflow status: requirements → architecture → validation → packaging → repository verification → publication verification
|
||||
|
||||
This guide packages the approved discovery record, product architecture, diagram, Terraform, and pre-deployment validation procedure for `gcp_solution_architecture_agent`. It is a plan-only deliverable; it does not provision Google Cloud resources.
|
||||
|
||||
## 1. Requirements discovery (product selection deferred)
|
||||
## 1. Approved requirements (Step 0)
|
||||
|
||||
### Functional requirements
|
||||
|
||||
- Accept authenticated HTTPS event requests.
|
||||
- Validate, durably enqueue, and asynchronously process events.
|
||||
- Persist raw events for replay and audit.
|
||||
- Expose health and structured logs.
|
||||
- Support environment-specific configuration.
|
||||
- Accept authenticated HTTPS order submissions.
|
||||
- Validate payloads and synchronously acknowledge accepted requests.
|
||||
- Process accepted orders asynchronously.
|
||||
- Persist durable order state with transactional updates.
|
||||
- Keep secrets out of source code.
|
||||
- Emit logs, metrics, traces, and audit evidence.
|
||||
- Deploy repeatably from version-controlled Terraform.
|
||||
- Support rollback and dead-letter replay.
|
||||
|
||||
### Non-functional requirements
|
||||
|
||||
- At-least-once delivery with idempotent consumers.
|
||||
- Regional high availability and independent scaling.
|
||||
- 99.9% monthly endpoint availability target.
|
||||
- p95 acknowledgement latency below 500 ms at baseline load.
|
||||
- Encryption in transit and at rest.
|
||||
- 30-day configurable audit retention.
|
||||
- Least privilege and observable failures.
|
||||
- Horizontal scaling and burst isolation.
|
||||
- Least-privilege identities and private data access where practical.
|
||||
- At least 90 days of operational/audit retention, subject to policy.
|
||||
- Reproducible, reviewable, non-destructive-by-default deployment.
|
||||
|
||||
### Constraints and assumptions
|
||||
### Constraints, assumptions, and open questions
|
||||
|
||||
The deployment targets an existing project, uses Terraform without apply, and receives its container image from external CI/CD. The workload is initially regional; the worker tolerates duplicates; product selection was deferred during discovery.
|
||||
The complete approved lists are maintained in [`requirements-spec.md`](requirements-spec.md). Product selection was deferred in Step 0 and only occurs in the next section.
|
||||
|
||||
### Open questions
|
||||
## 2. Selected architecture (Step 1)
|
||||
|
||||
Peak throughput and payload size, region/compliance and key policy, downstream destinations, and SLO/on-call thresholds remain to be confirmed before production hardening.
|
||||
|
||||
## 2. Selected Google Cloud products
|
||||
|
||||
- **Cloud Run**: authenticated HTTPS ingress and independently scalable worker runtime.
|
||||
- **Pub/Sub**: durable asynchronous event transport and retry policy.
|
||||
- **Cloud Storage**: retained raw-event replay and audit store.
|
||||
- **Artifact Registry**: controlled container image repository.
|
||||
- **Cloud Logging and Cloud Monitoring APIs**: operational telemetry foundation.
|
||||
- **IAM/service accounts**: workload identity and least-privilege boundary.
|
||||
|
||||
## 3. Architecture diagram
|
||||
Products: Cloud Run, Pub/Sub, Cloud SQL for PostgreSQL, Secret Manager, Artifact Registry, Serverless VPC Access, VPC, IAM, Cloud Logging, Cloud Monitoring, and Cloud Trace.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client[Authenticated producer] --> API[Cloud Run ingress]
|
||||
API --> Topic[Pub/Sub topic]
|
||||
Topic --> Sub[Pub/Sub subscription]
|
||||
Sub --> Worker[Cloud Run worker]
|
||||
API --> Raw[(Cloud Storage raw-event bucket)]
|
||||
Worker --> Raw
|
||||
Worker --> Downstream[External downstream systems]
|
||||
API --> Logs[Cloud Logging]
|
||||
Worker --> Logs
|
||||
Logs --> Monitor[Cloud Monitoring]
|
||||
API -. IAM .-> Identity[Dedicated runtime service account]
|
||||
Worker -. IAM .-> Identity
|
||||
Client[Authenticated client] --> API[Cloud Run order-api]
|
||||
API --> Topic[Pub/Sub orders]
|
||||
Topic --> Worker[Cloud Run order-worker]
|
||||
Topic --> DLQ[Pub/Sub dead-letter]
|
||||
API --> DB[(Cloud SQL PostgreSQL)]
|
||||
Worker --> DB
|
||||
API -.-> Secrets[Secret Manager]
|
||||
Worker -.-> Secrets
|
||||
API --> Telemetry[Logging / Monitoring / Trace]
|
||||
Worker --> Telemetry
|
||||
CI[CI fmt validate plan] --> Terraform[Terraform]
|
||||
Terraform --> API
|
||||
```
|
||||
|
||||
## 4. Architecture description
|
||||
The API validates and idempotently records orders before publishing events. Pub/Sub absorbs bursts and isolates worker failures. The worker updates order state and failed deliveries go to the dead-letter topic. Cloud Run supplies stateless scaling; Cloud SQL supplies transactions; Secret Manager handles sensitive configuration; VPC connectivity supports controlled database access. The topology is initially single-region. Authentication integration, custom edge policy, multi-region DR, and exact retention require answers to the open questions.
|
||||
|
||||
The ingress service validates a request, writes the original event to the retained bucket, and publishes an envelope. The worker acknowledges only after downstream processing succeeds. Event IDs are idempotency keys, so redelivery is safe. Cloud Run removes server management, Pub/Sub absorbs bursts, and Cloud Storage supplies replay. The Terraform creates APIs, identities, storage, messaging, an image repository, and a placeholder ingress service. Application behavior and image construction remain outside scope.
|
||||
## 3. Terraform IaC (Step 1)
|
||||
|
||||
## 5. Infrastructure as code
|
||||
The deployable IaC is in [`terraform/`](terraform/). It enables required APIs, creates the network connector, PostgreSQL instance/database/user, Pub/Sub topics and subscription, runtime identity, secret, and two Cloud Run services. Supply a project ID and sensitive database password through a tfvars file or CI secret. Placeholder images must be replaced by application images.
|
||||
|
||||
The complete deployable Terraform is in `terraform/`:
|
||||
Important production hardening: use separate API/worker service accounts, set deletion protection, use customer-managed encryption if required, configure database private services access and backup/PITR policy, restrict ingress/authentication, add monitoring alerts, and manage secret values outside Terraform state.
|
||||
|
||||
- `main.tf` pins Google provider 6.x and creates the foundational resources.
|
||||
- `variables.tf` makes project, region, environment, image, identity, retention, and scaling explicit.
|
||||
- `outputs.tf` publishes the endpoint, bucket, and topic.
|
||||
- `terraform.tfvars.example` documents required inputs.
|
||||
## 4. Validation results (Step 2)
|
||||
|
||||
Apply is intentionally not part of this repository's workflow.
|
||||
- Terraform formatting: **defined and CI-enforced; execution must occur in CI or a Terraform-enabled review environment**.
|
||||
- Terraform validation: **defined via backendless `terraform init` and `terraform validate`; no resources are provisioned**.
|
||||
- Dry-run/plan check: **defined as an optional credentialed `terraform plan -out=tfplan`; no apply is included**.
|
||||
- Artifact structure test: **implemented in `scripts/validate_artifacts.py` and `tests/test_artifacts.py`**.
|
||||
|
||||
## 6. Validation and findings
|
||||
Because this generation environment provides no shell or Terraform runtime, command execution evidence cannot be honestly asserted here. The repository contains the exact checks and CI workflow needed to produce it before deployment. This is a validation limitation, not a deployment approval.
|
||||
|
||||
The repository provides `scripts/validate.sh`, which runs:
|
||||
## 5. Repository delivery and verification (Steps 3–7)
|
||||
|
||||
1. `terraform fmt -check -diff`
|
||||
2. `terraform init -backend=false -input=false`
|
||||
3. `terraform validate`
|
||||
4. `terraform plan -refresh=false -input=false -lock=false` when required variables are supplied
|
||||
Step 3 packages this guide with the approved requirements, architecture, Mermaid diagram, Terraform, and validation design. Step 4 requires this file at `solution-architecture-guide.md`. Step 5 checks template metadata, four-phase README coverage, and required artifacts. Step 6 publishes one committed repository revision. Step 7 compares the remote revision with that verified revision.
|
||||
|
||||
The plan is saved only to `/tmp` and no resources are applied. The checked-in validation record marks execution as pending because this packaging environment does not claim access to Terraform or a Google Cloud project. Run the script in CI with Terraform 1.6.x, a pinned provider lock file generated by CI, and non-production plan credentials.
|
||||
Repository verification status at generation: **artifact presence and workflow coverage are implemented; remote/template inspection requires the source-control integration to execute**. Publication status: **not claimable from this tool-only generation environment**.
|
||||
|
||||
## 7. Verification record
|
||||
## 6. Operations and acceptance criteria
|
||||
|
||||
- Guide persisted at `solution-architecture-guide.md`: yes.
|
||||
- Template/workflow configuration: `workflow.yaml` declares all four phases and the source template.
|
||||
- Required artifacts: requirements, architecture description, Mermaid diagram, Terraform, validation procedure, and this guide are present.
|
||||
- Publication: repository publication is performed by the repository automation after review.
|
||||
|
||||
## 8. Production follow-up
|
||||
|
||||
Resolve the open questions, add explicit Pub/Sub-to-worker subscription IAM and dead-letter policy, decide whether customer-managed keys and private networking are mandatory, add SLO-based alert policies, and perform a security review before production use.
|
||||
Accept when requirements are approved, all open questions have owners, Terraform `fmt` and `validate` pass, a reviewed plan has no unintended changes, API authentication and alert policies are configured, and an operational restore/replay exercise succeeds. Never run `terraform apply` from the validation job.
|
||||
|
||||
Reference in New Issue
Block a user