feat: load the env file at start-up, trim schema lookups, remove legacy samples

Start-up
- Export the env file's variables for other libraries (the Cloud provider's
  client) into the process environment; the app's own settings and secrets
  are never exported, and a value already in the environment wins.
- Use GOOGLE_GENAI_USE_ENTERPRISE in place of the deprecated
  GOOGLE_GENAI_USE_VERTEXAI.

Target architect
- Look each distinct resource type up once instead of once per setting: in
  the run of 2026-10-07 it made 39 lookups for 8 types and exhausted its
  budget. terraform_schema's find takes several names; budget 30 to 45.
- A cut-off schema outline says so.

Removed, as leftovers of the original pipeline that nothing read
- terraform/ (no longer passed terraform validate), scripts/validate.sh,
  tests/test_package.py and the CI steps that ran on them.
- The sample outputs under docs/ and requirements.yaml.
- CI now pins Terraform 1.14.3, as the container image does.

Plans record the case 01 run: completed at 100% in 18 minutes with no
Revision, against 60 minutes and warnings before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-07 20:06:58 +01:00
parent 5bb22d984e
commit f1f6f1b83a
34 changed files with 161 additions and 402 deletions

View File

@@ -1,21 +0,0 @@
# Phase 1 — Architecture & Product Selection
## Selected Products
- **Compute / Serving**: Google Cloud Run (Fully Managed Container Ingress & Stateless Execution)
- **Messaging & Eventing**: Google Cloud Pub/Sub (Regional Event Bus for Asynchronous Decoupling)
- **State & Storage**: Google Cloud Storage & Firestore (Database & Bucket Storage for Durable Audit Event Replay)
- **Security & Identity**: Cloud IAM (Least Privilege Service Accounts) & KMS (Customer-Managed Encryption Keys)
- **Artifact Registry**: Google Artifact Registry (OCI Container Image Hosting)
## Component Responsibilities
1. **Cloud Run Service**: Accepts HTTPS requests, validates client signatures, enqueues events to Pub/Sub, returns 202 Accepted.
2. **Pub/Sub Topic & Subscription**: Buffer incoming payloads, deliver events asynchronously with exponential backoff retries to consumer handlers.
3. **Audit Bucket (GCS)**: Raw event retention for replay, payload audit, and operational troubleshooting.
## Security & Compliance
- HTTPS ingress with TLS 1.3 encryption in transit.
- Default Google-managed encryption at rest for Cloud Storage and Pub/Sub.
- Cloud Run service account bound strictly to `roles/pubsub.publisher` and `roles/storage.objectCreator`.
## Grounded Documentation Citations (Google Developer Knowledge MCP)
- [Google Cloud Run Architecture Guide](https://cloud.google.com/run/docs/overview/what-is-cloud-run)

View File

@@ -1,7 +0,0 @@
# Publication verification
This repository was republished to the configured remote as part of the step 6 publication retry.
- Remote: `https://gitea.kyndemo.live/agents/gcp_solution_architecture_agent`
- Purpose: establish a concrete publication commit for the already-verified workflow deliverable.
- Scope: this audit note only; all previously delivered architecture, guide, Terraform, validation, template, phase, and compliance artifacts are preserved unchanged.

View File

@@ -1,57 +0,0 @@
# Step 0 — approved requirements specification
## Workflow request
Produce a reviewable, deployable Google Cloud reference architecture for an event-driven order-ingestion service, while separating product-neutral discovery from product selection and validating IaC without provisioning.
## Functional requirements
- Accept authenticated order submissions over HTTPS.
- Validate order payloads and return a synchronous acknowledgement.
- Process accepted orders asynchronously so ingestion is not coupled to downstream latency.
- Persist durable order state and support transactional updates.
- Store credentials and other sensitive configuration outside source code.
- Provide application logs, metrics, traces, and auditable administrative activity.
- Support repeatable infrastructure deployment from version-controlled IaC.
- Provide a documented rollback and dead-letter/replay approach.
## Non-functional requirements
- Target 99.9% monthly availability for the public ingestion endpoint.
- Target p95 acknowledgement latency below 500 ms under the expected baseline load.
- Provide encryption in transit and at rest.
- Scale horizontally for bursty traffic and isolate asynchronous work from ingestion.
- Apply least-privilege identities and private access to data services where practical.
- Retain operational and audit evidence for at least 90 days, subject to organizational policy.
- Ensure deployments are reproducible, reviewable, and non-destructive by default.
## Constraints
- The target platform is Google Cloud.
- Terraform is the infrastructure-as-code language.
- No resources may be provisioned during architecture validation.
- Product selection is explicitly deferred until this requirements section is approved.
- The first release is a reference implementation, not a completed compliance certification.
- Region, budget, traffic volume, data residency, and regulatory classification are not yet supplied.
## Assumptions
- Orders are JSON and contain an immutable order identifier.
- A single primary region is acceptable for the initial release.
- The service can tolerate eventual consistency for asynchronous fulfillment.
- A managed relational database is appropriate for transactional order state.
- CI has permission to run Terraform formatting, initialization without a backend, validation, and an optional credentialed plan.
- Application container images are published by a separate build pipeline.
## Open questions
- What are peak requests per second, payload size, and daily order volume?
- Which identity provider and client authentication protocol are required?
- What RTO/RPO and disaster-recovery region are required?
- What data residency, PCI, GDPR, or other controls apply?
- Should the database be regional or cross-region, and what is the retention/deletion policy?
- Which downstream systems consume orders, and what delivery semantics do they require?
- What is the approved Google Cloud project, region, DNS zone, and naming convention?
- What are the maximum monthly budget and alerting escalation targets?
Product selection deferred during this step: **true**.

View File

@@ -1,44 +0,0 @@
# Step 0 — Requirements discovery
## Workflow request
Create a high-scale containerized data ingestion pipeline with least-privilege IAM service accounts and automated validation.
## Functional requirements
- Accept authenticated HTTPS requests from external clients.
- Execute stateless application logic behind a versioned service endpoint.
- Publish asynchronous domain events from the application.
- Process events independently and tolerate retry/redelivery.
- Persist durable objects and application state separately.
- Expose operational logs, metrics, and audit-relevant events.
- Support repeatable infrastructure changes through declarative IaC.
## Non-functional requirements
- High availability within a selected Google Cloud region.
- Horizontal scale for bursty HTTP traffic and asynchronous work.
- At-least-once event delivery with idempotent consumers.
- Encryption in transit and at rest using managed defaults initially.
- Least-privilege runtime identities and private network egress where practical.
- Observable deployments with structured logs and actionable health signals.
- Reproducible, reviewable, non-deployment validation in CI.
## Constraints
- Google Cloud is the target cloud; exact products are not selected in discovery.
- Terraform must be deployable without embedding secrets or credentials.
- The baseline must not provision resources during validation.
- A container image must be supplied by the application delivery pipeline.
- State backends, DNS ownership, identity federation, and organization policies are external concerns.
## Assumptions
- A single region is acceptable for the initial deployment.
- The application can be packaged as an OCI container listening on port 8080.
- Events can use at-least-once semantics and consumers can deduplicate.
- A dedicated Google Cloud project is available.
- Managed encryption keys and public ingress are acceptable defaults pending review.
## Open questions
- What are the actual API, event, data-retention, and compliance requirements?
- Which clients and identity provider must authenticate requests?
- What are traffic, payload-size, latency, RTO, and RPO targets?
- Which data is relational, document, object, or analytical?
**Product selection deferred:** `true` for this phase.

View File

@@ -1,15 +0,0 @@
# Pre-emptive Live GCP Environment Discovery (Project: `gcp-solution-architecture-demo`)
## Live Resource Audit
- **Target Google Cloud Project**: `gcp-solution-architecture-demo`
- **Discovered Storage Buckets**: None / Default Bucket
- **Discovered Compute Instances**: None active
- **Discovered Database Instances**: None active
- **Discovered Pub/Sub Topics**: None active
- **Discovered Cloud Run Services**: None active
## Resource Inventory Breakdown
## Current Operational Bottlenecks & Migration Drivers
- As-is infrastructure requires serverless auto-scaling and managed high availability.
- Need for declarative IaC management via Terraform.
- Transition to least-privilege IAM service identities and automated CI validation.

View File

@@ -1,34 +0,0 @@
# Terraform validation evidence
## Scope and safety controls
This validation record is for pre-deployment checks only. No `terraform apply`, resource creation, or cloud provisioning is permitted. The intended configuration must retain:
```hcl
deploy_resources = false
deploy_enabled = false
```
## Required checks
The requested checks are:
```sh
terraform fmt -check -recursive
terraform init -backend=false
terraform validate
terraform plan -refresh=false -lock=false -input=false -out=tfplan
```
## Execution result
**BLOCKED — execution evidence is unavailable in this revision.** The execution environment used to prepare this correction did not provide a repository filesystem, Terraform binary, or command-execution tool. Consequently, these commands were not run here; no exit statuses or command outputs can honestly be reported, and validation is not claimed as successful.
| Check | Command | Exit status | Output |
|---|---|---:|---|
| Formatting | `terraform fmt -check -recursive` | Not executed | Blocked: no command execution capability |
| Backendless initialization | `terraform init -backend=false` | Not executed | Blocked: no command execution capability |
| Configuration validation | `terraform validate` | Not executed | Blocked: backendless init could not be performed |
| No-apply plan-oriented check | `terraform plan -refresh=false -lock=false -input=false -out=tfplan` | Not executed | Blocked: no command execution capability; no resources provisioned |
A real validation run must execute the commands from the repository root, capture stdout/stderr and each process exit status, and confirm that the plan is not applied. Until that run is available, `terraform_format_valid`, `terraform_validation_valid`, and `dry_run_valid` must remain false/unknown rather than being inferred from scripts or this record.

View File

@@ -1,9 +0,0 @@
{
"terraform_format_valid": "pending local execution",
"terraform_validation_valid": "pending local execution",
"dry_run_valid": "pending local execution",
"validation_findings": [
"The repository contains a no-apply validation script.",
"Execution requires Terraform 1.6.x and operator-supplied project and invoker variables; no cloud resources are provisioned by this deliverable."
]
}