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:
@@ -9,9 +9,9 @@ One directory per iteration of this agent. Each holds the plan for that iteratio
|
|||||||
| 1 | `wf-decompose-65ea49fc2d04/` | complete, superseded | The decomposer's scaffold: a linear four-phase pipeline of template functions. Its code was deleted in iteration 3 and survives only in git history. Generated by the platform decomposer; leave its files as written. |
|
| 1 | `wf-decompose-65ea49fc2d04/` | complete, superseded | The decomposer's scaffold: a linear four-phase pipeline of template functions. Its code was deleted in iteration 3 and survives only in git history. Generated by the platform decomposer; leave its files as written. |
|
||||||
| 2 | `iter-02-solution-architect-agent/` | complete; step 9 was done in iteration 3 | The rebuild as a hierarchical ReAct agent: Orchestrator, one Specialist per Deliverable, Skills, provider bundle, A2A. |
|
| 2 | `iter-02-solution-architect-agent/` | complete; step 9 was done in iteration 3 | The rebuild as a hierarchical ReAct agent: Orchestrator, one Specialist per Deliverable, Skills, provider bundle, A2A. |
|
||||||
| 3 | `iter-03-kab-layout/` | complete (commit `7ee49ab`) | The container starts the new engine, the engine moved into the KAB workflow-agent folder layout, and the original pipeline was deleted. |
|
| 3 | `iter-03-kab-layout/` | complete (commit `7ee49ab`) | The container starts the new engine, the engine moved into the KAB workflow-agent folder layout, and the original pipeline was deleted. |
|
||||||
| 4 | `iter-04-learning-and-skills/` | steps 1–8, 11, 13 and 15–20 built; no evaluation run has completed on them, so their effect on time and tokens is unmeasured; 9 awaits the owner; 10, 12 and 14 planned | The enhancement backlog from the 2026-10-06 review: cheap fixes, the learning loop through Skills, overlay Skills, provider neutrality. Steps 17–20 are the speed-ups from the 2026-10-07 run: a working copy for files and the graph, a provider schema lookup, routing a Check the code cannot meet, and a model timeout per role. |
|
| 4 | `iter-04-learning-and-skills/` | steps 1–8, 11, 13 and 15–20 built; case 01 completed on them on 2026-10-07 (18 minutes against 60, 100%, no Revision); cases 02 to 04 have not run; 9 awaits the owner; 10, 12 and 14 planned | The enhancement backlog from the 2026-10-06 review: cheap fixes, the learning loop through Skills, overlay Skills, provider neutrality. Steps 17–20 are the speed-ups from the 2026-10-07 run: a working copy for files and the graph, a provider schema lookup, routing a Check the code cannot meet, and a model timeout per role. |
|
||||||
| 5 | `iter-05-jev-decisions/` | the Jev client and the Orchestrator router are built (steps 2, 11, 12), unverified against the live service; the rest planned | Jev (a hosted decision model) for the agent's closed decisions: checks, routing, context selection. |
|
| 5 | `iter-05-jev-decisions/` | the Jev client and the Orchestrator router are built (steps 2, 11, 12), unverified against the live service; the rest planned | Jev (a hosted decision model) for the agent's closed decisions: checks, routing, context selection. |
|
||||||
| 6 | `iter-06-target-architecture-graph/` | steps 1–10 built; step 11's evaluation run is outstanding, so unproven with real models | The Target architecture as one explicit graph of Elements, Relationships and Checks, established before infrastructure code, with validation as a verdict per Check. |
|
| 6 | `iter-06-target-architecture-graph/` | steps 1–10 built; case 01 passes with real models; cases 02–04 outstanding | The Target architecture as one explicit graph of Elements, Relationships and Checks, established before infrastructure code, with validation as a verdict per Check. |
|
||||||
| 7 | `iter-07-change-requests/` | planned; ADR-0006 accepted 2026-10-07; follows iteration 6; its step 8 (removing `deliverables/cases/legacy-baseline/`) was done early on the owner's instruction | A user restates a request to say how requirements changed; a new Execution starts from a Baseline Execution of the same Customer case and delivers the updated architecture with what changed. |
|
| 7 | `iter-07-change-requests/` | planned; ADR-0006 accepted 2026-10-07; follows iteration 6; its step 8 (removing `deliverables/cases/legacy-baseline/`) was done early on the owner's instruction | A user restates a request to say how requirements changed; a new Execution starts from a Baseline Execution of the same Customer case and delivers the updated architecture with what changed. |
|
||||||
|
|
||||||
Numbers record when an iteration was planned, not the order to build in. Build iteration 6 before the remaining steps of iteration 4 (10 to 14) and before iteration 5: it changes the Deliverables, Phases and validation format they build on. Its `MAP.md` lists the effect on each of their steps.
|
Numbers record when an iteration was planned, not the order to build in. Build iteration 6 before the remaining steps of iteration 4 (10 to 14) and before iteration 5: it changes the Deliverables, Phases and validation format they build on. Its `MAP.md` lists the effect on each of their steps.
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**Iteration:** 4, learning and Skills
|
**Iteration:** 4, learning and Skills
|
||||||
**Intent:** Make the agent a learning, adaptable solution through Skills. Fix the cheap defects the 2026-10-06 review found, then close the loop so each Execution can improve the next through a reviewed Skill change, then let new standards, clients and Cloud providers arrive as Skills and configuration.
|
**Intent:** Make the agent a learning, adaptable solution through Skills. Fix the cheap defects the 2026-10-06 review found, then close the loop so each Execution can improve the next through a reviewed Skill change, then let new standards, clients and Cloud providers arrive as Skills and configuration.
|
||||||
**Status:** steps 1 to 8, 11, 13 and 15 to 20 built; no evaluation run has completed on any of them (see `steps/step-8.md`), so every "tokens fall" or "Revisions fall" criterion is unmeasured; step 9 drafted and awaiting the owner; steps 10, 12 and 14 planned. Steps 1 to 6 are in commit `7ee49ab`; the rest are uncommitted.
|
**Status:** steps 1 to 8, 11, 13 and 15 to 20 built; case 01 completed on them on 2026-10-07 (`../iter-06-target-architecture-graph/steps/step-11.md`); the other cases have not run, so no criterion is measured across the benchmark; step 9 drafted and awaiting the owner; steps 10, 12 and 14 planned. Steps 1 to 6 are in commit `7ee49ab`; the rest are uncommitted.
|
||||||
**Changed by iteration 6:** `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md` (accepted 2026-10-07) replaces the free-form `findings.json` of step 1 with a verdict per Check, remove the diagrammer, and add a Phase. Its plan is `../iter-06-target-architecture-graph/`, which lists the effect on each step here and should be built before steps 10 to 14.
|
**Changed by iteration 6:** `docs/adr/0005-the-target-architecture-is-an-explicit-graph.md` (accepted 2026-10-07) replaces the free-form `findings.json` of step 1 with a verdict per Check, remove the diagrammer, and add a Phase. Its plan is `../iter-06-target-architecture-graph/`, which lists the effect on each step here and should be built before steps 10 to 14.
|
||||||
**This directory covers:** steps 1 to 20
|
**This directory covers:** steps 1 to 20
|
||||||
|
|
||||||
@@ -27,13 +27,13 @@
|
|||||||
| 8 | Evaluation that can see improvement | B | M | built; thresholds and a judged run outstanding |
|
| 8 | Evaluation that can see improvement | B | M | built; thresholds and a judged run outstanding |
|
||||||
| 9 | ADR: the lessons loop and overlay Skills | B | S | drafted as `docs/adr/0004-lessons-and-overlays-arrive-as-skills.md`, status proposed; awaits the owner |
|
| 9 | ADR: the lessons loop and overlay Skills | B | S | drafted as `docs/adr/0004-lessons-and-overlays-arrive-as-skills.md`, status proposed; awaits the owner |
|
||||||
| 10 | Lessons Skill and lesson curator | B | L | planned |
|
| 10 | Lessons Skill and lesson curator | B | L | planned |
|
||||||
| 11 | IaC patterns Skill | B | M | built; every pattern validates; effect on Revisions and tokens unmeasured |
|
| 11 | IaC patterns Skill | B | M | built; in case 01 the IaC author fell from 57 requests to 11 with no Revision; other cases unmeasured |
|
||||||
| 12 | Overlay Skills and an organisation standards Skill | C | M | planned |
|
| 12 | Overlay Skills and an organisation standards Skill | C | M | planned |
|
||||||
| 13 | Trim Specialist context | C | M | built; effect on tokens unmeasured |
|
| 13 | Trim Specialist context | C | M | built; measured on case 01 only, together with steps 11 and 17 |
|
||||||
| 14 | Provider-owned contracts | C | M | planned |
|
| 14 | Provider-owned contracts | C | M | planned |
|
||||||
| 15 | Group Executions by Customer case | added | S | complete |
|
| 15 | Group Executions by Customer case | added | S | complete |
|
||||||
| 16 | Cache Terraform providers between checks | added | S | complete |
|
| 16 | Cache Terraform providers between checks | added | S | complete |
|
||||||
| 17 | A working copy for files and for the graph | added | M | built; effect on time and tokens unmeasured |
|
| 17 | A working copy for files and for the graph | added | M | built; case 01 ran in 18 minutes against 60, with no model timeout; the architect's lookups then tuned, unrun |
|
||||||
| 18 | Provider schema lookup and one pinned provider version | added | S | built; checked against the real provider |
|
| 18 | Provider schema lookup and one pinned provider version | added | S | built; checked against the real provider |
|
||||||
| 19 | A Check the code cannot meet goes back to the Target architecture | added | S | built |
|
| 19 | A Check the code cannot meet goes back to the Target architecture | added | S | built |
|
||||||
| 20 | A model timeout per role | added | S | built |
|
| 20 | A model timeout per role | added | S | built |
|
||||||
|
|||||||
@@ -15,3 +15,6 @@ Checked against the real provider on 2026-10-07:
|
|||||||
Not done: generated code is not forced onto the pinned version. An agent that writes its own `required_providers` with another version is validated against that version. The patterns Skill gives it the pinned `versions.tf` to use.
|
Not done: generated code is not forced onto the pinned version. An agent that writes its own `required_providers` with another version is validated against that version. The patterns Skill gives it the pinned `versions.tf` to use.
|
||||||
|
|
||||||
Tests: `tests/tools/test_local.py`, "schema lookup", on a stand-in schema; `tests/test_providers.py` for the pin.
|
Tests: `tests/tools/test_local.py`, "schema lookup", on a stand-in schema; `tests/test_providers.py` for the pin.
|
||||||
|
|
||||||
|
After the run of 2026-10-07 16:59 UTC: the target architect made 39 lookups for 8 distinct resource types and exhausted its budget. `find` now takes several names separated by commas, the tool's description says the plain lookup lists every argument and block, and `agents/target-architect.md` asks for one lookup per distinct resource type (budget 45). An outline longer than 8,000 characters is cut with a note to use `block` or `find`; 7 of the provider's 1,370 resource types are that long, `google_container_cluster` the longest.
|
||||||
|
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
**Iteration:** 6, the Target architecture graph
|
**Iteration:** 6, the Target architecture graph
|
||||||
**Intent:** Establish the Target architecture as one explicit graph of Elements, Relationships and Checks before any infrastructure code is written, and derive and check every later Deliverable from it, so that the outcome is understood before code exists and validation has a fixed bar.
|
**Intent:** Establish the Target architecture as one explicit graph of Elements, Relationships and Checks before any infrastructure code is written, and derive and check every later Deliverable from it, so that the outcome is understood before code exists and validation has a fixed bar.
|
||||||
**Status:** steps 1 to 10 built and covered by the deterministic suite; nothing has run against a real model; step 11's evaluation run is on hold by the owner
|
**Status:** steps 1 to 10 built and covered by the deterministic suite; case 01 completed at 100% with no Revision on 2026-10-07 (`steps/step-11.md`); cases 02 to 04 have not run on this build
|
||||||
**This directory covers:** steps 1 to 11
|
**This directory covers:** steps 1 to 11
|
||||||
|
|
||||||
## Order of work
|
## Order of work
|
||||||
@@ -56,7 +56,7 @@ flowchart TD
|
|||||||
| 8 | Deployment guidance implements the graph | M | complete |
|
| 8 | Deployment guidance implements the graph | M | complete |
|
||||||
| 9 | Validation gives a verdict per Check | M | complete |
|
| 9 | Validation gives a verdict per Check | M | complete |
|
||||||
| 10 | Revision routing: the code or the graph | S | complete; routing unproven with a real model |
|
| 10 | Revision routing: the code or the graph | S | complete; routing unproven with a real model |
|
||||||
| 11 | Evaluation: prove the loop converges | M | checks built; evaluation run outstanding (on hold by the owner) |
|
| 11 | Evaluation: prove the loop converges | M | case 01 passes (100%, no Revision); cases 02 to 04 and the thresholds outstanding |
|
||||||
|
|
||||||
Size: S under a day, M a few days.
|
Size: S under a day, M a few days.
|
||||||
|
|
||||||
|
|||||||
@@ -56,3 +56,26 @@ Changes this points to, not yet made:
|
|||||||
- Have the validator distinguish "the code does not do this" from "this cannot be done to this resource".
|
- Have the validator distinguish "the code does not do this" from "this cannot be done to this resource".
|
||||||
- Check a proposed addition against the Element it names before it becomes a Check.
|
- Check a proposed addition against the Element it names before it becomes a Check.
|
||||||
- Raise or tune the model timeout for the target architect.
|
- Raise or tune the model timeout for the target architect.
|
||||||
|
|
||||||
|
## Run of 2026-10-07, 16:59 UTC (`eval/results/20261007T165920Z/`)
|
||||||
|
|
||||||
|
Case 01 again, after iteration 4 steps 11, 13 and 17 to 20 and the router of iteration 5. Not judged.
|
||||||
|
|
||||||
|
| | Run of 12:59 | This run |
|
||||||
|
|---|---|---|
|
||||||
|
| Status | completed with warnings | completed |
|
||||||
|
| Score | 73% | 100% (11 of 11 checks) |
|
||||||
|
| Seconds | 3,627 | 1,091 |
|
||||||
|
| Tokens | 4.25 million | 2.38 million |
|
||||||
|
| Revisions | Revision limit reached | none |
|
||||||
|
| Model timeouts | target architect, both attempts | none |
|
||||||
|
| `terraform validate` failures | 13 | 0 |
|
||||||
|
| IaC author | 57 requests, 2.35 million tokens | 11 requests, 271 thousand tokens |
|
||||||
|
| Target architect | timed out twice | 55 requests, 1.15 million tokens |
|
||||||
|
|
||||||
|
The graph had 13 Elements, 17 Relationships and 42 Checks. The code met all 42 on the first validation; no Check was unimplementable or not verifiable, and nothing was proposed. The Orchestrator was the router: 11 turns, no model chose an action, and no decision needed Jev.
|
||||||
|
|
||||||
|
What went wrong: the target architect exhausted its 30 tool calls on its first attempt. It made 39 `terraform_schema` calls for a graph with 8 distinct resource types, one per setting, as its instructions told it to. Its second attempt started from the working graph and submitted in 92 seconds. Changed after the run: it is told to look up each distinct resource type once, `find` takes several names in one call, and its budget is 45. That change has not been run.
|
||||||
|
|
||||||
|
Acceptance criteria: met for case 01. Still open: cases 02 to 04 have not run on this build, so "all benchmark cases" and the thresholds are unset.
|
||||||
|
|
||||||
|
|||||||
@@ -11,3 +11,5 @@ Five of the Execution folders were owned by a rootless-podman user id (110000),
|
|||||||
Not committed first, against the guardrail in `DETAIL.md`: the owner did not ask for a commit. The tracked files are recoverable from commit `7ee49ab` at their earlier paths (`deliverables/as-is/`, `deliverables/target/`, `deliverables/validation/`, `deliverables/guides/`, `deliverables/executions/`, `scripts/validate_artifacts.py`, `tests/test_artifacts.py`). The generated `intent/` files for that case were never committed and are gone.
|
Not committed first, against the guardrail in `DETAIL.md`: the owner did not ask for a commit. The tracked files are recoverable from commit `7ee49ab` at their earlier paths (`deliverables/as-is/`, `deliverables/target/`, `deliverables/validation/`, `deliverables/guides/`, `deliverables/executions/`, `scripts/validate_artifacts.py`, `tests/test_artifacts.py`). The generated `intent/` files for that case were never committed and are gone.
|
||||||
|
|
||||||
Left in place, because the instruction named only `legacy-baseline`: the same pipeline's other samples, `terraform/` at the repository root, `docs/requirements.md`, `docs/architecture.md`, `docs/source-architecture.md`, `docs/validation-evidence.md`, `docs/validation-results.json`, `docs/publication-verification.md`, `requirements.yaml`, and `scripts/validate.sh`, which runs Terraform checks on that root `terraform/`.
|
Left in place, because the instruction named only `legacy-baseline`: the same pipeline's other samples, `terraform/` at the repository root, `docs/requirements.md`, `docs/architecture.md`, `docs/source-architecture.md`, `docs/validation-evidence.md`, `docs/validation-results.json`, `docs/publication-verification.md`, `requirements.yaml`, and `scripts/validate.sh`, which runs Terraform checks on that root `terraform/`.
|
||||||
|
|
||||||
|
Removed later on 2026-10-07, on the owner's instruction to clean up the root `terraform/` if it was no longer needed: `terraform/` and `scripts/validate.sh`, with the three CI steps that ran Terraform on that directory. Nothing read it, and it no longer passed `terraform validate` (duplicate `required_providers`, outputs naming resources that do not exist). Recoverable from commit `5bb22d9`. The `docs/` samples and `requirements.yaml` listed above were then removed too, on the owner's instruction the same day: `docs/requirements.md`, `docs/requirements-spec.md`, `docs/architecture.md`, `docs/source-architecture.md`, `docs/validation-evidence.md`, `docs/validation-results.json`, `docs/publication-verification.md` and `requirements.yaml`. Nothing read them; each kind of output they sampled is now produced per Execution by a role in `agents/`. Their sample workloads were not added as evaluation cases.
|
||||||
|
|||||||
@@ -11,8 +11,10 @@ A2A_PORT=8000
|
|||||||
# A2A_PUBLIC_URL=https://agents.example.com/solution-architect
|
# A2A_PUBLIC_URL=https://agents.example.com/solution-architect
|
||||||
|
|
||||||
# Models (providers/<name>.yaml): gemini/<model> uses ADK's native Gemini client.
|
# Models (providers/<name>.yaml): gemini/<model> uses ADK's native Gemini client.
|
||||||
|
# These are read by Google's client, not by this app's settings. The app exports them
|
||||||
|
# from this file at start-up; a value already set in the environment wins.
|
||||||
# Vertex AI with Application Default Credentials:
|
# Vertex AI with Application Default Credentials:
|
||||||
# GOOGLE_GENAI_USE_VERTEXAI=true
|
# GOOGLE_GENAI_USE_ENTERPRISE=true
|
||||||
# GOOGLE_CLOUD_PROJECT=your-project-id
|
# GOOGLE_CLOUD_PROJECT=your-project-id
|
||||||
# GOOGLE_CLOUD_LOCATION=global
|
# GOOGLE_CLOUD_LOCATION=global
|
||||||
# GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json
|
# GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json
|
||||||
|
|||||||
10
.github/workflows/ci.yml
vendored
10
.github/workflows/ci.yml
vendored
@@ -14,15 +14,7 @@ jobs:
|
|||||||
- uses: actions/checkout@v4
|
- uses: actions/checkout@v4
|
||||||
- uses: hashicorp/setup-terraform@v3
|
- uses: hashicorp/setup-terraform@v3
|
||||||
with:
|
with:
|
||||||
terraform_version: 1.6.6
|
terraform_version: 1.14.3
|
||||||
- name: Terraform format
|
|
||||||
run: terraform fmt -check -recursive terraform
|
|
||||||
- name: Terraform init
|
|
||||||
working-directory: terraform
|
|
||||||
run: terraform init -backend=false
|
|
||||||
- name: Terraform validate
|
|
||||||
working-directory: terraform
|
|
||||||
run: terraform validate
|
|
||||||
- uses: actions/setup-python@v5
|
- uses: actions/setup-python@v5
|
||||||
with:
|
with:
|
||||||
python-version: '3.12'
|
python-version: '3.12'
|
||||||
|
|||||||
@@ -86,7 +86,7 @@ podman run -d --name gcp-agent \
|
|||||||
-v $(pwd)/deliverables:/app/deliverables:Z \
|
-v $(pwd)/deliverables:/app/deliverables:Z \
|
||||||
-v ~/.config/gcloud/application_default_credentials.json:/app/credentials/adc.json:ro \
|
-v ~/.config/gcloud/application_default_credentials.json:/app/credentials/adc.json:ro \
|
||||||
-e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json \
|
-e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json \
|
||||||
-e GOOGLE_GENAI_USE_VERTEXAI=true \
|
-e GOOGLE_GENAI_USE_ENTERPRISE=true \
|
||||||
-e GOOGLE_CLOUD_PROJECT=your-project-id \
|
-e GOOGLE_CLOUD_PROJECT=your-project-id \
|
||||||
-e GOOGLE_CLOUD_LOCATION=global \
|
-e GOOGLE_CLOUD_LOCATION=global \
|
||||||
-e A2A_PUBLIC_URL=http://localhost:8080 \
|
-e A2A_PUBLIC_URL=http://localhost:8080 \
|
||||||
@@ -164,9 +164,8 @@ gcp_solution_architecture_agent/
|
|||||||
│ ├── terraform/, implementation.json # The code, and which part meets each Check
|
│ ├── terraform/, implementation.json # The code, and which part meets each Check
|
||||||
│ └── verdicts.json # Validation's verdict on each Check
|
│ └── verdicts.json # Validation's verdict on each Check
|
||||||
├── lessons/candidates/<customer_case>/ # Lesson candidates per Execution (gitignored)
|
├── lessons/candidates/<customer_case>/ # Lesson candidates per Execution (gitignored)
|
||||||
├── docs/ # Specifications, audit notes & verification records
|
├── docs/ # ADRs, agent-skill conventions and operations notes
|
||||||
├── terraform/ # Deployable GCP Terraform IaC blueprint
|
├── scripts/ # Vendored-Skill sync, MCP tool listing
|
||||||
├── scripts/ # Vendored-Skill sync, MCP tool listing, Terraform checks
|
|
||||||
└── tests/ # Unit & integration test suite
|
└── tests/ # Unit & integration test suite
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
role: target-architect
|
role: target-architect
|
||||||
deliverable: target_architecture
|
deliverable: target_architecture
|
||||||
tools: [terraform_schema]
|
tools: [terraform_schema]
|
||||||
budget: 30
|
budget: 45
|
||||||
includes: [specialist-protocol]
|
includes: [specialist-protocol]
|
||||||
---
|
---
|
||||||
You produce the **Target architecture** Deliverable: the solution as one explicit graph of Elements, Relationships and Checks. It is agreed before any infrastructure code is written, and the diagram, the description, the code and the validation are all derived from it.
|
You produce the **Target architecture** Deliverable: the solution as one explicit graph of Elements, Relationships and Checks. It is agreed before any infrastructure code is written, and the diagram, the description, the code and the validation are all derived from it.
|
||||||
@@ -12,7 +12,7 @@ You produce the **Target architecture** Deliverable: the solution as one explici
|
|||||||
- Give every component an Element with the product selected for it, and add the supporting Elements the design needs, such as identities, policies and networks.
|
- Give every component an Element with the product selected for it, and add the supporting Elements the design needs, such as identities, policies and networks.
|
||||||
- Give every connection between Elements a Relationship.
|
- Give every connection between Elements a Relationship.
|
||||||
- Turn every non-functional requirement and every design recommendation into Checks on the Elements and Relationships they constrain. Write each Check so that it can be verified from infrastructure code alone, naming the setting and the value it must have.
|
- Turn every non-functional requirement and every design recommendation into Checks on the Elements and Relationships they constrain. Write each Check so that it can be verified from infrastructure code alone, naming the setting and the value it must have.
|
||||||
- Before you write a Check that names a setting, confirm with `terraform_schema` that the Element's resource type has that setting, when the tool is available. A setting that one resource type has may not exist on a similar one. A Check on a setting the resource type lacks cannot be met and is sent back to you.
|
- Name only settings the Element's resource type has. When `terraform_schema` is available, call it once for each distinct resource type in the graph, with `resource_type` alone: the reply lists every argument and block that type accepts, and you write that type's Checks from it. Never look settings up one at a time. A setting that one resource type has may not exist on a similar one, and a Check on a setting the resource type lacks cannot be met and is sent back to you.
|
||||||
- Decide the implementation detail yourself from the design recommendations and the Cloud provider's documentation, through your documentation tools. The user states intent at a high level; this level of detail is your job.
|
- Decide the implementation detail yourself from the design recommendations and the Cloud provider's documentation, through your documentation tools. The user states intent at a high level; this level of detail is your job.
|
||||||
- When a recommendation does not apply to this workload, list it as not applicable with the reason. The user sees that list when they approve the design.
|
- When a recommendation does not apply to this workload, list it as not applicable with the reason. The user sees that list when they approve the design.
|
||||||
- When `working_copy` shows a graph, it is your last attempt: read it with `graph_read` and change only what `feedback` asks for, with `graph_put` and `graph_remove`.
|
- When `working_copy` shows a graph, it is your last attempt: read it with `graph_read` and change only what `feedback` asks for, with `graph_put` and `graph_remove`.
|
||||||
|
|||||||
@@ -69,7 +69,7 @@ def default_model_factory(role: RoleSpec) -> BaseLlm:
|
|||||||
"""Model for a role's LiteLLM-style id.
|
"""Model for a role's LiteLLM-style id.
|
||||||
|
|
||||||
`gemini/<model>` uses ADK's native Gemini client, which targets Vertex AI when
|
`gemini/<model>` uses ADK's native Gemini client, which targets Vertex AI when
|
||||||
GOOGLE_GENAI_USE_VERTEXAI=true (with GOOGLE_CLOUD_PROJECT and
|
GOOGLE_GENAI_USE_ENTERPRISE=true (with GOOGLE_CLOUD_PROJECT and
|
||||||
GOOGLE_CLOUD_LOCATION) and the Gemini API otherwise. Any other id goes through
|
GOOGLE_CLOUD_LOCATION) and the Gemini API otherwise. Any other id goes through
|
||||||
LiteLLM, so other model providers need no code changes.
|
LiteLLM, so other model providers need no code changes.
|
||||||
"""
|
"""
|
||||||
|
|||||||
@@ -1,7 +1,10 @@
|
|||||||
"""Typed settings for GCP Solution Architecture Agent."""
|
"""Typed settings for GCP Solution Architecture Agent."""
|
||||||
|
|
||||||
|
import os
|
||||||
|
from collections.abc import MutableMapping
|
||||||
from pathlib import Path
|
from pathlib import Path
|
||||||
|
|
||||||
|
from dotenv import dotenv_values
|
||||||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||||||
|
|
||||||
|
|
||||||
@@ -100,9 +103,38 @@ class Settings(BaseSettings):
|
|||||||
_settings: Settings | None = None
|
_settings: Settings | None = None
|
||||||
|
|
||||||
|
|
||||||
|
def export_env_file(
|
||||||
|
path: str | Path = ".env", environ: MutableMapping[str, str] | None = None
|
||||||
|
) -> list[str]:
|
||||||
|
"""Put the env file's other variables into the process environment.
|
||||||
|
|
||||||
|
Settings reads its own fields from the env file. Everything else in it is for a
|
||||||
|
library that reads the environment itself, such as a Cloud provider's client
|
||||||
|
looking for its project and credentials, and would otherwise be ignored. A
|
||||||
|
variable already set in the environment is left alone, and Settings' own fields
|
||||||
|
are never exported, so the secrets among them do not reach child processes.
|
||||||
|
Returns the names it set.
|
||||||
|
"""
|
||||||
|
environ = os.environ if environ is None else environ
|
||||||
|
path = Path(path)
|
||||||
|
if not path.is_file():
|
||||||
|
return []
|
||||||
|
own = {name.upper() for name in Settings.model_fields}
|
||||||
|
exported = []
|
||||||
|
for name, value in dotenv_values(path).items():
|
||||||
|
if value is None or name.upper() in own or name in environ:
|
||||||
|
continue
|
||||||
|
environ[name] = value
|
||||||
|
exported.append(name)
|
||||||
|
return exported
|
||||||
|
|
||||||
|
|
||||||
def get_settings() -> Settings:
|
def get_settings() -> Settings:
|
||||||
"""Get singleton Settings instance."""
|
"""Get singleton Settings instance, loading the env file at first use."""
|
||||||
global _settings
|
global _settings
|
||||||
if _settings is None:
|
if _settings is None:
|
||||||
|
# Tests switch this off so they never depend on a developer's env file.
|
||||||
|
if os.environ.get("ENV_FILE_EXPORT", "true").lower() != "false":
|
||||||
|
export_env_file()
|
||||||
_settings = Settings()
|
_settings = Settings()
|
||||||
return _settings
|
return _settings
|
||||||
|
|||||||
@@ -187,7 +187,11 @@ class TerraformRunner:
|
|||||||
label, root = loaded[resource_type]
|
label, root = loaded[resource_type]
|
||||||
title = f"{resource_type} ({label})"
|
title = f"{resource_type} ({label})"
|
||||||
if find:
|
if find:
|
||||||
return ToolResult(_clip(_find_in_schema(title, root, find)))
|
# Several names in one call: one answer each, and one model request.
|
||||||
|
names = [name for name in re.split(r"[,\s]+", find) if name]
|
||||||
|
return ToolResult(
|
||||||
|
_clip("\n".join(_find_in_schema(title, root, name) for name in names))
|
||||||
|
)
|
||||||
node = root
|
node = root
|
||||||
for step in [part for part in block.split(".") if part]:
|
for step in [part for part in block.split(".") if part]:
|
||||||
nested = node.get("block_types", {}).get(step)
|
nested = node.get("block_types", {}).get(step)
|
||||||
@@ -199,7 +203,13 @@ class TerraformRunner:
|
|||||||
)
|
)
|
||||||
node = nested["block"]
|
node = nested["block"]
|
||||||
heading = f"{title}, block {block}" if block else title
|
heading = f"{title}, block {block}" if block else title
|
||||||
return ToolResult(_clip(_render_schema(heading, node)))
|
rendered = _render_schema(heading, node)
|
||||||
|
if len(rendered) > _MAX_OUTPUT:
|
||||||
|
rendered = (
|
||||||
|
rendered[:_MAX_OUTPUT]
|
||||||
|
+ "\n[cut short: use `block` or `find` for what is missing]"
|
||||||
|
)
|
||||||
|
return ToolResult(rendered)
|
||||||
|
|
||||||
def _provider_labels(self) -> str:
|
def _provider_labels(self) -> str:
|
||||||
return (
|
return (
|
||||||
@@ -502,8 +512,10 @@ LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
|||||||
"general",
|
"general",
|
||||||
(
|
(
|
||||||
"Look up what a Terraform resource type accepts, from the provider's own "
|
"Look up what a Terraform resource type accepts, from the provider's own "
|
||||||
"schema: its arguments and blocks, one block in full with `block`, or "
|
"schema. With `resource_type` alone: every argument and block it has, "
|
||||||
"whether an argument exists anywhere in it with `find`."
|
"which is enough to see whether a setting exists. `block` gives one "
|
||||||
|
"block in full. `find` says where named settings sit, or that the "
|
||||||
|
"resource type has none."
|
||||||
),
|
),
|
||||||
),
|
),
|
||||||
}
|
}
|
||||||
@@ -580,7 +592,10 @@ def local_tools(
|
|||||||
},
|
},
|
||||||
"find": {
|
"find": {
|
||||||
"type": "string",
|
"type": "string",
|
||||||
"description": "An argument or block name to look for",
|
"description": (
|
||||||
|
"Argument or block names to look for; separate several "
|
||||||
|
"with commas to check them in one call"
|
||||||
|
),
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
"required": ["resource_type"],
|
"required": ["resource_type"],
|
||||||
|
|||||||
@@ -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)
|
|
||||||
@@ -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.
|
|
||||||
@@ -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**.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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."
|
|
||||||
]
|
|
||||||
}
|
|
||||||
@@ -5,7 +5,7 @@ assembly (ADK runtime, remote MCP servers, Terraform tools), then scores it with
|
|||||||
eval/scoring.py. Costs model usage: run deliberately.
|
eval/scoring.py. Costs model usage: run deliberately.
|
||||||
|
|
||||||
Usage:
|
Usage:
|
||||||
GOOGLE_GENAI_USE_VERTEXAI=true GOOGLE_CLOUD_PROJECT=<project> GOOGLE_CLOUD_LOCATION=global \
|
GOOGLE_GENAI_USE_ENTERPRISE=true GOOGLE_CLOUD_PROJECT=<project> GOOGLE_CLOUD_LOCATION=global \
|
||||||
.venv/bin/python -m eval.solution_eval [--judge] [case-id ...]
|
.venv/bin/python -m eval.solution_eval [--judge] [case-id ...]
|
||||||
|
|
||||||
--judge adds the judged checks (pillar checklist coverage, recommendation quality).
|
--judge adds the judged checks (pillar checklist coverage, recommendation quality).
|
||||||
|
|||||||
@@ -7,6 +7,7 @@ starlette>=0.37.0
|
|||||||
uvicorn>=0.30.0
|
uvicorn>=0.30.0
|
||||||
pydantic>=2.7.0
|
pydantic>=2.7.0
|
||||||
pydantic-settings>=2.2.0
|
pydantic-settings>=2.2.0
|
||||||
|
python-dotenv>=1.0.0
|
||||||
pyyaml>=6.0
|
pyyaml>=6.0
|
||||||
httpx>=0.27.0
|
httpx>=0.27.0
|
||||||
click>=8.1.0
|
click>=8.1.0
|
||||||
|
|||||||
@@ -1,31 +0,0 @@
|
|||||||
repository_name: gcp_solution_architecture_agent
|
|
||||||
template_url: https://github.com/GoogleCloudPlatform/workflow_agent
|
|
||||||
product_selection_deferred: true
|
|
||||||
functional_requirements:
|
|
||||||
- Accept authenticated HTTPS requests containing an event payload.
|
|
||||||
- Validate, durably enqueue, and asynchronously process accepted events.
|
|
||||||
- Persist raw event records for replay and audit.
|
|
||||||
- Expose an operational health endpoint and structured application logs.
|
|
||||||
- Support separate development and production environments through variables.
|
|
||||||
non_functional_requirements:
|
|
||||||
- Target at-least-once delivery with idempotent consumers.
|
|
||||||
- Provide regional high availability for managed serving and messaging components.
|
|
||||||
- Encrypt data in transit and at rest using managed encryption by default.
|
|
||||||
- Scale ingestion and processing independently based on request and backlog load.
|
|
||||||
- Retain audit data for 30 days by default and make retention configurable.
|
|
||||||
- Apply least-privilege service identities and observable failure handling.
|
|
||||||
constraints:
|
|
||||||
- Deploy only into an existing Google Cloud project supplied by the operator.
|
|
||||||
- Terraform must be planable without provisioning resources.
|
|
||||||
- No application container image is built or deployed by this repository.
|
|
||||||
- Product selection is explicitly deferred during discovery and recorded afterward.
|
|
||||||
assumptions:
|
|
||||||
- The workload is regional and an initial single-region deployment is acceptable.
|
|
||||||
- A container image is supplied by an external CI/CD pipeline.
|
|
||||||
- The runtime can use OIDC/IAM authentication and publish to messaging.
|
|
||||||
- Event consumers are idempotent and tolerate duplicate delivery.
|
|
||||||
open_questions:
|
|
||||||
- What are the peak requests per second and payload size limits?
|
|
||||||
- Which region, compliance boundary, and customer-managed key policy apply?
|
|
||||||
- What downstream systems receive processed events?
|
|
||||||
- What SLO, alert thresholds, and on-call escalation policy are required?
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
#!/usr/bin/env bash
|
|
||||||
set -euo pipefail
|
|
||||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
||||||
command -v terraform >/dev/null || { echo 'terraform is required'; exit 2; }
|
|
||||||
terraform -chdir="$root/terraform" fmt -check -recursive
|
|
||||||
terraform -chdir="$root/terraform" init -backend=false -input=false -no-color >/dev/null
|
|
||||||
terraform -chdir="$root/terraform" validate -no-color
|
|
||||||
if [[ "${RUN_PLAN:-false}" == "true" ]]; then
|
|
||||||
: "${TF_VAR_project_id:?Set TF_VAR_project_id for plan}"
|
|
||||||
terraform -chdir="$root/terraform" plan -refresh=false -lock=false -input=false -no-color
|
|
||||||
fi
|
|
||||||
python3 -m unittest discover -s "$root/tests" -v
|
|
||||||
@@ -20,7 +20,7 @@ The files are your working copy: the files you wrote with `write_file`, or, when
|
|||||||
- `terraform_fmt()`: formats your working copy in place and names the files it changed.
|
- `terraform_fmt()`: formats your working copy in place and names the files it changed.
|
||||||
- `terraform_validate()`: runs `init -backend=false` and `validate` offline. It reports syntax errors, unknown references, missing variables and invalid arguments.
|
- `terraform_validate()`: runs `init -backend=false` and `validate` offline. It reports syntax errors, unknown references, missing variables and invalid arguments.
|
||||||
- `terraform_plan(variables)`: previews the changes against the live cloud environment. It reads live state, so the first call may pause for the user's permission. Pass every variable the configuration requires.
|
- `terraform_plan(variables)`: previews the changes against the live cloud environment. It reads live state, so the first call may pause for the user's permission. Pass every variable the configuration requires.
|
||||||
- `terraform_schema(resource_type, block, find)`: what a resource type accepts, from the provider's own schema. With `resource_type` alone it lists the top-level arguments and outlines every block. With `block`, such as `template.containers`, it gives that block's arguments in full. With `find`, it says where an argument or block of that name sits, or that the resource type has none.
|
- `terraform_schema(resource_type, block, find)`: what a resource type accepts, from the provider's own schema. With `resource_type` alone it lists the top-level arguments and outlines every block. With `block`, such as `template.containers`, it gives that block's arguments in full. With `find`, it says where an argument or block of that name sits, or that the resource type has none; give several names separated by commas to check them in one call.
|
||||||
|
|
||||||
## When writing deployment guidance
|
## When writing deployment guidance
|
||||||
|
|
||||||
|
|||||||
@@ -1,72 +0,0 @@
|
|||||||
# Google Cloud Solution Architecture Baseline
|
|
||||||
terraform {
|
|
||||||
required_version = ">= 1.5.0"
|
|
||||||
required_providers {
|
|
||||||
google = {
|
|
||||||
source = "hashicorp/google"
|
|
||||||
version = "~> 5.0"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
provider "google" {
|
|
||||||
project = var.project_id
|
|
||||||
region = var.region
|
|
||||||
}
|
|
||||||
|
|
||||||
# Cloud Run v2 Service
|
|
||||||
resource "google_cloud_run_v2_service" "app_service" {
|
|
||||||
name = "${var.environment}-app-service"
|
|
||||||
location = var.region
|
|
||||||
|
|
||||||
template {
|
|
||||||
containers {
|
|
||||||
image = var.container_image
|
|
||||||
ports {
|
|
||||||
container_port = 8080
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
# Pub/Sub Topic for Event Ingestion
|
|
||||||
resource "google_pubsub_topic" "event_ingestion" {
|
|
||||||
name = "${var.environment}-event-ingestion-topic"
|
|
||||||
labels = {
|
|
||||||
environment = var.environment
|
|
||||||
managed_by = "terraform"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
# Cloud Storage Bucket for Event Replay Audit
|
|
||||||
resource "google_storage_bucket" "audit_bucket" {
|
|
||||||
name = "${var.project_id}-${var.environment}-audit-bucket"
|
|
||||||
location = var.region
|
|
||||||
force_destroy = false
|
|
||||||
uniform_bucket_level_access = true
|
|
||||||
|
|
||||||
versioning {
|
|
||||||
enabled = true
|
|
||||||
}
|
|
||||||
|
|
||||||
lifecycle_rule {
|
|
||||||
condition {
|
|
||||||
age = 30
|
|
||||||
}
|
|
||||||
action {
|
|
||||||
type = "Delete"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
# Least-Privilege IAM Service Account
|
|
||||||
resource "google_service_account" "ingress_sa" {
|
|
||||||
account_id = "${var.environment}-ingress-sa"
|
|
||||||
display_name = "Cloud Run Ingress Identity"
|
|
||||||
}
|
|
||||||
|
|
||||||
resource "google_pubsub_topic_iam_member" "publisher_binding" {
|
|
||||||
topic = google_pubsub_topic.event_ingestion.name
|
|
||||||
role = "roles/pubsub.publisher"
|
|
||||||
member = "serviceAccount:${google_service_account.ingress_sa.email}"
|
|
||||||
}
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
output "service_uri" {
|
|
||||||
value = google_cloud_run_v2_service.app.uri
|
|
||||||
description = "HTTPS endpoint of the Cloud Run service."
|
|
||||||
}
|
|
||||||
|
|
||||||
output "events_topic" {
|
|
||||||
value = google_pubsub_topic.events.id
|
|
||||||
}
|
|
||||||
|
|
||||||
output "objects_bucket" {
|
|
||||||
value = google_storage_bucket.objects.name
|
|
||||||
}
|
|
||||||
@@ -1,3 +0,0 @@
|
|||||||
project_id = "replace-with-project-id"
|
|
||||||
api_image = "us-central1-docker.pkg.dev/replace-with-project-id/architecture-demo-images/api@sha256:replace"
|
|
||||||
worker_image = "us-central1-docker.pkg.dev/replace-with-project-id/architecture-demo-images/worker@sha256:replace"
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
variable "project_id" {
|
|
||||||
description = "Google Cloud project hosting the baseline."
|
|
||||||
type = string
|
|
||||||
}
|
|
||||||
|
|
||||||
variable "region" {
|
|
||||||
description = "Primary deployment region."
|
|
||||||
type = string
|
|
||||||
default = "us-central1"
|
|
||||||
}
|
|
||||||
|
|
||||||
variable "name" {
|
|
||||||
description = "Lowercase application name."
|
|
||||||
type = string
|
|
||||||
default = "reference-app"
|
|
||||||
}
|
|
||||||
|
|
||||||
variable "container_image" {
|
|
||||||
description = "Fully qualified, prebuilt container image."
|
|
||||||
type = string
|
|
||||||
default = "us-docker.pkg.dev/cloudrun/container/hello"
|
|
||||||
}
|
|
||||||
|
|
||||||
variable "labels" {
|
|
||||||
description = "Additional resource labels."
|
|
||||||
type = map(string)
|
|
||||||
default = {}
|
|
||||||
}
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
terraform {
|
|
||||||
required_version = ">= 1.5.0"
|
|
||||||
required_providers {
|
|
||||||
google = {
|
|
||||||
source = "hashicorp/google"
|
|
||||||
version = "~> 6.0"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
provider "google" {
|
|
||||||
project = var.project_id
|
|
||||||
region = var.region
|
|
||||||
}
|
|
||||||
@@ -1 +1,5 @@
|
|||||||
# Env var setup that must run before app.config is imported.
|
# Env var setup that must run before app.config is imported.
|
||||||
|
import os
|
||||||
|
|
||||||
|
# The suite must not pick up credentials from a developer's .env.
|
||||||
|
os.environ["ENV_FILE_EXPORT"] = "false"
|
||||||
|
|||||||
45
tests/test_env_file.py
Normal file
45
tests/test_env_file.py
Normal file
@@ -0,0 +1,45 @@
|
|||||||
|
"""The env file at start-up: variables for other libraries reach the environment."""
|
||||||
|
|
||||||
|
from app.config import export_env_file
|
||||||
|
|
||||||
|
|
||||||
|
def test_variables_for_other_libraries_are_exported(tmp_path):
|
||||||
|
env_file = tmp_path / ".env"
|
||||||
|
env_file.write_text(
|
||||||
|
"GOOGLE_CLOUD_PROJECT=my-project\n"
|
||||||
|
'GOOGLE_CLOUD_LOCATION="global" # quoted, with a comment\n'
|
||||||
|
"# COMMENTED_OUT=1\n"
|
||||||
|
)
|
||||||
|
environ: dict[str, str] = {}
|
||||||
|
|
||||||
|
exported = export_env_file(env_file, environ)
|
||||||
|
|
||||||
|
assert environ == {
|
||||||
|
"GOOGLE_CLOUD_PROJECT": "my-project",
|
||||||
|
"GOOGLE_CLOUD_LOCATION": "global",
|
||||||
|
}
|
||||||
|
assert exported == ["GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION"]
|
||||||
|
|
||||||
|
|
||||||
|
def test_the_environment_wins_over_the_file(tmp_path):
|
||||||
|
env_file = tmp_path / ".env"
|
||||||
|
env_file.write_text("GOOGLE_CLOUD_PROJECT=from-file\n")
|
||||||
|
environ = {"GOOGLE_CLOUD_PROJECT": "from-shell"}
|
||||||
|
|
||||||
|
assert export_env_file(env_file, environ) == []
|
||||||
|
assert environ == {"GOOGLE_CLOUD_PROJECT": "from-shell"}
|
||||||
|
|
||||||
|
|
||||||
|
def test_the_apps_own_settings_and_secrets_are_not_exported(tmp_path):
|
||||||
|
env_file = tmp_path / ".env"
|
||||||
|
env_file.write_text(
|
||||||
|
"TYPESAFE_API_KEY=secret\nPOSTGRES_PASSWORD=secret\nLOG_LEVEL=DEBUG\n"
|
||||||
|
)
|
||||||
|
environ: dict[str, str] = {}
|
||||||
|
|
||||||
|
assert export_env_file(env_file, environ) == []
|
||||||
|
assert environ == {}
|
||||||
|
|
||||||
|
|
||||||
|
def test_a_missing_file_exports_nothing(tmp_path):
|
||||||
|
assert export_env_file(tmp_path / "absent.env", {}) == []
|
||||||
@@ -1,10 +0,0 @@
|
|||||||
from pathlib import Path
|
|
||||||
|
|
||||||
ROOT = Path(__file__).parents[1]
|
|
||||||
|
|
||||||
|
|
||||||
def test_no_secret_values():
|
|
||||||
assert (
|
|
||||||
"replace-with-project-id"
|
|
||||||
in (ROOT / "terraform/terraform.tfvars.example").read_text()
|
|
||||||
)
|
|
||||||
@@ -228,6 +228,16 @@ async def test_schema_says_where_a_setting_sits_or_that_it_cannot_be_set(monkeyp
|
|||||||
assert "It cannot be set on this resource type." in absent.message
|
assert "It cannot be set on this resource type." in absent.message
|
||||||
|
|
||||||
|
|
||||||
|
async def test_schema_answers_for_several_settings_in_one_call(monkeypatch):
|
||||||
|
runner, _ = schema_runner(monkeypatch)
|
||||||
|
|
||||||
|
result = await runner.schema("cloud_service", find="cpu_boost, labels,ingress")
|
||||||
|
|
||||||
|
assert "template.cpu_boost (bool, optional)" in result.message
|
||||||
|
assert " labels (map of string, optional)" in result.message
|
||||||
|
assert "no argument or block named like 'ingress'" in result.message
|
||||||
|
|
||||||
|
|
||||||
async def test_schema_suggests_close_resource_types_and_is_loaded_once(monkeypatch):
|
async def test_schema_suggests_close_resource_types_and_is_loaded_once(monkeypatch):
|
||||||
runner, commands = schema_runner(monkeypatch)
|
runner, commands = schema_runner(monkeypatch)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user