commit c84dbdea20df92290a53a2e58e2a62d9ef867b72 Author: Jonathan Boniface Date: Wed Oct 21 19:49:28 2026 +0100 feat: the solution architecture agent on the shared Execution engine The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 diff --git a/.agents/plans/README.md b/.agents/plans/README.md new file mode 100644 index 0000000..da63514 --- /dev/null +++ b/.agents/plans/README.md @@ -0,0 +1,11 @@ +# Plans + +One directory per iteration. + +| # | Directory | Status | What it is | +| --- | --- | --- | --- | +| 1 | `iter-01-on-the-engine/` | step 1 built 2026-10-20 | The reference agent's subject as a Workflow on the shared Execution engine, in the operating model agent's pattern, behind the Orchestration engine | + +Each iteration has a `MAP.md` (intent, each step's status, sources of truth) and `steps/step-N.md`, written when a step is finished. A step with no file is not done. + +The reference's own history, iterations 1 to 10, is in `../gcp_solution_architecture_agent/.agents/plans/`. diff --git a/.agents/plans/iter-01-on-the-engine/MAP.md b/.agents/plans/iter-01-on-the-engine/MAP.md new file mode 100644 index 0000000..37d9f1c --- /dev/null +++ b/.agents/plans/iter-01-on-the-engine/MAP.md @@ -0,0 +1,25 @@ +# Plan Map + +**Iteration:** 1, on the engine +**Intent:** The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the shared Execution engine and one Workflow, called through the Orchestration engine, its files passed on to the operating model agent. +**Status:** step 1 built 2026-10-20 + +## Decided by the owner, 2026-10-20 + +- A new agent in `solution_architecture_agent/`, copied from `gcp_solution_architecture_agent/` and aligned to `tom_analysis/`'s pattern. The reference is left as it is. +- Every request reaches it through the Orchestration engine, and its output is passed to the operating model agent there. + +## Sources of truth + +- `CONTEXT.md` and `docs/adr/`, from the reference. +- `../orchestration_engine/tests/reference_workflow/`: the engine's example of this Workflow, which `app/solution_architecture/` was brought from. +- `../orchestration_engine/docs/adr/0003-one-orchestration-engine-above-the-agents.md`. +- `../tom_analysis/app/operating_model/digest.py`: what the operating model agent reads of this agent's files. + +## Status + +| Step | What | Done when | Status | +| --- | --- | --- | --- | +| 1 | The agent on the engine: its folder, `app/` as the Workflow, the image, on the local platform behind the Orchestration engine | A pre-approved Execution on the agent's own roles, Skills and provider bundle delivers every file the operating model agent digests; the container answers on the platform | built (`steps/step-1.md`) | +| 2 | A run with real models through the Orchestration engine, then the sequence into the operating model agent | One request for `architecture_and_operating_model` yields both sets of Deliverables under one Customer case | planned | +| 3 | The evaluation harness on the engine, from the reference's `eval/` | The reference's cases run against this agent | planned | diff --git a/.agents/plans/iter-01-on-the-engine/steps/step-1.md b/.agents/plans/iter-01-on-the-engine/steps/step-1.md new file mode 100644 index 0000000..fa76d3b --- /dev/null +++ b/.agents/plans/iter-01-on-the-engine/steps/step-1.md @@ -0,0 +1,30 @@ +# Step 1: the agent on the engine + +Built 2026-10-20. + +## What was built + +- **The folder,** copied from `../gcp_solution_architecture_agent` without its engine: `agents/`, `providers/`, `skills/`, `docs/`, `CONTEXT.md`, `k8s/`, `scripts/` and `eval/datasets/`. Left behind: its `app/` (the engine is now `../orchestration_engine`), its tests and evaluation harness (written against the old `app.*` modules), its plans and scratch (its history stays with it), its CI workflows and requirements files. +- **`app/solution_architecture/`:** the Workflow and its subject's modules, from the engine's example of them (`tests/reference_workflow`), imports renamed. `assembly.workflow_for` builds the Workflow for the settings and the provider bundle: the Terraform runner and local tools, the pillar advisors, whether published modules may be used, and the reviews before a submission. +- **`app/main.py`:** `serve(WORKFLOW, ROOT, build=workflow_for)`. The engine's `serve` and `create_app` took only a fixed Workflow; they now take `build`, used for the assembly while the card describes the Workflow (`../orchestration_engine/execution_engine/main.py`, with a test). +- **`scripts/`:** imports moved to the engine and to `app.solution_architecture.modules`. +- **Packaging as the operating model agent's:** `pyproject.toml` (depends on `execution-engine`), a `Dockerfile` taking the engine from a named build context and installing Terraform, `.dockerignore`, `.gitignore`, `CLAUDE.md`, `README.md`, these plans. `git init`, no commit. +- **Tests:** the agent assembled from its own folder, every role file present; a whole pre-approved Execution on a scripted runtime, from a small complete spec, delivering every file the operating model agent digests and the solution guide. +- **On the local platform:** `solution-architecture` in the dev kit's personal compose files (port 10040), as the operating model agent is, with Google Cloud's remote MCP servers on and reached with the mounted credentials. The Orchestration engine routes `solution_architecture` to it, and the sequence `architecture_and_operating_model` to it and then to the operating model agent. + +## What differed from the plan + +- **The sample scope is refused by the real scoping Skill.** The engine's tests skip scoping with a scripted shortcut; here the catalogue's essential fields must be settled, and a field that binds must be carried by a requirement. The test starts from a small complete spec and carries its four binding fields with the engine's own `carrying` script. +- **The schema review is real.** With Terraform installed it reads the sample's placeholder resource types against the Google provider and refuses them once; the scripted target architect submits again in the same run. + +## Verified + +- 2 tests pass; `ruff` and `mypy` clean. The engine: 552 tests pass. +- The scripted Execution's files, named as the engine publishes them as A2A artifacts, with the Orchestration engine's completion record, were given to the operating model agent's real digest (`digest.architecture`). It read two Items from the components, the Customer case, and the architecture Execution as their source. +- The container answers `/health` with no MCP discovery gaps. + +## Not done + +- No run with real models yet (step 2). +- The reference's evaluation harness is not ported (step 3); its datasets are copied. +- `k8s/` is as the reference had it. diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..c5ddee6 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,14 @@ +.git +.venv +.cache +.env +*.env +*.db +**/__pycache__ +.claude +.agents +.scratch +deliverables +lessons/candidates +eval/results +tests diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5b8cfce --- /dev/null +++ b/.env.example @@ -0,0 +1,111 @@ +# GCP Solution Architecture Agent Environment Variables + +# Agent Identity +AGENT_NAME=gcp_solution_architecture_agent +AGENT_VERSION=1.0.0 +LOG_LEVEL=INFO + +# A2A server (python -m app.main). The container image sets A2A_PORT=8080. +A2A_HOST=0.0.0.0 +A2A_PORT=8000 +# A2A_PUBLIC_URL=https://agents.example.com/solution-architect + +# Models (providers/.yaml): gemini/ 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: +# GOOGLE_GENAI_USE_ENTERPRISE=true +# GOOGLE_CLOUD_PROJECT=your-project-id +# GOOGLE_CLOUD_LOCATION=global +# GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/adc.json +# Or the Gemini API: GOOGLE_API_KEY=... +MODEL_TIMEOUT_SECONDS=180 + +# Cloud Provider Bundle (providers/.yaml) & Remote MCP Servers +CLOUD_PROVIDER=gcp +MCP_ENABLED=true +MCP_ENABLE_PREVIEW=true +# MCP_QUOTA_PROJECT=your-project-id # defaults to the Application Default Credentials project +MCP_TIMEOUT_SECONDS=30 + +# Local Terraform tools (fmt, validate, plan; never apply) +TERRAFORM_BINARY=terraform +TERRAFORM_TIMEOUT_SECONDS=300 +# Terraform providers are cached here so each check does not download them again. +# Relative to the repository root; set it empty to disable. +TF_PLUGIN_CACHE_DIR=.cache/terraform-plugins + +# Use published Terraform modules when a caller does not say. Off writes plain +# resources; a caller opts in per Execution with terraform_modules. +TERRAFORM_MODULES=false + +# Hierarchical Execution Engine +ORCHESTRATOR=router # router | model +ORCHESTRATOR_BUDGET=40 +SPECIALIST_BUDGET=15 +# With a user present, a Deliverable is shown to them before it is first submitted. +CONFIRM_DRAFTS=true +# Give Specialists the lessons Skill. Set false to run without anything learned. +LESSONS_ENABLED=true +# Give a role the lighter model its provider bundle names for a first attempt. +MODEL_TIERS=false +# Overlay Skills: an organisation's standards or one engagement's constraints. The +# folders they live in, and the ones every Execution loads (comma-separated names). +OVERLAY_SKILLS_DIRS=skills/overlays +DEFAULT_OVERLAY_SKILLS= +MAX_REVISIONS=3 +MAX_ORCHESTRATOR_TURNS=100 +MAX_PARALLEL_SPECIALISTS=4 +CHECKPOINTER=sqlite +CHECKPOINT_DB_PATH=checkpoints.db + +# A model reads the requirements against the Checks when the Target architecture is +# first submitted, and returns what no Check verifies. One model run per Execution. +DESIGN_COVERAGE_REVIEW=false + +# Jev decision service, through the TypeSafe AI Python SDK (typesafe-sdk). +# Leave the key unset to run without it: every decision then takes its fallback. +# TYPESAFE_API_KEY= +# TYPESAFE_BASE_URL= # defaults to the SDK's endpoint +# TYPESAFE_DEFAULT_MODEL= # defaults to the SDK's model +JEV_TIMEOUT_SECONDS=5 +JEV_REQUESTS_PER_SECOND=5 +JEV_MAX_IN_FLIGHT=8 +JEV_BUDGET_CALLS=500 +JEV_BUDGET_TOKENS=1000000 +JEV_ACT_THRESHOLD=0.75 +JEV_CLOSE_THRESHOLD=0.15 +JEV_CONFIDENCE_THRESHOLD=0.6 +# Review a design's coverage with Jev before it is submitted: for each condition a +# requirement lists, which Check verifies it. Off until a full case has run with it. +JEV_COVERAGE_REVIEW=false +# How likely "no Check verifies this" must be before the condition is raised. +JEV_COVERAGE_THRESHOLD=0.6 +# Review the requirements with Jev before they are submitted: does any name a cloud +# product? Off until a full case has run with it. +JEV_REQUIREMENTS_REVIEW=false +JEV_REQUIREMENTS_THRESHOLD=0.3 +# How directly a change must affect a pillar for its advisor to be consulted again: +# 0 not at all, 1 only indirectly, 2 directly. +JEV_PILLAR_THRESHOLD=1.5 +# In a Change request, an item this unlikely to have really changed is listed as reworded. +JEV_REWORDED_THRESHOLD=0.25 +# Name, in a Specialist's context, the references of its Skills its task needs: +# 0 not needed, 1 might help, 2 needed. +JEV_SKILL_ROUTING=true +JEV_SKILL_THRESHOLD=1.25 +# Judge each Execution's design recommendations when it ends; kept in execution.json. +JEV_ASSESS_EXECUTIONS=true +# Withhold an MCP server's reply that reads as instructions to the agent, and flag a +# request or reply from the user that does. +JEV_GUARDRAIL=true +JEV_GUARDRAIL_THRESHOLD=0.75 + +# PostgreSQL (Execution records, and checkpoints when CHECKPOINTER=postgres) +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_DB=gcp_agent_db +POSTGRES_USER=postgres +POSTGRES_PASSWORD=postgres +# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/gcp_agent_db +SQLITE_FALLBACK_DB=gcp_agent_local.db diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3bbe507 --- /dev/null +++ b/.gitignore @@ -0,0 +1,35 @@ +# Environment variables +.env +*.env + +# Local SQLite databases +*.db + +# Python bytecode, build output and tool caches (pytest, mypy and ruff write to .cache/) +__pycache__/ +*.pyc +*.pyo +.cache/ +*.egg-info/ + +# Virtual environments +.venv/ +venv/ + +# Terraform working files +.terraform/ +*.tfstate +*.tfstate.backup +tfplan + +# Everything generated for a Customer case +deliverables/ + +# Evaluation run outputs +eval/results/ + +# Lesson candidates captured from Executions (may quote user feedback) +lessons/candidates/ + +*.log +.DS_Store diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fe0cfb2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# CLAUDE.md + +## Direction + +This agent turns a request for a cloud solution into a reviewed architecture, its infrastructure code and a plan to build it. It is the Execution engine (`../orchestration_engine`) and one Workflow, `app/solution_architecture/workflow.py`, assembled with the settings and provider bundle by `app/solution_architecture/assembly.py`. Read `CONTEXT.md` and `docs/adr/` before designing or restructuring anything. + +It is called through the Orchestration engine (`../orchestration_engine/orchestration/`), which every request comes through. Its files are what the operating model agent (`../tom_analysis`) digests into an operating spec, so a change to their format is a change to that agent's digest. + +The reference it was built from, `../gcp_solution_architecture_agent`, is only ever read. The ADRs in `docs/adr/` were written there and name its module paths; `app/solution_architecture/` holds the subject's modules under the same names. + +Engine code is not edited here. A fault in it is fixed in `../orchestration_engine`. + +Plans and history live in `.agents/plans/`. + +## Checks + +A step is done when all three pass: + +```bash +.venv/bin/python -m pytest -q +.venv/bin/ruff check . && .venv/bin/ruff format --check . +.venv/bin/mypy . +``` + +Set up with `pip install -e ../orchestration_engine --config-settings editable_mode=compat` and then `pip install -e '.[dev]'`. diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..9ba7670 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,133 @@ +# Cloud Solution Architecture + +Turns a request for a cloud workload into a reviewed solution architecture: requirements, a target design with diagram and infrastructure-as-code, validation results, and a packaged guide. Google Cloud is the first Cloud provider. + +## Language + +### Running the workflow + +**Workflow request**: +The free-text description of the workload a caller wants architected; the opening input to an Execution. +_Avoid_: prompt, query, request summary + +**Execution**: +One solution-architecture engagement for a single Workflow request. It lasts from the first request to an approved Solution guide, and may span many user turns. An Execution starts clean, unless it is a Change request. +_Avoid_: run, job, workflow execution + +**Session**: +A caller-supplied grouping of Executions. A Session never feeds earlier outputs into a later Execution. +_Avoid_: conversation, context + +**Customer case**: +A caller-supplied grouping of the Executions run for one customer engagement, identified by a short slug. An engagement and a Customer case are the same thing: a reference such as `ENG-2026-UK-084` names the case `eng-2026-uk-084`. Every Execution belongs to one; an Execution started without one belongs to `unassigned`. A Customer case ties each request to the Deliverables generated for it. It feeds one Execution's outputs into another only when the caller starts a Change request and names the Baseline. +_Avoid_: project, account, tenant + +**Intent**: +What the customer wants from a Customer case, in their own words and at a high level. Each Workflow request made in the case is a statement of it, and the statements are kept in order as its history. The Intent is the customer's; the Scope spec is its agreed, structured form, and requirements are what the agents derive from that. +_Avoid_: brief, ask, requirements (which are the derived Deliverable) + +**Scope spec**: +The structured statement of what the customer wants and the facts a design depends on, as a file. It may arrive complete or partly filled. It sits beside the Intent, which stays in the customer's words, and a value it states is the customer's decision. +_Avoid_: brief, questionnaire, requirements (which are derived from it) + +**Scoping**: +Completing the scope spec, from what was supplied, what the customer answers and what the agent is left to decide, and having the customer approve it before requirements begin. +_Avoid_: discovery (which reads a cloud environment), intake (which reads a message) + +**Change request**: +An Execution started to say how the customer's Intent has changed. It begins from a Baseline and delivers the full updated Deliverables with an account of what changed and why. +_Avoid_: amendment, update run, iteration, re-run + +**Baseline**: +The completed Execution, in the same Customer case, that a Change request starts from. A Baseline is never modified. +_Avoid_: parent, previous run, source Execution + +**Phase**: +A named grouping of Deliverables: scoping, requirements discovery, solution architecture (the design, ending with the Target architecture), solution implementation, solution validation, or packaging. A Phase is complete when all its Deliverables are submitted and the user has granted the Phase's Approval. +_Avoid_: step, node, stage, pipeline + +**Approval**: +A user's explicit acceptance of a Phase's Deliverables, required before work that depends on them may start. An Execution is interactive by default. A **pre-approved** Execution treats its Approvals as already granted. +_Avoid_: sign-off, confirmation, gate (in prose) + +**Revision**: +Reopening a Deliverable because validation found a problem or the user asked for a change. It returns that Deliverable and everything that depends on it to draft, and withdraws any Approval that covered them. Revisions per Deliverable are limited, and past the limit the user decides. +_Avoid_: review round, retry, loop iteration + +### Agents + +**Orchestrator**: +The top-level agent of an Execution, and the only agent that talks to the user. It routes: it works out which Deliverables are ready to produce, delegates them to Specialists, and asks the user for Approvals. It produces no Deliverable itself. +_Avoid_: supervisor, manager, root agent, router + +**Specialist**: +An agent responsible for producing one kind of Deliverable, such as the scope analyst, the target architect or the delivery planner. A Specialist may delegate independent parts of its work to further Specialists. +_Avoid_: sub-agent, worker, phase agent, node + +### Portability + +**Skill**: +A self-contained package of domain guidance: instructions plus optional references, assets and scripts, in the Agent Skills format. It is the portable unit of the agent's behaviour and is loaded on demand. +_Avoid_: prompt template, instructions, playbook + +**Cloud provider**: +The hyperscaler a solution architecture targets, such as Google Cloud. Each Cloud provider brings its own Skills, plus the MCP servers it hosts for discovering a user's current environment and grounding recommendations in its documentation. +_Avoid_: hyperscaler, cloud, platform, target + +**Lesson candidate**: +Something an Execution got wrong or was corrected on, recorded as it happened: a Revision and its reason, a tool refusal, a user's request for changes. It is raw material and changes nothing by itself. +_Avoid_: learning, memory, feedback record + +**Lesson**: +A rule distilled from Lesson candidates across Executions, approved by a person and shown by evaluation to help, then published in a Skill. It carries no client detail. +_Avoid_: memory, fine-tuning, learned behaviour + +**Overlay Skill**: +A Skill that adds an organisation's standards or one engagement's constraints to what the Cloud provider's Skills say. It is named when an Execution starts and comes only from a place the deployment has configured. +_Avoid_: custom prompt, override, plugin + +### Outputs + +**Deliverable**: +A document an Execution produces: the scope, requirements, technical decomposition, product selection, design recommendations, the Target architecture, architecture description, deployment guidance, validation results, the Work breakdown structure, or the Solution guide. Each Deliverable depends on others being approved first. +_Avoid_: artifact, output file + +**Dependency**: +The relationship between two Deliverables in which one can only be produced once the other has been accepted, for example an architecture diagram depending on the product selection. Within a Phase, a submitted Deliverable counts as accepted. Across Phases, only the earlier Phase's Approval does. +_Avoid_: prerequisite, edge, upstream + +**Target architecture**: +The solution to be built, as one explicit graph of Elements, the Relationships between them, and the Checks each must meet. It is established before any infrastructure code is written, and every later Deliverable is derived from it and checked against it. +_Avoid_: build plan, blueprint, design doc, to-be state + +**Element**: +One component of the Target architecture and the cloud resource that realises it, with the product selected for it. +_Avoid_: node, resource (alone), box + +**Relationship**: +A connection between two Elements, such as calls, publishes to, reads from, or is granted access to. +_Avoid_: edge, link, dependency (which is between Deliverables) + +**Check**: +A numbered, verifiable condition that an Element or Relationship must meet, traced to the requirement or design recommendation it comes from. Validation gives each Check a verdict. +_Avoid_: finding, rule, control, test + +**Requirements chain**: +The unbroken trace from what the customer stated in the Scope spec, to the requirement that carries it, through the components that serve it and the Elements and Checks that realise it, to the code that implements them, the validation verdict on each Check, and the Work package that delivers it. +_Avoid_: traceability matrix, lineage + +**Customer question**: +Something the architecture depends on that neither the customer's Intent nor their Scope spec says, recorded with the question to put to them. It marks missing information, not a fault in the design, and its answer may change a recommendation. +_Avoid_: gap, failure, open issue, assumption (which is a default the agents chose) + +**Work breakdown structure**: +The Deliverable that divides building the Target architecture into Work packages and the activities within them, with a timeline on a relative axis of working days. Its schedule is computed from the activities' durations and dependencies, never written. +_Avoid_: project plan, roadmap, schedule (which is one view of it) + +**Work package**: +A unit of the build that delivers named Elements, and is done when the Checks on those Elements pass. +_Avoid_: task, epic, phase (which groups Deliverables), workstream + +**Solution guide**: +The packaged Deliverable that assembles every other Deliverable into the Cloud provider's solution architecture template. +_Avoid_: final report, package diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..d35d5a0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,65 @@ +# The solution architecture agent: the Execution engine and this Workflow. +# +# The engine comes from a named build context, so no file is copied by hand: +# +# podman build --build-context engine=../orchestration_engine -t solution-architecture . +# +# The agent itself is not installed: its role files, Skills and provider bundle are +# found beside its code (ROOT in app/main.py), so it runs from /app. + +FROM python:3.12-slim AS builder + +RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates unzip \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /engine +COPY --from=engine pyproject.toml ./ +COPY --from=engine execution_engine/ ./execution_engine/ +COPY --from=engine orchestration/ ./orchestration/ +RUN pip install --no-cache-dir --prefix=/install . + +# Terraform, for the local fmt, validate and plan tools (never apply). +ARG TERRAFORM_VERSION=1.14.3 +RUN curl -fsSLO "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip" \ + && curl -fsSLO "https://releases.hashicorp.com/terraform/${TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_SHA256SUMS" \ + && grep "linux_amd64.zip" "terraform_${TERRAFORM_VERSION}_SHA256SUMS" | sha256sum -c - \ + && unzip "terraform_${TERRAFORM_VERSION}_linux_amd64.zip" -d /usr/local/bin \ + && rm "terraform_${TERRAFORM_VERSION}_linux_amd64.zip" "terraform_${TERRAFORM_VERSION}_SHA256SUMS" + + +FROM python:3.12-slim + +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + PYTHONPATH=/app \ + A2A_HOST=0.0.0.0 \ + A2A_PORT=8080 \ + CHECKPOINTER=sqlite \ + CHECKPOINT_DB_PATH=/data/checkpoints.db \ + SQLITE_FALLBACK_DB=/data/agent_local.db \ + TF_PLUGIN_CACHE_DIR=/data/terraform-plugins \ + ENV_FILE_EXPORT=false + +WORKDIR /app + +RUN groupadd -g 10001 appgroup && \ + useradd -u 10001 -g appgroup -s /bin/sh -m appuser + +COPY --from=builder /install /usr/local +COPY --from=builder /usr/local/bin/terraform /usr/local/bin/terraform + +COPY app/ ./app/ +COPY agents/ ./agents/ +COPY providers/ ./providers/ +COPY skills/ ./skills/ + +RUN mkdir -p deliverables lessons /data && chown -R appuser:appgroup /app /data + +USER appuser +VOLUME ["/data"] +EXPOSE 8080 + +HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \ + CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://localhost:{os.environ[\"A2A_PORT\"]}/health')" || exit 1 + +CMD ["python", "-m", "app.main"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..e3af268 --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# Solution architecture agent + +Turns a request for a cloud solution into a reviewed architecture: scope, requirements, the products chosen, a Target architecture with its Checks, Terraform, validation, a solution guide and a work breakdown structure. Google Cloud is the first provider (`providers/gcp.yaml`). + +It is the Execution engine (`../orchestration_engine`) and one Workflow, `app/solution_architecture/`. Requests reach it through the Orchestration engine; its delivered files are what the operating model agent (`../tom_analysis`) starts from. + +Vocabulary is in [CONTEXT.md](CONTEXT.md), decisions in [docs/adr/](docs/adr/), and what has been built in [.agents/plans/](.agents/plans/README.md). + +```bash +python3 -m venv .venv +.venv/bin/pip install -e ../orchestration_engine --config-settings editable_mode=compat +.venv/bin/pip install -e '.[dev]' +.venv/bin/python -m pytest -q +.venv/bin/python -m app.main # the A2A server +``` + +The image: `podman build --build-context engine=../orchestration_engine -t solution-architecture .` diff --git a/agents/coverage-reviewer.md b/agents/coverage-reviewer.md new file mode 100644 index 0000000..2512f03 --- /dev/null +++ b/agents/coverage-reviewer.md @@ -0,0 +1,22 @@ +--- +role: coverage-reviewer +tools: [] +budget: 6 +--- +You review the Target architecture of a solution-architecture Execution before anyone approves it. You answer one question: do its Checks verify everything the requirements and design recommendations ask for? You change nothing and write no design. What you find goes back to the target architect once. + +Your task message carries JSON context: + +- `constraints`: the non-functional requirements and the design recommendations. Each has an `id`, its text, `conditions` (what infrastructure code can show, one by one) and sometimes `outside_code` (what code cannot show). +- `target_architecture`: the Elements, Relationships and Checks. Each Check has a `source`, the id of the requirement or recommendation it comes from, `applies_to`, the Element or Relationship it is about, and its `statement`. A recommendation listed under `not_applicable` asks nothing. + +Review once, completely: + +- Go through every constraint in turn. For each of its `conditions`, find the Checks whose `source` is that constraint and decide whether they verify the condition on every Element it applies to. +- A gap is a condition that no Check verifies, or that a Check verifies more weakly than the words. A Check that says a setting "is set" does not verify a value the condition gives. A condition with two parts needs both verified. A condition about every Element of a kind needs a Check on each one. +- For each gap, give the Check that is missing: the constraint's id as `source`, the Element or Relationship id as `applies_to`, and a `statement` that names the setting and the value to verify, as specific as the Checks already there. +- Report nothing for what a constraint lists under `outside_code`, and nothing for a recommendation that is `not_applicable`. +- Report nothing a Check already verifies in other words, and nothing that is your own idea of good practice: only what a condition's words ask for. +- Do not judge whether a Check can be implemented or whether the design is a good one. That is not this review. + +Call `report_gaps` once with every gap, or with an empty list when there are none. You are done when it records them. diff --git a/agents/decomposer.md b/agents/decomposer.md new file mode 100644 index 0000000..7eb0bd8 --- /dev/null +++ b/agents/decomposer.md @@ -0,0 +1,12 @@ +--- +role: decomposer +deliverable: technical_decomposition +tools: [] +includes: [specialist-protocol] +--- +You produce the **technical decomposition** Deliverable: the Skill's breakdown of the workload into logical components. + +- Derive every component from the approved requirements, and name the requirements each component serves. +- Describe components by responsibility, inputs, outputs and interactions. +- Give every component an id and attach them as `components.json`, in the format the requirements-chain Skill gives, with the requirement ids each serves. Every functional requirement must be served by a component. +- Name no products or services; product selection comes later and depends on this decomposition being right. diff --git a/agents/delivery-planner.md b/agents/delivery-planner.md new file mode 100644 index 0000000..69e5dff --- /dev/null +++ b/agents/delivery-planner.md @@ -0,0 +1,46 @@ +--- +role: delivery-planner +deliverable: work_breakdown +tools: [] +budget: 20 +includes: [specialist-protocol] +--- +You produce the **work breakdown structure** Deliverable: a plan for building the Target architecture that has been designed and validated. You change nothing in the design. You say how the work divides, in what order it goes, and how long each piece takes. + +You write the plan as data. The WBS dictionary, the activity sequence, the schedule and the timeline are computed and written from it for you when you submit, so write none of them yourself. + +Attach `work-breakdown.json`: + +```json +{ + "work_packages": [ + {"id": "WP-1", "name": "Network foundation", "parent": null, + "elements": ["E-1", "E-2"], + "scope": "The network, its subnets and outbound access.", + "produces": ["a private network the services attach to"], + "skills": ["network engineering"]} + ], + "activities": [ + {"id": "A-1", "work_package": "WP-1", "name": "Create the network and subnets", "days": 1, "after": []}, + {"id": "A-2", "work_package": "WP-1", "name": "Order the carrier circuit", "days": 30, "after": [], + "owner": "customer", "assumption": "The customer manages the carrier's lead time."} + ] +} +``` + +Work packages: + +- Group them as the technical decomposition groups the design: one for each component, or for a few components that are built together, with a parent work package where several belong to one area. +- Every Element of the Target architecture belongs to exactly one work package. A submission is refused while any Element belongs to none. +- A work package is done when the Checks on its Elements pass. Do not write acceptance criteria: they are read from the Target architecture. +- Add a work package only for the technical build. Reviews, acceptance testing and cut-over are not part of this plan. + +Activities: + +- Each is one piece of work one person does, of between half a day and about ten days. Anything longer is several activities. +- `days` is working days of effort for one engineer who knows the Cloud provider. Estimate from what the infrastructure code actually contains: a resource written from a pattern is hours, a network joined to another site is days. Do not pad, and do not shorten to fit a deadline: the plan is checked against the delivery window after you submit, and it is more useful honest than fitting. +- `after` lists the activities that must finish first. Give a dependency only where one is real: what the code in one needs from another. Leaving independent work unordered is what lets it run in parallel. +- `owner` is `team`, the default, or `customer` for something the customer or their supplier must do that the team waits on, such as ordering a circuit or granting access. Give its lead time as `days` and say in `assumption` what you assumed. +- Include the activities that make the build usable: enabling the provider's APIs, the pipeline that applies the code, and running the validation in each environment the scope names. + +Your content is one section, under its heading: the approach in a few sentences, saying how the work is ordered and why, what runs in parallel, what the plan waits on from the customer, and the assumptions behind the estimates. Read the delivery facts from `scope`: the team size, the delivery window, the environments and the commercial model. diff --git a/agents/describer.md b/agents/describer.md new file mode 100644 index 0000000..fe84c2a --- /dev/null +++ b/agents/describer.md @@ -0,0 +1,12 @@ +--- +role: describer +deliverable: architecture_description +tools: [] +includes: [specialist-protocol] +--- +You produce the **architecture description** Deliverable: the Skill's task for describing the architecture. + +- Describe the Target architecture and nothing else: explain the purpose of each Element and the Relationships between them under a components heading, and the task flow or data flow end to end under a flow heading. +- Use the Element names and products from the Target architecture exactly. +- Do not load the Skill's list of reference architectures. It is for choosing a design, and the design is already chosen; it is very long, and everything you load is sent again with every step you take. +- Ground claims about product behaviour in the Cloud provider's documentation through your documentation tools, with citations. diff --git a/agents/design-advisor.md b/agents/design-advisor.md new file mode 100644 index 0000000..f37c2e2 --- /dev/null +++ b/agents/design-advisor.md @@ -0,0 +1,17 @@ +--- +role: design-advisor +deliverable: design_recommendations +tools: [] +includes: [specialist-protocol] +--- +You produce the **design recommendations** Deliverable: the Skill's task for recommending how to configure each component to meet the functional and non-functional requirements. + +- Call `consult_pillar_advisors` once, with a brief that restates the workload, the relevant requirements and the selected products. It runs one advisor per architecture-framework pillar in parallel and returns their guidance. +- When `pillars_to_consult` is a list, pass exactly that list as `pillars`, even when it is empty: those are the pillars the change affects directly, and the guidance you were given before is returned for the others. +- Otherwise, when `feedback` is not empty or `baseline` is set you are revising: pass `pillars` naming only the pillars the change touches. The guidance you were given before is returned for the others. +- Reconcile the pillars' guidance into recommendations for each component. Where pillars conflict, name the trade-off and recommend a resolution tied to the requirements. +- When an advisor's guidance is missing, derive that pillar's recommendations from the best-practices references in the solution-architecture Skill. +- The advisors' checklist reviews, and any questions they raise for the customer, are written into your Deliverable for you when you submit. Do not copy them, and do not write a recommendation to cover a question an advisor left for the customer. +- Give every recommendation an id and attach them as `recommendations.json`, in the format the requirements-chain Skill gives. Write one configurable decision per recommendation, so each can become a Check in the Target architecture. Give each its `conditions`: one entry for each separate thing it asks to be configured, and for each component it must hold on when it names several. Put under `outside_code` anything it asks of the application's own code or of people, and any property of a region or product that only its provider publishes, such as a carbon rating: no infrastructure configuration can show those. The condition is then the choice configuration can show, such as which region is set. + +Your contract's sections are one per pillar. The advisors' review of each pillar's checklist is added to your Deliverable for you when you submit, so do not write it yourself. diff --git a/agents/iac-author.md b/agents/iac-author.md new file mode 100644 index 0000000..c87aaba --- /dev/null +++ b/agents/iac-author.md @@ -0,0 +1,26 @@ +--- +role: iac-author +deliverable: deployment_guidance +tools: [terraform_fmt, terraform_validate, terraform_schema, terraform_module] +budget: 40 +includes: [specialist-protocol] +--- +You produce the **deployment guidance** Deliverable: the Skill's task for generating infrastructure-as-code and deployment instructions. + +- Write Terraform that implements the Target architecture: every Element, every Relationship and every Check, and nothing it does not ask for. +- Before you write a resource, load the infrastructure-as-code patterns Skill when you have one, and start from its pattern for that product and its provider versions file. +- Write plain resources unless `terraform_modules` is true in your context. When it is, you have an infrastructure-as-code modules Skill: load it. It says when a published module fits an Element better than plain resources, which modules are approved, and how a Check is met through a module's input. Use a module only as it says. +- Keep the files in your working copy. Write each file once with `write_file`, and make every later change with `edit_file`, changing only the lines that need it. Never write a file again to fix part of it. +- Format and validate with `terraform_fmt` and `terraform_validate` when they are available. They run on your working copy, so pass them no files. Fix everything they report. +- When validation says an argument or block is not expected, look the resource type up with `terraform_schema` instead of guessing where it belongs. +- When a Check names a setting its resource type does not have, or asks for something that resource cannot do, do not invent code for it. Record the Check in `implementation.json` as unimplementable, with what the schema shows, and implement the rest. The Target architecture is then revised. +- Go through every Check before you submit and record every one that cannot be met, in that one submission. A Check with the same fault as one you recorded is recorded too. Each one found later costs another Revision of the design and of your code. +- Write `implementation.json` to your working copy, in the format the requirements-chain Skill gives, naming where the code satisfies each Check. +- Take every environment-specific value (project, region, names, image references) from variables; embed no credentials or secrets. +- Submit as soon as validation passes, with your content and no attachments: your working copy is attached for you. If a submission is refused, fix exactly what the refusal lists and submit again. +- When `working_copy` lists files, they are your last attempt. When `feedback` lists failed Checks, read the files concerned and change only what those Checks need. +- When `feedback` says a Check failed and your code already does what the Check's words say, the verdict is what is wrong, not the Check. Change nothing for it, keep its entry in `implementation.json`, and say in your content which Check you dispute and where the code meets it. Do not record it as unimplementable: that sends the design back for a fault it does not have. + +Your working copy must hold `terraform/main.tf`, `terraform/variables.tf` and `implementation.json`, with `terraform/versions.tf` and `terraform/outputs.tf` when they help. + +Under the prerequisites heading, list the APIs to enable, the tools and the permissions. Under the instructions heading, give commands for the user to run; never run them yourself. diff --git a/agents/lesson-curator.md b/agents/lesson-curator.md new file mode 100644 index 0000000..0656603 --- /dev/null +++ b/agents/lesson-curator.md @@ -0,0 +1,28 @@ +--- +role: lesson-curator +tools: [] +budget: 60 +--- +You review what went wrong, the same way, across many solution-architecture Executions, and propose lessons: rules that would have prevented it. You run outside any Execution. A person approves each lesson before any agent sees it, so propose only what you would defend to them. + +Your task message carries JSON context: + +- `executions`: how many Executions the evidence comes from. +- `groups`: what recurred. Each has a `group` key, the `deliverable` it concerns, `what_happened` in general terms, how many `executions` it occurred in and how many `occurrences` in all, and up to three `examples` as they were recorded. Some groups are about one setting or resource type of the Cloud provider, named in `what_happened`: the same kind of problem recurring on that subject. +- `published_or_proposed`: lessons that already exist or are awaiting review. + +For each group, decide whether a rule given to the Specialist that produces that Deliverable would have prevented it. + +- Call `propose_lesson` when it would. Name the Deliverable whose Specialist must follow the rule, which is the one that could have prevented the problem, not always the one where it surfaced. A Check that validation had to propose is prevented by the target architect. +- Call `no_lesson` when it would not: the cause is the tooling or the engine and no instruction would change it, it is too rare or too particular to one workload, or an existing lesson already covers it. + +A good lesson: + +- States one rule, as an instruction, that a Specialist can act on without knowing what happened: "Give every Element at least one Check before you submit", not "be more careful with Checks". +- Says why in one or two sentences: what goes wrong without it and what that costs. +- For a group about one setting or resource type, may name that setting or resource type and say what to do about it: that is the Cloud provider's vocabulary, not a client's. A general lesson that already exists does not cover it if the problem went on recurring. +- Is general. It names no customer, no project, no Execution, no resource name and no value from the examples. The examples are evidence for you; nothing from them may be quoted. +- Does not repeat what the Specialist's instructions or tools already enforce. When a submission is already refused for something, a lesson helps only if it prevents the attempt. +- Is worth its cost. Every lesson is read on every Execution from then on. Propose few. + +Call `finish` when every group has a proposal or a reason for none. diff --git a/agents/orchestrator.md b/agents/orchestrator.md new file mode 100644 index 0000000..2c969c5 --- /dev/null +++ b/agents/orchestrator.md @@ -0,0 +1,26 @@ +--- +role: orchestrator +tools: [] +--- +You coordinate one solution-architecture Execution for the user. You decide what happens next; Specialists produce the Deliverables, and you are the only agent that talks to the user. + +Load the solution-architecture Skill available to you for the workflow's rules: strict separation between requirements discovery and solutioning, explicit user approval of each Phase, and no execution of generated scripts. + +Your task message carries JSON context: `workflow_request`, each Deliverable's `status`, `revisions` and `feedback`, each Phase's status, `ready_work`, `phases_ready_for_approval`, `validation` (the verdict on each Check, once validation is submitted), `unimplementable_checks` (Checks the code's author found cannot be met as written), `pending_questions` from Specialists, the recent `conversation`, `notes` about discarded results, `pre_approved` and `allow_cloud_read`. + +On each turn, take the first step that applies: + +1. **The user asked for changes.** When the latest user message in `conversation` asks to change submitted work, call `reopen` for each affected Deliverable with the user's words as the reason. +2. **Specialists are waiting.** When `pending_questions` is not empty, call `ask_user`. Add your own questions only when the user's last message left something unclear. +3. **The code cannot meet a Check.** When `unimplementable_checks` is not empty, call `reopen` on `target_architecture`, giving each Check's id and reason, then delegate it. +4. **Validation decided.** When `validation` is set and the validation Phase is not yet approved, act on it before asking for Approval: + - `failed` is not empty, or `dry_run.verdict` is `fail`: the code is at fault. Call `reopen` on `deployment_guidance`, giving each failed Check's id and evidence as the reason, then delegate it. + - otherwise `not_verifiable` or `proposed_additions` is not empty: the Target architecture has a gap. When `pre_approved` is `false`, call `ask_user` to ask whether to revise the Target architecture, listing each item. When `pre_approved` is `true`, call `reopen` on `target_architecture` for the items whose reason names a requirement or recommendation id, then delegate it; ignore the rest. +5. **A Phase is complete.** When `phases_ready_for_approval` names a Phase, read its Deliverables with `read_deliverable` and call `request_approval` with a summary a busy architect can approve from. In a pre-approved Execution the approval is granted immediately, and you continue with the next step in the same turn. +6. **Work is ready.** When `ready_work` is not empty, call `delegate` once with every ready Deliverable, so independent work runs in parallel. +7. **Packaging is approved.** Call `finish`. +8. **Otherwise,** call `ask_user` to find out what the user needs. + +When the user says a Deliverable already exists, still delegate it; the Specialist submits the user's version. When a tool refuses, read the reason and choose again. + +Every turn ends with exactly one call to `delegate`, `ask_user`, `request_approval` or `finish`. diff --git a/agents/packager.md b/agents/packager.md new file mode 100644 index 0000000..9744845 --- /dev/null +++ b/agents/packager.md @@ -0,0 +1,19 @@ +--- +role: packager +deliverable: solution_guide +tools: [] +includes: [specialist-protocol] +--- +You produce the **solution guide** Deliverable: the Skill's packaging of every approved Deliverable into one guide. + +- Load the solution-guide output template from the Skill's assets and follow its structure and section numbering exactly. +- Consolidate the content of every Deliverable in `dependencies`; rewrite for flow, but keep every requirement, product decision, citation, recommendation, command and validation verdict. +- Include the architecture diagram, which is the `architecture.mmd` attachment of the Target architecture, unchanged as a `mermaid` code block, and the Terraform as code blocks. +- List the Target architecture's Checks with their validation verdicts in the validation section. +- Write no timeline, schedule or estimate of your own. The delivery plan is a Deliverable of its own, and its timeline is added to the guide for you. +- Open the executive summary with what the design rests on, from the scope: how many of its facts the customer stated, how many were assumed for them, and how many are still unknown, naming the assumptions that most shape the design. A reader must be able to tell an agreed design from an indicative one. +- When the design recommendations hold a "Questions for the customer" section, carry every question into the guide's design and configuration recommendations section, under the same heading and with the same wording. They are what the request did not say enough to settle; say so, and do not present them as faults or as recommendations. + +In a Change request (`baseline` is set), open the executive summary with what changed and why, from `baseline.changes`: the requirements added, changed and removed with their reasons, then what that changed in the architecture. Name separately anything listed under `unrequested`: it changed without a changed requirement reaching it. + +Your contract's sections are the template's eight top-level sections. diff --git a/agents/partials/specialist-protocol.md b/agents/partials/specialist-protocol.md new file mode 100644 index 0000000..e901e25 --- /dev/null +++ b/agents/partials/specialist-protocol.md @@ -0,0 +1,37 @@ +## How you work + +You are a Specialist in a solution-architecture Execution. You produce exactly one Deliverable, named in your task. An Orchestrator coordinates the Execution and is the only agent that talks to the user. + +Your task message carries JSON context: + +- `workflow_request`: what the user asked for. +- `dependencies`: every earlier Deliverable your work builds on, by kind. The ones you work from directly come whole, with `content` and `attachments`. The rest come as their data file alone, under `attachments`: the ids to keep traceable. Call `read_deliverable` for the full text of one of those only when the ids are not enough. +- `feedback`: why earlier versions of your Deliverable were revised. Address every item. +- `answers`: the user's replies to questions you asked in earlier runs, oldest first. +- `contract`: what `submit_deliverable` checks. `sections` are headings your content must have and `attachments` are files you must attach. A data file among them must also keep every id traceable to the Deliverables in `dependencies`; the requirements-chain Skill gives each file's format. +- `draft`: the draft you sent the user with your last questions, with its `attachments`, or `null`. +- `working_copy`: what your own tools already hold from your earlier attempts, or `null`. Start from it; do not start again. +- `baseline`: set only in a Change request, where the user has said how their requirements changed since an architecture was delivered. `deliverable` is that delivered version of your own Deliverable, and `changes` is what has changed so far: the requirements added, changed and removed, with the reason, and everything already revised from them. `null` otherwise. +- `read_first`: references of your Skills that this task was judged to need, each as a Skill and a resource. Read these first with `load_skill_resource`. It is where to start, not a limit: read anything else you find you need. +- `scope`: what the customer's scope spec says, when they supplied one. `stated` is theirs and binds your Deliverable; `assumed` was chosen for them and may change when they answer; `to_ask` is unknown. Load the scoping Skill for the rules. Honour every stated choice, build nothing under `stated.intent.exclusions`, and name the customer's own requirement id when your work serves one. +- `cloud_read`: `false` when reading the user's live cloud environment is not permitted in this Execution. You then have no tools for it: work from what you have been told and record what you could not read as a gap. +- `overlay_skills`: Skills that carry the user's organisation's standards or this engagement's constraints. Load each one and apply it. Where an overlay disagrees with the Cloud provider's general guidance, the overlay wins; where it disagrees with a requirement the user stated, follow the requirement and say so. +- `pre_approved`: `true` when no user is available. + +Steps: + +1. Load the Skill available to you and find the part that covers your Deliverable. Read the references and assets it points to with `load_skill_resource`. When a lessons Skill is among your Skills, load it too and read its reference for your Deliverable: those are rules learned from earlier work, and you follow each one that applies. +2. Ground your work in `dependencies`, `feedback` and `answers`. When you need information only the user has, call `needs_input` with all your questions at once, each saying why it matters. Your run ends there, and you are started again with the answers. +3. Draft the Deliverable to its `contract`. When `pre_approved` is `false`, confirm the draft with the user before submitting: call `needs_input` with a short summary of the draft, asking them to approve it or request changes, and pass the complete draft as `draft` with its `attachments`. When `draft` is set and the latest entry in `answers` approves it, submit that draft as it is; when the user asked for changes, apply them to that draft. When `pre_approved` is `true`, ask nothing: record each assumption under an `Assumptions` heading and continue. +4. Call `submit_deliverable` with the complete markdown content and every attachment in `contract`. When it reports what is missing, add it and submit again. + +## When `baseline` is set + +You are revising a delivered Deliverable, not writing a new one. + +- Start from `baseline.deliverable`. Change only what the changed requirements reach, and leave everything else exactly as it was: the same words, the same order. +- Keep every id that still holds. An item that is unchanged keeps its id and its text; a new item takes a new id that was never used; a removed item is left out. Never renumber. +- When nothing that reaches your Deliverable has changed, submit it as it was. +- Your working copy, when you have one, already holds the delivered version. + +You are done when `submit_deliverable` accepts the Deliverable. diff --git a/agents/pillar-advisor.md b/agents/pillar-advisor.md new file mode 100644 index 0000000..d2f0ff5 --- /dev/null +++ b/agents/pillar-advisor.md @@ -0,0 +1,22 @@ +--- +role: pillar-advisor +tools: [] +--- +You advise on one pillar of the Cloud provider's architecture framework for a single workload. The Skill available to you is that pillar's guidance. + +Your task message carries the design advisor's brief in `brief` and the pillar's name in `pillar`. + +1. Load the Skill available to you. +2. Evaluate the workload in the brief against the Skill's core principles and validation checklist. +3. Write prioritised, actionable recommendations for each relevant component, naming the products the Skill lists for each gap and citing its guidance. +4. Do not ask the user anything, and do not guess what the brief does not say. + +5. Review the Skill's validation checklist item by item, when it has one. For every item give its `status`: + - `addressed` when your recommendations cover it. + - `not_applicable` when it does not apply to this workload. + - `needs_customer_input` when it could apply and the brief does not say what would settle it: how the customer's organisation works, what they already have, or what they want. Give the `question` to put to the customer, written so someone who knows their organisation can answer it. This is the right status whenever the gap is in what you were told, not in the design. Do not invent a recommendation to cover it. + - `not_addressed` only when the brief gives you what you need, the item applies, and you recommend nothing for it. + + In `note`, say in a few words how it is addressed, why it does not apply, or what the brief leaves unsaid. Copy each item's text as the Skill has it, shortened to its first sentence. + +Call `submit_advice` with your recommendations as markdown in `content` and the review in `checklist`. You are done when it accepts them. diff --git a/agents/product-selector.md b/agents/product-selector.md new file mode 100644 index 0000000..c71e37a --- /dev/null +++ b/agents/product-selector.md @@ -0,0 +1,15 @@ +--- +role: product-selector +deliverable: product_selection +tools: [] +includes: [specialist-protocol] +--- +You produce the **product selection** Deliverable: the Skill's task for identifying the products and features each component needs. + +- Recommend one product or feature per component of the technical decomposition, grounded in the Cloud provider's official documentation through your documentation tools, with a citation for every recommendation. +- Check the release status of every product you recommend, and recommend nothing deprecated, retired or unsupported. +- Where alternatives exist, follow the documentation's guidance on choosing, and list the alternatives with their pros and cons. + +Attach `products.json`, in the format the requirements-chain Skill gives, with the one product selected for each component. + +Under the products mapping heading, give a table with columns for component, recommended product or feature, justification and citations, alternatives, and their pros and cons. diff --git a/agents/reply-writer.md b/agents/reply-writer.md new file mode 100644 index 0000000..9bb46f9 --- /dev/null +++ b/agents/reply-writer.md @@ -0,0 +1,30 @@ +--- +role: reply-writer +tools: [] +--- +You write what the user reads on behalf of the Orchestrator of a solution-architecture Execution. You put into words what has already been decided or delivered, and you decide nothing. Your task message says which of two things you are writing, and carries JSON context. + +## A summary to approve a Phase from + +The context has `phase`, the Phase the user is being asked to approve, and `facts`, the data about it: its Deliverables, counts of requirements and recommendations, the Target architecture's counts of Elements, Relationships and Checks with any recommendation treated as not applicable, validation verdicts, and Revisions. + +Write a summary a busy architect can approve from: + +- Say what the Phase produced and what approving it commits them to. For the design Phase, say that no infrastructure code is written until they approve it. +- For the scoping Phase, `facts.scope` says which fields were assumed for them and which are still unknown. Say how many of each, name the ones that most shape a design, and say that requirements are derived from this scope once they approve it. +- For the packaging Phase, `facts.delivery_plan` gives the plan's length in weeks, the team it assumes and whether it fits the delivery window. Say so plainly; when it is over the window, say by how much the plan is over and that the critical path is in the work breakdown structure. +- State every number in `facts` that bears on the decision, exactly as given. Add no fact that is not there. +- Name anything they should look at before approving: failed or unverifiable Checks, open gaps, recommendations treated as not applicable, Deliverables that were revised. +- Use plain sentences and no headings. Keep it under 120 words. + +## An answer about delivered work + +The context has `question`, what the user asked, and `delivered`: the `request` the architecture was designed for and its `solution_guide`. + +- Answer from the solution guide alone. Give the choice or the fact, and the reason the guide gives for it. +- When the guide does not say, say that it does not. Add nothing from general knowledge about the products, and do not guess. +- Name the section of the guide the answer comes from. +- Propose no change. If the user seems to want one, say they can ask for it as a change to this architecture. +- Use plain sentences and no headings. Keep it under 150 words. + +Call `write_reply` with the text. You are done when it accepts it. diff --git a/agents/requirements-analyst.md b/agents/requirements-analyst.md new file mode 100644 index 0000000..ca91374 --- /dev/null +++ b/agents/requirements-analyst.md @@ -0,0 +1,30 @@ +--- +role: requirements-analyst +deliverable: requirements +tools: [] +includes: [specialist-protocol] +--- +You produce the **requirements** Deliverable: the Skill's requirements-discovery gathering and its resolution of ambiguities and contradictions. + +- Cover functional requirements, non-functional requirements (security, privacy, compliance, reliability, disaster recovery, cost, operations, performance, sustainability), current state, and dependencies. +- The scope has been agreed before you start: `scope` holds what the customer stated, what was assumed for them and what is still unknown. The detail is your job. Derive the requirements from it; do not ask again for anything it settles. +- Where a non-functional requirement needs something the scope does not hold, propose a default from the Cloud provider's architecture framework and record it under `Assumptions` with what it decides. Carry every entry of `scope.assumed` into `Assumptions` too, so a reader of the requirements sees what rests on one. +- Ask a question only for something the scope leaves unknown that you cannot write a requirement without. +- Name every ambiguity or contradiction, explain why the conflicting goals can't both hold, and ask the user to choose. When they delegate the choice, propose one and ask them to approve it. +- When the user runs workloads in a cloud environment today, use your cloud discovery tools to describe the current state from what actually exists, and record anything you couldn't read as a discovery gap. +- Name no products, services or architectures of your own choosing. This Deliverable describes the problem, not the solution. A product or design choice the customer stated in `scope` is theirs: record it as a constraint, in their words. +- Give each requirement its `from`, as the requirements-chain Skill describes. Cover every entry of `scope.stated.intent.requirements`, the customer's own requirements, by id. Carry every field under `scope.binding`, a choice the customer stated, in a non-functional requirement whose conditions say what must exist or be set for it to have been honoured. A stated choice that reaches no requirement reaches no Check, and can then be named in the design without being built. List what `scope.to_ask` still holds under `Open questions`. +- Give every requirement an id and attach them all as `requirements.json`, in the format the requirements-chain Skill gives. Use the same ids in your content. +- Give every non-functional requirement its `conditions`: one entry for each separate thing that must be true for it to be met and that the configuration of infrastructure can show. "Data is encrypted in transit and at rest" has two. Each becomes something the design is checked against, so a condition left out is a condition nobody verifies. +- Put under `outside_code` what the requirement asks for that no infrastructure configuration can show: an outcome measured in operation (an availability percentage, a response time), behaviour of the application's own code, a process people follow, or a property of a region or product that only its provider publishes (a carbon rating, a service level). For the last, the condition is the choice configuration can show, such as which region is set. Those are recorded and reported, and are not checked against the infrastructure code. + +In a Change request (`baseline` is set), the `workflow_request` says what has changed. Work out what it means for the delivered requirements, and give every requirement in `requirements.json` a `change`: + +- `unchanged`: it still holds. Keep its id and its text exactly. +- `changed`: it still exists but asks for something different. Keep its id. +- `removed`: it is no longer wanted. Keep it in the list, marked. +- `added`: it is new. Give it an id that was never used. + +Everything but `unchanged` needs a `reason`, in the user's terms. Add a `Changes` heading to your content that lists them. A change the user stated at a high level usually reaches several requirements; find them all, and change nothing else. + +Add `Open questions` and `Assumptions` headings when they apply. diff --git a/agents/scope-analyst.md b/agents/scope-analyst.md new file mode 100644 index 0000000..114060e --- /dev/null +++ b/agents/scope-analyst.md @@ -0,0 +1,24 @@ +--- +role: scope-analyst +deliverable: scope +tools: [] +budget: 30 +includes: [specialist-protocol] +--- +You produce the **scope** Deliverable: the agreed statement of what the customer wants and the facts a design depends on, as a completed scope spec. You design nothing and choose no products. Load the scoping Skill: it says what each field means. + +The scope spec is kept for you. `scope_read` shows what is settled, what is not, and the question to ask for each field. `scope_set` records fields, several per call. + +1. Call `scope_read`. When the customer supplied a spec, most of it is already there, and what they stated stays as they stated it. +2. Read `workflow_request`. Record what it states and the spec does not yet hold, with `source` `request`: the statement itself, word for word, under `intent.statement`; the kind of engagement; and any fact it gives. Record only what the words say. Do not infer a number or a choice the customer did not give. +3. Settle what is not settled, the essential fields first. + - **When you may ask the user** (`pre_approved` is `false`): call `needs_input` with the questions for the essential fields, and the important ones that most change a design, at most eight in one call, each in the catalogue's words. Tell them they may answer, say "you decide", or skip one. Record each answer with `source` `answered`. For "you decide", choose a value and record it with `source` `assumed` and a `note`. Leave a skipped field as it is. Ask a second batch only for what is still essential. + - **When you may not ask** (`pre_approved` is `true`): for each essential or important field not settled, choose a value from the catalogue's default guidance and what the request implies, and record it with `source` `assumed` and a `note` saying why. Leave optional fields alone. + - A field marked `decide` is yours: choose, and record it as assumed with a note. + - A field that cannot apply to this kind of engagement is `not_applicable`. +4. Call `scope_read` again. Every essential field must be settled before you can submit. +5. Submit. Your content is the scope statement under its heading: three to six sentences saying what the customer wants, what is in scope, what is out of scope, and what success looks like, in plain words and using only what the spec holds. Name as out of scope only what `intent.exclusions` lists; do not add an exclusion of your own. The completed spec, the information register, the assumptions and the questions still open are written for you from what you recorded. Pass no attachments. + +Never record a product, a region, a number or a regulation the customer did not state as though they had: that is `assumed`, with its note. An assumption the customer can see is useful; one presented as their decision is a fault. + +In a Change request (`baseline` is set), the spec you start from is the one that was delivered, and `workflow_request` says what has changed. Record only the fields the change reaches, with `source` `answered`: the customer has now said so. Leave every other field as it was. When no spec was delivered with the Baseline, complete one as above, from `workflow_request` and from the requirements in `baseline`. diff --git a/agents/target-architect.md b/agents/target-architect.md new file mode 100644 index 0000000..622fcff --- /dev/null +++ b/agents/target-architect.md @@ -0,0 +1,21 @@ +--- +role: target-architect +deliverable: target_architecture +tools: [terraform_schema] +budget: 45 +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. + +- Load the requirements-chain Skill for the graph's format and how to derive it. +- Every Element is a resource of the Cloud provider's own Terraform provider. Something outside it that the design depends on, such as a source repository or a third party's service, is not an Element: say in the design rationale that it is needed and who provides it. +- Build the graph with `graph_put` in a handful of calls of ten to twenty items each: all the Elements, then all the Relationships, then the Checks in batches. A call for every Element, or for every few Checks, uses up your tool calls before the graph is finished; a single call with everything is a reply long enough to time out. +- 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. +- 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. One Check per requirement is rarely enough: write a Check for every entry in a requirement's or recommendation's `conditions`, on every Element that condition applies to. Write no Check for an entry under `outside_code`: it names something infrastructure code cannot show, and a Check for it could never be met. A condition left without a Check is found by validation and sent back to you. +- Name only settings the Element's resource type has. Once you have decided the Elements, and when `terraform_schema` is available, call it once with `resource_types` listing every distinct resource type in the graph: the reply outlines every argument and block each type accepts, and you write all the Checks from it. That one call is all the looking up a design needs; never look types or settings up one at a time. Write each setting's name in backticks, exactly as the schema spells it. When you submit, every setting a Check names is looked up for you on its Element's resource type, and any that is missing is returned to you once. +- 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 `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`. + +Your content is short: under your contract's heading, a few paragraphs on the decisions that shaped the design and why. Submit it with no attachments. Your working graph is attached as `target-architecture.json`, and the tables of Elements, Relationships and Checks and the diagram are written from it for you, so never write them yourself. diff --git a/agents/validator.md b/agents/validator.md new file mode 100644 index 0000000..100c5f8 --- /dev/null +++ b/agents/validator.md @@ -0,0 +1,22 @@ +--- +role: validator +deliverable: validation_results +tools: [terraform_validate, terraform_plan, terraform_schema, terraform_module] +budget: 30 +includes: [specialist-protocol] +--- +You produce the **validation results** Deliverable: the Skill's pre-deployment validation, done statically without provisioning anything. + +- Run the deployment dry-run with your tools: validate the Terraform, and preview it with a plan when you have permission to read live cloud resources. The tools already hold the submitted files, so pass them no files. +- Give a verdict on every Check in the Target architecture, from the infrastructure code: pass, fail or not verifiable, each with the evidence you read. The Checks are the whole bar: judge the code against them and nothing else. Judge each Check by its own words. A Check that says a role is granted or a setting is set passes when it is; other grants or settings beside it do not fail it unless the Check says "only" or "no other". What you think should also be true is a proposed addition, never a failure. +- Before you fail a Check because the code lacks a setting, confirm with `terraform_schema` that the resource type has that setting, when the tool is available. When it does not, the Check cannot be met by any code: give it not verifiable, with what the schema shows as the evidence. Give the same verdict to a Check that `implementation.json` records as unimplementable. +- When `terraform_modules` is true the code may call approved published modules. Then judge a Check on a resource the module creates from the module input that sets it: read the value in the code, and confirm with `terraform_module` what that input sets or what its default is. The modules Skill, when you have one, says how. +- Review the Target architecture's coverage once, completely. Go through every requirement and every design recommendation in turn; for each, list the conditions its text states and the Elements it applies to, and record a proposed addition for each one no Check verifies, naming the requirement or recommendation it serves. Report every gap in this pass: each later pass that finds one more costs a whole Revision of the design, the code and this validation. Propose nothing for what a requirement or recommendation lists under `outside_code`: that is application behaviour, an outcome measured in operation, or a process, and no Check on infrastructure code can verify it. Name those under your analysis heading as things to verify after deployment. A proposed addition is not a failure of the code. +- When `feedback` or your earlier verdicts show the Target architecture was revised for your proposed additions, propose only what the revision still leaves uncovered. Never propose what a Check already verifies in other words. +- Record your verdicts with `verdict_put`, a few Checks per call, as you reach them: the Checks of one Element, then the next. Record the dry-run's result and each proposed addition the same way. Short calls are what keep your replies from timing out, and what you record is kept if your run is cut short. `verdict_read` shows which Checks still have none. +- When `working_copy` shows verdicts recorded, your last run was cut short on this same code: call `verdict_read` and carry on from there. +- Submit with your content and no attachments when every Check has a verdict: what you recorded is attached as `verdicts.json`, in the format the requirements-chain Skill gives. +- When `pre_approved` is `false`, confirm with the user before you submit, as every Specialist does: call `needs_input` with a summary of the verdicts and pass your content as `draft`. Your recorded verdicts are kept and attached when you submit afterwards. +- Give the exact commands for every check you couldn't run, for the user to run themselves. + +End each of your contract's sections with a pass or fail verdict. diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/app/main.py b/app/main.py new file mode 100644 index 0000000..2487b45 --- /dev/null +++ b/app/main.py @@ -0,0 +1,15 @@ +"""The solution architecture agent's entrypoint: `python -m app.main`.""" + +from pathlib import Path + +from execution_engine.main import serve + +from app.solution_architecture.assembly import workflow_for +from app.solution_architecture.workflow import WORKFLOW + +ROOT = Path(__file__).resolve().parents[1] # the agent's own folder + +if __name__ == "__main__": + # Parts of the Workflow depend on the settings and the provider bundle: the + # Terraform runner, the pillar advisors, whether published modules may be used. + serve(WORKFLOW, ROOT, build=workflow_for) diff --git a/app/solution_architecture/__init__.py b/app/solution_architecture/__init__.py new file mode 100644 index 0000000..0553f67 --- /dev/null +++ b/app/solution_architecture/__init__.py @@ -0,0 +1,7 @@ +"""Cloud solution architecture, as a Workflow on the Execution engine. + +Brought from the engine's own example of this subject +(`orchestration_engine/tests/reference_workflow`), itself taken from the reference +agent `gcp_solution_architecture_agent` at commit 8b397cd. This copy is the agent's; +the engine's stays as the test of its seam (the engine's ADR-0001). +""" diff --git a/app/solution_architecture/assembly.py b/app/solution_architecture/assembly.py new file mode 100644 index 0000000..503bd04 --- /dev/null +++ b/app/solution_architecture/assembly.py @@ -0,0 +1,86 @@ +"""The Reference's Workflow for one deployment: its settings and its provider bundle. + +In the Reference this is the body of `open_assembly` in `app/agent.py`: the +Terraform runner, the local tools built on it, and the reviews of a design before +it is submitted. +""" + +from __future__ import annotations + +import dataclasses +from typing import Any + +from execution_engine.adk.runtime import SubmissionReview +from execution_engine.tools.jev import JevDecider +from execution_engine.workflows.workflow import Assembling, LocalToolBuilder, Workflow + +from app.solution_architecture.coverage import CoverageReview +from app.solution_architecture.design_review import DesignCoverageReview +from app.solution_architecture.hooks import ( + COVERAGE_REVIEWER, + MODULES_OPTION, + consultations, + modules_option, + pillar_hints, +) +from app.solution_architecture.local import TerraformRunner, local_tools +from app.solution_architecture.requirements_review import RequirementsReview +from app.solution_architecture.schema_review import Reviews, SchemaReview +from app.solution_architecture.workflow import WORKFLOW + + +def _runner(given: Assembling) -> TerraformRunner: + settings, bundle = given.settings, given.bundle + return TerraformRunner( + binary=settings.TERRAFORM_BINARY, + timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS, + plugin_cache_dir=settings.terraform_plugin_cache(), + providers=bundle.terraform_providers, + module_namespaces=bundle.terraform_module_namespaces, + ) + + +def local(given: Assembling) -> LocalToolBuilder: + runner = _runner(given) + offered = [name for names in given.bundle.tools.values() for name in names] + return lambda working_copy: local_tools(offered, runner, working_copy) + + +def reviews(given: Assembling) -> SubmissionReview | None: + """What is looked at in a design before it is submitted. Each raises what it + finds once and never blocks.""" + settings, bundle, decider = given.settings, given.bundle, given.decider + found: list[SubmissionReview] = [] + if bundle.terraform_providers: + # In code: every setting a Check names exists on its resource type. + found.append(SchemaReview(_runner(given))) + if settings.JEV_REQUIREMENTS_REVIEW and isinstance(decider, JevDecider): + # Optional, and off by default: Jev says whether a requirement names a product. + found.append( + RequirementsReview(decider, act=settings.JEV_REQUIREMENTS_THRESHOLD) + ) + if settings.DESIGN_COVERAGE_REVIEW and COVERAGE_REVIEWER in given.roles: + # A model reads the requirements against the Checks, once, before the + # design is approved: the reading the validator would make after the code. + found.append( + DesignCoverageReview(given.runtime, given.roles[COVERAGE_REVIEWER]) + ) + if settings.JEV_COVERAGE_REVIEW and isinstance(decider, JevDecider): + # Optional, and off by default: Jev says which Check verifies each condition. + found.append(CoverageReview(decider, none_at=settings.JEV_COVERAGE_THRESHOLD)) + return Reviews(found) if found else None + + +def workflow_for(settings: Any, bundle: Any) -> Workflow: + return dataclasses.replace( + WORKFLOW, + role_tools=consultations(bundle.pillar_skills), + task_hints=pillar_hints(settings.JEV_PILLAR_THRESHOLD), + options={ + MODULES_OPTION: modules_option( + bool(bundle.terraform_module_namespaces), settings.TERRAFORM_MODULES + ) + }, + local_tools=local, + reviews=reviews, + ) diff --git a/app/solution_architecture/assessment.py b/app/solution_architecture/assessment.py new file mode 100644 index 0000000..31bf1d7 --- /dev/null +++ b/app/solution_architecture/assessment.py @@ -0,0 +1,81 @@ +"""Every Execution judged as it ends (ADR-0007, iteration 5 step 19). + +The evaluation scores benchmark cases. This asks the same graded questions of a live +Execution's design recommendations when it ends, and keeps the answers with its +record. It reports; it never stops or changes an Execution. + +Without a decision an Execution carries no assessment. +""" + +from __future__ import annotations + +import logging +from collections.abc import Mapping +from typing import Any + +from execution_engine.adk.runtime import Decider, Question + +logger = logging.getLogger(__name__) + +GRADES = ("not at all", "weakly", "mostly", "fully") +QUALITY_BAR = 0.67 # mean of the graded rubric: "mostly" or better +QUALITY_RUBRIC: Mapping[str, str] = { + "specific": "Are the recommendations specific to this workload and its stated " + "requirements, as opposed to generic best practice that would fit any workload?", + "actionable": "Does each recommendation name the concrete setting, feature or " + "configuration to apply, so an engineer could act on it without more research?", + "trade_offs": "Where pillars pull in different directions (for example cost " + "against reliability), is the trade-off named and a resolution recommended?", + "traceable": "Can each recommendation be traced to a requirement or constraint " + "of the workload?", +} +_JUDGED = "design_recommendations" + + +def checklist_question(pillar: str, item: str) -> str: + """Whether the recommendations account for one item of a pillar's checklist. + + An item is accounted for in three ways. The third matters: a customer's request + seldom says enough to settle every item, and what it leaves unsaid is a + question for them, not a fault in the design (the owner, 2026-10-10). + """ + return ( + f"Do the recommendations account for this {pillar} checklist item in any " + "of these ways: by recommending it, by explaining why it does not apply, " + "or by recording it as something to confirm with the customer? " + f"{item}" + ) + + +async def assess( + decider: Decider, + deliverables: Mapping[str, Mapping[str, Any]], + *, + scope: str = "", +) -> dict[str, Any] | None: + """The rubric's scores for the design recommendations, each from 0 to 1, with + their mean and whether it meets the bar. None when there is nothing to judge or + no decision.""" + document = str((deliverables.get(_JUDGED) or {}).get("content", "")) + if not document.strip(): + return None + answers = await decider.decide( + document, + {key: Question("score", text, GRADES) for key, text in QUALITY_RUBRIC.items()}, + scope=scope, + ) + if answers is None: + return None + top = len(GRADES) - 1 + scores = { + key: round(min(1.0, max(0.0, float(answers[key].value) / top)), 2) + for key in QUALITY_RUBRIC + } + mean = round(sum(scores.values()) / len(scores), 2) + if mean < QUALITY_BAR: + logger.warning("[%s] design recommendations judged at %.2f", scope, mean) + return { + "recommendations_quality": scores, + "mean": mean, + "meets_bar": mean >= QUALITY_BAR, + } diff --git a/app/solution_architecture/chain.py b/app/solution_architecture/chain.py new file mode 100644 index 0000000..80c4257 --- /dev/null +++ b/app/solution_architecture/chain.py @@ -0,0 +1,546 @@ +"""The data files along the Requirements chain, and what each must hold (ADR-0005). + + requirements.json requirements with ids + components.json components, and the requirements each serves + products.json the product selected for each component + recommendations.json design recommendations with ids + target-architecture.json the graph (see target_architecture.py) + implementation.json which code satisfies each Check + verdicts.json the validation verdict on each Check + +Each checker returns what is wrong, one entry per fault, so a Specialist can fix it +and submit again. `upstream` is the Deliverables a submission builds on, by kind; a +link to one of them is checked only when it is there. +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping, Sequence +from typing import Any + +from app.solution_architecture.target_architecture import ( + GRAPH_ATTACHMENT, + GraphError, + TargetArchitecture, + chain_gaps, + parse_graph, +) + +REQUIREMENTS_FILE = "requirements.json" +COMPONENTS_FILE = "components.json" +PRODUCTS_FILE = "products.json" +RECOMMENDATIONS_FILE = "recommendations.json" +IMPLEMENTATION_FILE = "implementation.json" +VERDICTS_FILE = "verdicts.json" +SCOPE_FILE = "scope.yaml" # the completed scope spec +SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it + +REQUIREMENT_KINDS = ("functional", "non_functional") +VERDICTS = ("pass", "fail", "not_verifiable") +DRY_RUN_VERDICTS = ("pass", "fail", "not_run") + +Upstream = Mapping[str, Mapping[str, Any]] + + +def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]: + """An upstream data file as a list of objects; empty when absent or unreadable. + + An entry a Change request marked removed is left out: it stays in the file as + the record of what was dropped, and asks nothing of what follows. + """ + text = ((upstream or {}).get(kind) or {}).get("attachments", {}).get(name, "") + try: + data = json.loads(text) + except ValueError: + return [] + return ( + [ + item + for item in data + if isinstance(item, dict) and item.get("change") != "removed" + ] + if isinstance(data, list) + else [] + ) + + +def read_graph(upstream: Upstream | None) -> TargetArchitecture | None: + text = ( + ((upstream or {}).get("target_architecture") or {}) + .get("attachments", {}) + .get(GRAPH_ATTACHMENT, "") + ) + try: + return parse_graph(text) + except GraphError: + return None + + +def graph_structure(upstream: Upstream | None) -> str | None: + """The Target architecture's Elements and Relationships, as one comparable value. + + What a Deliverable written from the shape of the design, and not from its + Checks, was written from. None when there is no readable graph. + """ + graph = read_graph(upstream) + if graph is None: + return None + return json.dumps( + { + "elements": [ + [e.id, e.name, e.product, e.resource_type, e.component] + for e in graph.elements + ], + "relationships": [ + [r.id, r.source, r.target, r.kind] for r in graph.relationships + ], + }, + sort_keys=True, + ) + + +def _objects( + text: str, name: str, strings: Sequence[str], lists: Sequence[str] = () +) -> tuple[list[dict[str, Any]], list[str]]: + """The file's objects that have every required field, and what is wrong with it.""" + try: + data = json.loads(text) + except ValueError as exc: + return [], [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, list): + return [], [f"{name}: must be a JSON list"] + accepted, problems = [], [] + for index, item in enumerate(data): + where = f"{name}[{index}]" + if not isinstance(item, dict): + problems.append(f"{where}: must be an object") + continue + missing = [ + field + for field in strings + if not isinstance(item.get(field), str) or not item[field].strip() + ] + missing += [ + field + for field in lists + if not isinstance(item.get(field), list) + or not all(isinstance(value, str) for value in item[field]) + ] + if missing: + problems.append(f"{where}: needs {', '.join(missing)}") + continue + accepted.append(item) + return accepted, problems + + +def _repeated( + items: Sequence[Mapping[str, Any]], name: str, key: str = "id" +) -> list[str]: + seen: set[str] = set() + problems = [] + for item in items: + if item[key] in seen: + problems.append(f"{name}: {key} {item[key]} is used more than once") + seen.add(item[key]) + return problems + + +def conditions_of(item: Mapping[str, Any]) -> tuple[str, ...]: + """The separate things a requirement or recommendation asks for. + + Each is one statement that a Check can verify on its own. An item written before + conditions were listed is read as one condition: its whole text. + """ + listed = item.get("conditions") + if isinstance(listed, list): + conditions = tuple( + c.strip() for c in listed if isinstance(c, str) and c.strip() + ) + if conditions: + return conditions + text = item.get("text") + return (text.strip(),) if isinstance(text, str) and text.strip() else () + + +OUTSIDE_CODE = "outside_code" + + +def outside_code_of(item: Mapping[str, Any]) -> tuple[str, ...]: + """What a requirement asks for that infrastructure code cannot show: an outcome + measured in operation, application behaviour, or a process people follow.""" + listed = item.get(OUTSIDE_CODE) + if not isinstance(listed, list): + return () + return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip()) + + +def _lacking_conditions(items: Sequence[Mapping[str, Any]], name: str) -> list[str]: + """A constraint must say, one by one, what would have to be true for it to be met: + under `conditions` what infrastructure code can show, under `outside_code` what + it cannot. At least one of the two has an entry.""" + problems = [] + for item in items: + listed = item.get("conditions") + outside = item.get(OUTSIDE_CODE, []) + well_formed = all( + isinstance(group, list) + and all(isinstance(c, str) and c.strip() for c in group) + for group in (listed, outside) + ) + if not well_formed or not (listed or outside): + problems.append( + f"{name}: {item['id']} needs `conditions`: a list with one entry " + "for each separate thing it asks for that infrastructure code can " + f"show (and `{OUTSIDE_CODE}` for what it cannot)" + ) + return problems + + +def check_requirements( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = REQUIREMENTS_FILE + items, problems = _objects(attachments[name], name, ("id", "kind", "text")) + problems += _repeated(items, name) + problems += [ + f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}" + for item in items + if item["kind"] not in REQUIREMENT_KINDS + ] + if not items and not problems: + problems.append(f"{name}: lists no requirements") + problems += _lacking_conditions( + [item for item in items if item["kind"] == "non_functional"], name + ) + problems += _carries_the_scope(items, name, upstream) + return problems + + +def agreed_scope(upstream: Upstream | None) -> dict[str, Any]: + """The agreed scope, as every Specialist reads it; empty when there is none.""" + text = ( + ((upstream or {}).get("scope") or {}) + .get("attachments", {}) + .get(SCOPE_DATA_FILE, "") + ) + try: + data = json.loads(text) if text else {} + except ValueError: + return {} + return data if isinstance(data, dict) else {} + + +def sources_of(item: Mapping[str, Any]) -> tuple[str, ...]: + """What a requirement comes from: the customer's own requirement ids and the + scope spec's fields, as its `from` lists them.""" + listed = item.get("from") + return tuple(str(s) for s in listed) if isinstance(listed, list) else () + + +def _carries_the_scope( + items: Sequence[Mapping[str, Any]], name: str, upstream: Upstream | None +) -> list[str]: + """What the customer stated has to reach the requirements, by name (ADR-0008). + + Each requirement the customer wrote, and each choice they stated that a design + must honour, is named in the `from` of a requirement. A choice is carried by a + non-functional requirement with a condition, so the Target architecture owes it + a Check. Before this a stated topology could be named in a design and not built: + case 08 on 2026-10-11 passed all 101 Checks with no Check asking for it. + """ + scope = agreed_scope(upstream) + if not scope: + return [] + stated = scope.get("stated") or {} + theirs = [ + str(entry.get("id")) + for entry in ((stated.get("intent") or {}).get("requirements") or []) + if isinstance(entry, Mapping) and entry.get("id") + ] + binding = [str(path) for path in scope.get("binding") or []] + cited = {source for item in items for source in sources_of(item)} + problems = [ + f"{name}: the customer's requirement {reference} is covered by no " + "requirement; name it in the `from` of the one that covers it" + for reference in theirs + if reference not in cited + ] + problems += [ + f"{name}: the customer stated {path} and no requirement carries it; add a " + f"non-functional requirement whose `from` names {path}, with the condition " + "that shows it was honoured" + for path in binding + if path not in cited + ] + for item in items: + carried = [source for source in sources_of(item) if source in binding] + if carried and ( + item.get("kind") != "non_functional" or not conditions_of_listed(item) + ): + problems.append( + f"{name}: {item.get('id')} carries {', '.join(carried)}, a choice " + "the customer stated; it must be non_functional with at least one " + "entry in `conditions`, so the design is checked against it" + ) + return problems + + +def conditions_of_listed(item: Mapping[str, Any]) -> tuple[str, ...]: + """The conditions a requirement lists outright, with no fallback to its text.""" + listed = item.get("conditions") + if not isinstance(listed, list): + return () + return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip()) + + +def check_components( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = COMPONENTS_FILE + items, problems = _objects( + attachments[name], name, ("id", "name"), ("requirements",) + ) + problems += _repeated(items, name) + if not items and not problems: + problems.append(f"{name}: lists no components") + requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE) + if requirements: + known = {item["id"] for item in requirements} + served: set[str] = set() + for item in items: + served.update(item["requirements"]) + problems += [ + f"{name}: {item['id']} serves {reference}, which is not a requirement" + for reference in item["requirements"] + if reference not in known + ] + problems += [ + f"{name}: functional requirement {item['id']} is served by no component" + for item in requirements + if item.get("kind") == "functional" and item["id"] not in served + ] + return problems + + +def check_products( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = PRODUCTS_FILE + items, problems = _objects(attachments[name], name, ("component", "product")) + components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE) + if components: + known = {item["id"] for item in components} + chosen = {item["component"] for item in items} + problems += [ + f"{name}: {item['component']} is not a component" + for item in items + if item["component"] not in known + ] + problems += [ + f"{name}: component {identifier} has no product selected" + for identifier in sorted(known - chosen) + ] + return problems + + +def check_recommendations( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = RECOMMENDATIONS_FILE + items, problems = _objects( + attachments[name], name, ("id", "pillar", "text"), ("components",) + ) + problems += _repeated(items, name) + if not items and not problems: + problems.append(f"{name}: lists no recommendations") + problems += _lacking_conditions(items, name) + components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE) + if components: + known = {item["id"] for item in components} + problems += [ + f"{name}: {item['id']} names {reference}, which is not a component" + for item in items + for reference in item["components"] + if reference not in known + ] + return problems + + +def check_target_architecture( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + try: + graph = parse_graph(attachments[GRAPH_ATTACHMENT]) + except GraphError as exc: + return list(exc.problems) + if upstream is None: + return [] + return list( + chain_gaps( + graph, + requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE), + components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE), + products=read_list(upstream, "product_selection", PRODUCTS_FILE), + recommendations=read_list( + upstream, "design_recommendations", RECOMMENDATIONS_FILE + ), + ) + ) + + +def _covers_every_check( + items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None +) -> list[str]: + problems = _repeated(items, name, "check") + if graph is None: + return problems + given = {item["check"] for item in items} + problems += [ + f"{name}: {identifier} is not a Check in the Target architecture" + for identifier in sorted(given - set(graph.check_ids)) + ] + problems += [ + f"{name}: Check {identifier} is not accounted for" + for identifier in graph.check_ids + if identifier not in given + ] + return problems + + +def _split_implementation(text: str, name: str) -> tuple[str, str]: + """The entries that say where a Check is met, and those that say it cannot be.""" + try: + data = json.loads(text) + except ValueError: + return text, "[]" + if not isinstance(data, list): + return text, "[]" + cannot = [ + item for item in data if isinstance(item, dict) and "unimplementable" in item + ] + met = [item for item in data if item not in cannot] + return json.dumps(met), json.dumps(cannot) + + +def check_scope(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]: + """The scope a Specialist reads: what the customer stated, what was left to the + agent, and what is unknown.""" + name = SCOPE_DATA_FILE + try: + data = json.loads(attachments[name]) + except ValueError as exc: + return [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, dict) or not isinstance(data.get("stated"), dict): + return [f"{name}: must be an object with what the customer stated"] + return [] + + +def check_implementation( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = IMPLEMENTATION_FILE + met_text, cannot_text = _split_implementation(attachments[name], name) + met, problems = _objects(met_text, name, ("check", "file", "address")) + cannot, faults = _objects(cannot_text, name, ("check", "unimplementable")) + problems += faults + problems += _covers_every_check([*met, *cannot], name, read_graph(upstream)) + problems += [ + f"{name}: {item['check']} names {item['file']}, which is not attached" + for item in met + if item["file"] not in attachments + ] + return problems + + +def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]: + """The Checks the code's author found cannot be met as written, with the reason. + + Each is a fault in the Target architecture, not in the code: the Check names + something the resource does not have. + """ + _, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE) + cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable")) + return [ + {"check": item["check"], "reason": item["unimplementable"]} for item in cannot + ] + + +def check_verdicts( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = VERDICTS_FILE + try: + data = json.loads(attachments[name]) + except ValueError as exc: + return [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, dict): + return [ + f"{name}: must be an object with dry_run, checks and proposed_additions" + ] + problems: list[str] = [] + dry_run = data.get("dry_run") + if ( + not isinstance(dry_run, dict) + or dry_run.get("verdict") not in DRY_RUN_VERDICTS + or not isinstance(dry_run.get("evidence"), str) + or not dry_run["evidence"].strip() + ): + problems.append( + f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence" + ) + items, faults = _objects( + json.dumps(data.get("checks", [])), + f"{name}.checks", + ("check", "verdict", "evidence"), + ) + problems += faults + problems += [ + f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}" + for item in items + if item["verdict"] not in VERDICTS + ] + problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream)) + _, faults = _objects( + json.dumps(data.get("proposed_additions", [])), + f"{name}.proposed_additions", + ("statement", "applies_to", "reason"), + ) + return problems + faults + + +def validation_outcome(verdicts_text: str) -> dict[str, Any]: + """What a validation decided, for routing a Revision and for scoring. + + Failed Checks are faults in the code. A Check that could not be verified and a + proposed addition are gaps in the Target architecture. + """ + try: + data = json.loads(verdicts_text) + except ValueError: + data = {} + if not isinstance(data, dict): + data = {} + checks = [item for item in data.get("checks", []) if isinstance(item, dict)] + + def with_verdict(verdict: str) -> list[dict[str, Any]]: + return [ + {"check": item.get("check"), "evidence": item.get("evidence")} + for item in checks + if item.get("verdict") == verdict + ] + + dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {} + return { + "dry_run": dry_run, + "passed": [ + item.get("check") for item in checks if item.get("verdict") == "pass" + ], + "failed": with_verdict("fail"), + "not_verifiable": with_verdict("not_verifiable"), + "proposed_additions": [ + item + for item in data.get("proposed_additions", []) + if isinstance(item, dict) + ], + } diff --git a/app/solution_architecture/changes.py b/app/solution_architecture/changes.py new file mode 100644 index 0000000..de24871 --- /dev/null +++ b/app/solution_architecture/changes.py @@ -0,0 +1,326 @@ +"""What a Change request changed against its Baseline (ADR-0006). + +Ids are stable from one version of a Customer case's architecture to the next: a +requirement, component, recommendation, Element, Relationship or Check that still +holds keeps its id. That is what lets code, with no model, say what was added, what +changed and what was removed; trace from each changed requirement to everything it +reaches; and list apart anything that changed without being reached. Nobody asked +for those, so a reader should see them as such. + +This module is pure: data in, data out. +""" + +from __future__ import annotations + +import json +from collections.abc import Mapping, Sequence +from typing import Any + +from app.solution_architecture.chain import ( + COMPONENTS_FILE, + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, +) +from app.solution_architecture.target_architecture import GRAPH_ATTACHMENT + +CHANGES_FILE = "changes.json" +UNCHANGED, ADDED, CHANGED, REMOVED = "unchanged", "added", "changed", "removed" +CHANGE_KINDS = (UNCHANGED, ADDED, CHANGED, REMOVED) + +Deliverables = Mapping[str, Mapping[str, Any]] + + +def _items(deliverables: Deliverables | None, kind: str, name: str) -> list[dict]: + """A data file as a list of objects, removed requirements included.""" + text = ((deliverables or {}).get(kind) or {}).get("attachments", {}).get(name, "") + try: + data = json.loads(text) + except ValueError: + return [] + return ( + [item for item in data if isinstance(item, dict)] + if isinstance(data, list) + else [] + ) + + +def _graph(deliverables: Deliverables | None) -> dict[str, list[dict]]: + text = ( + ((deliverables or {}).get("target_architecture") or {}) + .get("attachments", {}) + .get(GRAPH_ATTACHMENT, "") + ) + try: + data = json.loads(text) + except ValueError: + data = {} + if not isinstance(data, dict): + data = {} + return { + key: [item for item in data.get(key, []) if isinstance(item, dict)] + for key in ("elements", "relationships", "checks") + } + + +# --- the requirements say what changed -------------------------------------------------- + + +def check_requirement_changes( + attachments: Mapping[str, str], baseline: Mapping[str, Any] | None +) -> list[str]: + """What is wrong with a Change request's requirements.json against the Baseline's. + + Every requirement carries a `change`. One that still holds keeps its id and is + `unchanged`, with its text as it was. One that differs is `changed`; one no + longer wanted stays in the list as `removed`; a new one takes a new id and is + `added`. Everything but `unchanged` says why. + """ + name = REQUIREMENTS_FILE + before = { + item["id"]: item + for item in _items({"requirements": baseline or {}}, "requirements", name) + if isinstance(item.get("id"), str) and item.get("change") != REMOVED + } + revised = _items( + {"requirements": {"attachments": attachments}}, "requirements", name + ) + problems: list[str] = [] + seen = set() + for item in revised: + identifier = item.get("id") + if not isinstance(identifier, str): + continue + seen.add(identifier) + change = item.get("change") + if change not in CHANGE_KINDS: + problems.append( + f"{name}: {identifier} needs a `change`: one of " + f"{', '.join(CHANGE_KINDS)}" + ) + continue + reason = item.get("reason") + if change != UNCHANGED and not (isinstance(reason, str) and reason.strip()): + problems.append(f"{name}: {identifier} is {change} and needs a `reason`") + if change == ADDED and identifier in before: + problems.append( + f"{name}: {identifier} is marked added, but the Baseline has that " + "id; a new requirement takes a new id" + ) + if change != ADDED and identifier not in before: + problems.append( + f"{name}: {identifier} is marked {change}, but the Baseline has no " + "such requirement; mark a new one added" + ) + if ( + change == UNCHANGED + and identifier in before + and _text(item) != _text(before[identifier]) + ): + problems.append( + f"{name}: {identifier} is marked unchanged, but its text differs " + "from the Baseline's; restore it or mark it changed" + ) + problems += [ + f"{name}: Baseline requirement {identifier} is missing; keep it, or keep it " + "marked removed with the reason" + for identifier in before + if identifier not in seen + ] + if revised and all(item.get("change") == UNCHANGED for item in revised): + problems.append( + f"{name}: nothing is marked added, changed or removed; a Change request " + "changes at least one requirement" + ) + return problems + + +def _text(item: Mapping[str, Any]) -> str: + return " ".join(str(item.get("text", "")).split()) + + +def requirement_changes(deliverables: Deliverables | None) -> list[dict[str, str]]: + """The requirements a Change request added, changed or removed, with the reason.""" + return [ + { + "id": str(item.get("id")), + "change": str(item["change"]), + "reason": str(item.get("reason", "")), + "text": str(item.get("text", "")), + } + for item in _items(deliverables, "requirements", REQUIREMENTS_FILE) + if item.get("change") in (ADDED, CHANGED, REMOVED) + ] + + +# --- comparing two versions ------------------------------------------------------------- + + +def _compare( + before: Sequence[Mapping[str, Any]], + after: Sequence[Mapping[str, Any]] | None, + key: str = "id", + ignore: Sequence[str] = ("change", "reason"), +) -> dict[str, list[str]]: + """Ids added, changed and removed between two lists of objects. + + `after` is None while the revised Deliverable has not been produced: nothing + has changed yet, which is not the same as everything having been removed. + """ + if after is None: + return {ADDED: [], CHANGED: [], REMOVED: []} + + def body(item: Mapping[str, Any]) -> dict[str, Any]: + return {name: value for name, value in item.items() if name not in ignore} + + old = {str(item.get(key)): body(item) for item in before if item.get(key)} + new = {str(item.get(key)): body(item) for item in after if item.get(key)} + return { + ADDED: [identifier for identifier in new if identifier not in old], + CHANGED: [ + identifier + for identifier in new + if identifier in old and new[identifier] != old[identifier] + ], + REMOVED: [identifier for identifier in old if identifier not in new], + } + + +def reach( + changed: Sequence[str], + components: Sequence[Mapping[str, Any]], + recommendations_changed: Sequence[str], + graph: Mapping[str, Sequence[Mapping[str, Any]]], +) -> set[str]: + """The Elements, Relationships and Checks a set of changed requirements reaches. + + A changed requirement reaches the components that serve it, the Elements that + realise those components, the Relationships at those Elements, and every Check + on any of them or with the requirement as its source. A recommendation that + changed reaches the Checks that come from it and what they apply to. + """ + sources = set(changed) | set(recommendations_changed) + served = { + str(component.get("id")) + for component in components + if set(component.get("requirements") or ()) & set(changed) + } + reached = { + str(element.get("id")) + for element in graph.get("elements", ()) + if element.get("component") in served + } + for check in graph.get("checks", ()): + if check.get("source") in sources: + reached.add(str(check.get("id"))) + reached.add(str(check.get("applies_to"))) + reached |= { + str(relationship.get("id")) + for relationship in graph.get("relationships", ()) + if relationship.get("from") in reached or relationship.get("to") in reached + } + reached |= { + str(check.get("id")) + for check in graph.get("checks", ()) + if check.get("applies_to") in reached + } + return reached + + +def change_summary( + baseline: Deliverables | None, current: Deliverables | None +) -> dict[str, Any]: + """What a Change request changed, as changes.json holds it. + + Requirements carry their own account. Everything else is compared by id. What + changed inside the reach of the changed requirements is listed as requested; + anything else that changed is listed apart as unrequested. + """ + requirements = requirement_changes(current) + changed_ids = [item["id"] for item in requirements] + produced = current or {} + recommendations = _compare( + _items(baseline, "design_recommendations", RECOMMENDATIONS_FILE), + _items(current, "design_recommendations", RECOMMENDATIONS_FILE) + if "design_recommendations" in produced + else None, + ) + components = _compare( + _items(baseline, "technical_decomposition", COMPONENTS_FILE), + _items(current, "technical_decomposition", COMPONENTS_FILE) + if "technical_decomposition" in produced + else None, + ) + old_graph, new_graph = _graph(baseline), _graph(current) + designed = "target_architecture" in produced + # Reach is traced through both versions: what a requirement used to touch can + # change or go, as well as what it touches now. + touched_recommendations = recommendations[ADDED] + recommendations[CHANGED] + reached = reach( + changed_ids, + _items(current, "technical_decomposition", COMPONENTS_FILE), + touched_recommendations, + new_graph, + ) | reach( + changed_ids, + _items(baseline, "technical_decomposition", COMPONENTS_FILE), + touched_recommendations + recommendations[REMOVED], + old_graph, + ) + graph: dict[str, dict[str, list[str]]] = {} + unrequested: dict[str, list[str]] = {} + for part in ("elements", "relationships", "checks"): + compared = _compare(old_graph[part], new_graph[part] if designed else None) + graph[part] = compared + outside = [ + identifier + for change in (ADDED, CHANGED, REMOVED) + for identifier in compared[change] + if identifier not in reached + ] + if outside: + unrequested[part] = outside + return { + "requirements": requirements, + "components": components, + "recommendations": recommendations, + **graph, + # Changed without being reached by any changed requirement. + "unrequested": unrequested, + } + + +def is_empty(summary: Mapping[str, Any]) -> bool: + return not summary.get("requirements") and not any( + summary.get(part, {}).get(change) + for part in ( + "components", + "recommendations", + "elements", + "relationships", + "checks", + ) + for change in (ADDED, CHANGED, REMOVED) + ) + + +# What an Approval of each kind of Deliverable shows of the change. +_SHOWN_WITH = { + "requirements": ("requirements",), + "technical_decomposition": ("components",), + "design_recommendations": ("recommendations",), + "target_architecture": ("elements", "relationships", "checks", "unrequested"), +} + + +def changes_for(summary: Mapping[str, Any], kinds: Sequence[str]) -> dict[str, Any]: + """The part of a change summary that belongs to the Deliverables being approved, + with the parts that hold nothing left out.""" + shown: dict[str, Any] = {} + for kind in kinds: + for part in _SHOWN_WITH.get(kind, ()): + value = summary.get(part) + if isinstance(value, Mapping): + value = {name: ids for name, ids in value.items() if ids} + if value: + shown[part] = value + return shown diff --git a/app/solution_architecture/coverage.py b/app/solution_architecture/coverage.py new file mode 100644 index 0000000..c20c8c6 --- /dev/null +++ b/app/solution_architecture/coverage.py @@ -0,0 +1,171 @@ +"""A review of the Target architecture's coverage, before it is submitted. + +The structural check knows that every non-functional requirement and every design +recommendation is the source of a Check. It cannot know whether those Checks verify +everything the text asks for: a requirement with three conditions and a Check for one +passes it. The validator finds the rest later, a few at a time, and each finding +costs a Revision of the design, the code and the validation. + +Requirements and recommendations list their conditions one by one. For each +condition this asks the decider (ADR-0007) which of the source's Checks verifies it, +with "none" as an answer. A condition answered "none" is raised. + +Two things make the question answerable, found by measurement on 2026-10-07 (see +.agents/plans/iter-05-jev-decisions/steps/step-4.md). It is about one explicit +condition, not a whole requirement; and it is a choice among the Checks, not a yes or +no. Asked the broad way, a complete design and an incomplete one scored alike. + +It never blocks: with no decision, the submission stands on its structure. +""" + +from __future__ import annotations + +import logging +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import Decider, Question + +from app.solution_architecture.chain import ( + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + Upstream, + conditions_of, + read_list, +) +from app.solution_architecture.kinds import DeliverableKind +from app.solution_architecture.target_architecture import ( + GRAPH_ATTACHMENT, + Check, + GraphError, + TargetArchitecture, + parse_graph, +) + +logger = logging.getLogger(__name__) + +NONE = "none" + + +def _described(graph: TargetArchitecture) -> str: + lines = ["Elements of the Target architecture:"] + lines += [ + f"- {e.id} {e.name} ({e.product}, {e.resource_type})" + + (f", realises component {e.component}" if e.component else "") + for e in graph.elements + ] + lines.append("Relationships:") + lines += [f"- {r.id}: {r.source} {r.kind} {r.target}" for r in graph.relationships] + return "\n".join(lines) + + +def _constraints(upstream: Upstream, graph: TargetArchitecture) -> list[dict[str, Any]]: + """What must be covered: every non-functional requirement, and every design + recommendation that applies.""" + excused = {item.recommendation for item in graph.not_applicable} + return [ + item + for item in read_list(upstream, "requirements", REQUIREMENTS_FILE) + if item.get("kind") == "non_functional" + ] + [ + item + for item in read_list(upstream, "design_recommendations", RECOMMENDATIONS_FILE) + if item.get("id") not in excused + ] + + +def coverage_questions( + graph: TargetArchitecture, constraints: Sequence[Mapping[str, Any]] +) -> dict[str, tuple[str, str, Question]]: + """One question per condition: (source id, the condition, the question). + + A source with no Check is the structural check's to report, so it is not asked + about here. + """ + names = {element.id: element.name for element in graph.elements} + names.update( + { + r.id: f"{names[r.source]} {r.kind} {names[r.target]}" + for r in graph.relationships + } + ) + by_source: dict[str, list[Check]] = {} + for check in graph.checks: + by_source.setdefault(check.source, []).append(check) + + questions: dict[str, tuple[str, str, Question]] = {} + for item in constraints: + source = item.get("id") + checks = by_source.get(source, []) if isinstance(source, str) else [] + if not checks: + continue + listed = "\n".join( + f"- {check.id} on {names[check.applies_to]}: {check.statement}" + for check in checks + ) + for number, condition in enumerate(conditions_of(item), start=1): + questions[f"{source}#{number}"] = ( + str(source), + condition, + Question( + "choice", + f'Condition: "{condition}".\nChecks:\n{listed}\n' + "Which one Check verifies this condition? Answer none when " + "no Check does.", + (*(check.id for check in checks), NONE), + ), + ) + return questions + + +class CoverageReview: + def __init__(self, decider: Decider, *, none_at: float = 0.6) -> None: + self._decider = decider + # How likely "none" must be before a condition is raised. Below it the + # answer is too uncertain to send work back on. + self._none_at = none_at + + async def __call__( + self, + kind: DeliverableKind, + attachments: Mapping[str, str], + upstream: Upstream | None, + scope: str = "", + ) -> Sequence[str]: + """The conditions no Check appears to verify, each as a line for the + Specialist. Empty when coverage looks complete or was not judged.""" + if kind != DeliverableKind.TARGET_ARCHITECTURE or not upstream: + return () + try: + graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, "")) + except GraphError: + return () + asked = coverage_questions(graph, _constraints(upstream, graph)) + if not asked: + return () + answers = await self._decider.decide( + _described(graph), + {key: question for key, (_, _, question) in asked.items()}, + scope=scope, + ) + if not answers: + return () + concerns = [] + for key, (source, condition, question) in asked.items(): + answer = answers.get(key) + if answer is None or answer.value != NONE: + continue + if answer.probabilities.get(NONE, answer.confidence) < self._none_at: + continue + checks = ", ".join(question.options[:-1]) + concerns.append( + f'{source}: no Check verifies "{condition}" (its Checks: {checks})' + ) + if concerns: + logger.info( + "[%s] coverage review raised %d of %d conditions", + scope, + len(concerns), + len(asked), + ) + return tuple(concerns) diff --git a/app/solution_architecture/design_review.py b/app/solution_architecture/design_review.py new file mode 100644 index 0000000..b05124c --- /dev/null +++ b/app/solution_architecture/design_review.py @@ -0,0 +1,156 @@ +"""A review of a design's coverage by a model, before anyone approves it. + +The validator reads the requirements and recommendations against the Checks and +proposes one for each condition nothing verifies. That reading needs no code, but it +used to happen only after the code was written: in the runs of 2026-10-09 it sent +the Target architecture back in four of seven, each time costing a Revision of the +design, the code and the validation (iteration 6 step 12). + +This is the same reading, made when the Target architecture is first submitted and +returned to its author. It is a review like the others: what it raises is returned +once and never blocks, and when it fails the submission stands. + +It runs once in an Execution. A Revision is asked for by the validator or the user, +who have just read the design; reviewing it again would pay for the same reading. +""" + +from __future__ import annotations + +import json +import logging +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import ( + AgentRuntime, + AgentTask, + RoleSpec, + Submitted, + ToolResult, + ToolSpec, +) + +from app.solution_architecture.chain import ( + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + Upstream, + read_list, +) +from app.solution_architecture.kinds import DeliverableKind +from app.solution_architecture.target_architecture import ( + GRAPH_ATTACHMENT, + GraphError, + parse_graph, +) + +logger = logging.getLogger(__name__) + +MAX_GAPS = 12 + + +class DesignCoverageReview: + def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None: + self._runtime = runtime + self._role = role + self._reviewed: set[str] = set() + + async def __call__( + self, + kind: DeliverableKind, + attachments: Mapping[str, str], + upstream: Upstream | None, + scope: str = "", + ) -> Sequence[str]: + """The conditions the reviewer finds no Check verifies, each as a line for + the target architect. Empty when it finds none or could not review.""" + if kind != DeliverableKind.TARGET_ARCHITECTURE or not upstream: + return () + text = attachments.get(GRAPH_ATTACHMENT, "") + try: + graph = parse_graph(text) + except GraphError: + return () + if scope in self._reviewed: + return () + self._reviewed.add(scope) + + constraints = [ + item + for item in read_list(upstream, "requirements", REQUIREMENTS_FILE) + if item.get("kind") == "non_functional" + ] + read_list(upstream, "design_recommendations", RECOMMENDATIONS_FILE) + known = {str(item.get("id")) for item in constraints} + applies_to = {element.id for element in graph.elements} | { + relationship.id for relationship in graph.relationships + } + + async def report_gaps(gaps: Any = None) -> ToolResult: + if not isinstance(gaps, list): + return ToolResult("Not recorded: `gaps` is a list; empty when none.") + return ToolResult("Recorded.", Submitted(json.dumps(gaps))) + + tool = ToolSpec( + "report_gaps", + "Give every gap you found, in one call. An empty list when the Checks " + "verify every condition. Ends your turn.", + { + "type": "object", + "properties": { + "gaps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": "The requirement or recommendation id", + }, + "applies_to": { + "type": "string", + "description": "The Element or Relationship id", + }, + "statement": { + "type": "string", + "description": "The Check that is missing", + }, + }, + "required": ["source", "applies_to", "statement"], + }, + } + }, + "required": ["gaps"], + }, + report_gaps, + tier="execution", + ) + task = AgentTask( + role=self._role.name, + prompt="Review whether the Target architecture's Checks verify every " + "condition of the requirements and recommendations.", + context={ + "constraints": constraints, + "target_architecture": json.loads(text), + }, + ) + outcome = await self._runtime.run(self._role, task, [tool]) + if not isinstance(outcome, Submitted): + logger.info("[%s] design coverage review gave no answer", scope) + return () + try: + reported = json.loads(outcome.content) + except ValueError: + return () + concerns = [] + for gap in reported if isinstance(reported, list) else []: + if not isinstance(gap, Mapping): + continue + source, where = str(gap.get("source", "")), str(gap.get("applies_to", "")) + statement = " ".join(str(gap.get("statement", "")).split()) + # A gap must be about something that exists: an invented id is dropped. + if source not in known or where not in applies_to or not statement: + continue + concerns.append(f"{source}: no Check verifies this on {where}: {statement}") + logger.info( + "[%s] design coverage review raised %d gap(s)", scope, len(concerns) + ) + return tuple(concerns[:MAX_GAPS]) diff --git a/app/solution_architecture/hooks.py b/app/solution_architecture/hooks.py new file mode 100644 index 0000000..53e03a8 --- /dev/null +++ b/app/solution_architecture/hooks.py @@ -0,0 +1,482 @@ +"""Where the Reference's own code runs inside the engine. + +In the Reference these are branches inside its engine: `app/tools/execution.py` adds +views to three Deliverables as they are submitted and adds to an Approval, +`app/tools/toolkit.py` gives the design advisor its pillar consultation, and +`app/adk/roles.py` gives the modules Skill to roles with the module tool. Here each +is a function the Workflow names. +""" + +from __future__ import annotations + +import dataclasses +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import Decider, RoleSpec, ToolSpec +from execution_engine.workflows.deliverables import GraphShape, ListShape, Upstream +from execution_engine.workflows.workflow import ( + Bench, + CardText, + ChangePolicy, + Hints, + OptionSpec, + RoleTools, +) + +from app.solution_architecture.chain import ( + IMPLEMENTATION_FILE, + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + read_graph, + read_list, + unimplementable_checks, +) +from app.solution_architecture.changes import ( + CHANGES_FILE, + change_summary, + changes_for, + is_empty, +) +from app.solution_architecture.changes import _graph as changes_graph +from app.solution_architecture.meaning import settle_meaning +from app.solution_architecture.modules import MODULE_TOOL, MODULES_OPTED_IN +from app.solution_architecture.pillars import ( + ADVICE_KEY, + QUESTIONS_HEADING, + REVIEW_HEADING, + customer_questions, + pillar_consultation_tool, + pillars_touched, + render_checklist_review, +) +from app.solution_architecture.presentation import ( + _describe_changes, + _describe_target_architecture, +) +from app.solution_architecture.target_architecture import ( + DIAGRAM_ATTACHMENT, + GRAPH_ATTACHMENT, + GraphError, + parse_graph, + render_mermaid, + render_tables, +) +from app.solution_architecture.work_breakdown import ( + DICTIONARY_HEADING, + TIMELINE_FILE, +) +from app.solution_architecture.work_breakdown import mermaid as plan_mermaid +from app.solution_architecture.work_breakdown import render as render_plan +from app.solution_architecture.work_breakdown import summary as plan_summary + +PILLAR_ADVISOR = "pillar-advisor" +COVERAGE_REVIEWER = "coverage-reviewer" # reviews a design before its Approval +DESIGN_RECOMMENDATIONS = "design_recommendations" +TARGET_ARCHITECTURE = "target_architecture" +WORK_BREAKDOWN = "work_breakdown" +MODULES_OPTION = "terraform_modules" +GUIDE_FILENAME = "solution-architecture-guide.md" +QUESTIONS_FILENAME = "customer-questions.md" # what to ask the customer + +# The Target architecture, as the Specialist builds it in its working copy. +GRAPH_SHAPE = GraphShape( + attachment=GRAPH_ATTACHMENT, + lists={ + "elements": ListShape( + ("id", "name", "product", "resource_type"), + optional=("component",), + label="Elements", + ), + "relationships": ListShape(("id", "from", "to", "kind"), label="Relationships"), + "checks": ListShape( + ("id", "applies_to", "statement", "source"), label="Checks" + ), + "not_applicable": ListShape(("recommendation", "reason"), key="recommendation"), + }, +) + + +def check_ids(upstream: Upstream | None) -> Sequence[str]: + graph = read_graph(upstream) + return graph.check_ids if graph else () + + +def with_checklist_review( + bench: Bench, content: str, attachments: dict[str, str] +) -> tuple[str, dict[str, str]]: + # The pillar advisors' checklist reviews, written from what they recorded. A + # Revision replaces the section, never stacks a second. + checklist_review = render_checklist_review(bench.working) + content = content.split(f"\n## {REVIEW_HEADING}")[0].rstrip() + "\n" + if checklist_review: + content += "\n" + checklist_review + return content, attachments + + +def with_plan_views( + bench: Bench, content: str, attachments: dict[str, str] +) -> tuple[str, dict[str, str]]: + # The dictionary, the sequence and the timeline are views of the plan, computed + # and written here: they cannot disagree with it. + views = render_plan(attachments, bench.upstream) + content = content.split(f"\n## {DICTIONARY_HEADING}")[0].rstrip() + "\n" + if views: + content += "\n" + views + chart = plan_mermaid(attachments, bench.upstream) + if chart: + attachments[TIMELINE_FILE] = chart + return content, attachments + + +def with_graph_views( + bench: Bench, content: str, attachments: dict[str, str] +) -> tuple[str, dict[str, str]]: + # The tables and the diagram are views of the graph, so code writes them: they + # cannot disagree with it. + graph = parse_graph(attachments[GRAPH_ATTACHMENT]) + content = content.rstrip() + "\n\n" + render_tables(graph) + attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph) + return content, attachments + + +def approval_details( + phase: str, + deliverables: Mapping[str, Mapping[str, Any]], + baseline: Mapping[str, Any] | None, + *, + in_phase: Sequence[str], + design_phase: str, +) -> dict[str, Any]: + details: dict[str, Any] = {} + if baseline: + # Worked out from the ids, not written by an agent: what this Phase's + # Deliverables add, change and remove against the Baseline. + details["changes"] = changes_for( + change_summary(baseline.get("deliverables"), deliverables), list(in_phase) + ) + target = deliverables.get(TARGET_ARCHITECTURE) + if target and phase == design_phase: + try: + graph = parse_graph(target.get("attachments", {})[GRAPH_ATTACHMENT]) + except (KeyError, GraphError): + return details + # What the user is approving before any code is written. + details["target_architecture"] = graph.summary() + return details + + +def consultations(pillar_skills: Mapping[str, str]): + """The design advisor's pillar consultation, for a bundle's pillar Skills.""" + + def role_tools(given: RoleTools) -> Sequence[ToolSpec]: + advisor = given.roles.get(PILLAR_ADVISOR) + if not ( + pillar_skills and advisor and given.deliverable == DESIGN_RECOMMENDATIONS + ): + return () + # Pillar advisors can't ask for permission, so they get general-tier tools only. + advisor_tools = [ + tool for tool in given.mcp_tools(advisor) if tool.tier == "general" + ] + return ( + pillar_consultation_tool( + given.runtime, + advisor, + pillar_skills, + extra_tools=advisor_tools, + memory=given.working, + limiter=given.limiter, + ), + ) + + return role_tools + + +def with_modules_skill( + roles: Mapping[str, RoleSpec], bundle: Any +) -> Mapping[str, RoleSpec]: + if not bundle.terraform_modules_skill: + return roles + return { + name: dataclasses.replace(role, modules_skill=bundle.terraform_modules_skill) + if MODULE_TOOL in role.tools + else role + for name, role in roles.items() + } + + +# --- what the router and the Execution's nodes read ------------------------------------ + + +def unimplementable(deliverables: Upstream) -> list[dict[str, str]]: + """Checks the code's author reported cannot be met as the design words them.""" + return unimplementable_checks( + (deliverables.get("deployment_guidance") or {}) + .get("attachments", {}) + .get(IMPLEMENTATION_FILE, "") + ) + + +def known_ids(deliverables: Upstream) -> set[str]: + return { + item["id"] + for name, kind in ( + (REQUIREMENTS_FILE, "requirements"), + (RECOMMENDATIONS_FILE, DESIGN_RECOMMENDATIONS), + ) + for item in read_list(deliverables, kind, name) + if "id" in item + } + + +def agreed(deliverables: Upstream) -> str: + return str( + (deliverables.get("requirements") or {}) + .get("attachments", {}) + .get(REQUIREMENTS_FILE, "") + ) + + +def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]: + facts: dict[str, Any] = {} + counts = { + "requirements": len(read_list(deliverables, "requirements", REQUIREMENTS_FILE)), + "recommendations": len( + read_list(deliverables, DESIGN_RECOMMENDATIONS, RECOMMENDATIONS_FILE) + ), + } + facts["counts"] = {name: count for name, count in counts.items() if count} + plan = deliverables.get(WORK_BREAKDOWN) + if plan and phase == "packaging": + # How long the build is planned to take, and whether that fits. + facts["delivery_plan"] = plan_summary(plan.get("attachments", {}), deliverables) + graph = read_graph(deliverables) + if graph is not None: + facts["target_architecture"] = graph.summary() + return facts + + +def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]: + lines = [] + counts = facts.get("counts") or {} + if counts: + lines.append( + ", ".join(f"{count} {name}" for name, count in counts.items()) + "." + ) + plan = facts.get("delivery_plan") + if plan: + fits = plan.get("within_window") + lines.append( + f"Delivery plan: {plan['activities']} activities in " + f"{plan['work_packages']} work packages, {plan['weeks']} weeks with a " + f"team of {plan['team_size']}" + + ( + "" + if fits is None + else f", {'inside' if fits else 'over'} the " + f"{plan['window_weeks']}-week window" + ) + + "." + ) + graph = facts.get("target_architecture") + if graph: + lines.append( + f"Target architecture: {graph['elements']} Elements, " + f"{graph['relationships']} Relationships, {graph['checks']} Checks." + ) + return lines + + +def changes_in_words(summary: Mapping[str, Any]) -> str: + return "\n".join( + f"Requirement {item['id']} {item['change']}: {item['text']} ({item['reason']})" + for item in summary["requirements"] + ) + + +async def settle( + decider: Decider, + summary: dict[str, Any], + before: Upstream | None, + after: Upstream, + *, + unchanged_at: float, + scope: str, +) -> dict[str, Any]: + return await settle_meaning( + decider, summary, before, after, unchanged_at=unchanged_at, scope=scope + ) + + +CHANGES = ChangePolicy( + file=CHANGES_FILE, + summary=change_summary, + is_empty=is_empty, + in_words=changes_in_words, + settle=settle, +) + + +def describe_design(deliverables: Upstream) -> str: + design = "\n".join( + f"- {item.get('name', item.get('id', ''))} ({item.get('product', '')}, " + f"{item.get('resource_type', '')})" + for item in changes_graph(deliverables)["elements"] + ) + return f"Elements of the Target architecture:\n{design}" if design else "" + + +def prepare_role(role: RoleSpec, task_input: Mapping[str, Any]) -> RoleSpec: + opted_in = bool(task_input.get(MODULES_OPTION)) + MODULES_OPTED_IN.set(opted_in) + if opted_in and role.modules_skill: + return dataclasses.replace(role, skills=(*role.skills, role.modules_skill)) + if MODULE_TOOL in role.tools: + # Plain resources: no modules Skill and no module lookup. + return dataclasses.replace( + role, tools=tuple(tool for tool in role.tools if tool != MODULE_TOOL) + ) + return role + + +def task_entries( + state: Mapping[str, Any], kind: str +) -> tuple[dict[str, Any], dict[str, Any]]: + # Whether this Execution opted into published Terraform modules. False: + # infrastructure code is plain resources. True: a published module may be used + # where the modules Skill says one fits. + opted_in = bool((state.get("options") or {}).get(MODULES_OPTION)) + return {MODULES_OPTION: opted_in}, { + MODULES_OPTION: opted_in, + # The pillars a change touches, when that could be judged: the design + # advisor consults those and keeps its earlier advice for the rest. + "pillars_to_consult": None, + } + + +def pillar_hints(threshold: float = 1.5): + """Which pillars the design advisor should consult again, when it is being + started on a Revision or a Change request and advice from before exists.""" + + async def task_hints(given: Hints) -> Mapping[str, Mapping[str, Any]]: + kind = DESIGN_RECOMMENDATIONS + if given.decider is None or kind not in given.started: + return {} + state = given.state + baseline = state.get("baseline") or {} + remembered = state.get("working", {}).get(kind, {}).get( + ADVICE_KEY + ) or baseline.get("working", {}).get(kind, {}).get(ADVICE_KEY) + if not remembered: + return {} # a first consultation: every pillar + change = "\n".join(given.feedback.get(kind, ())) or given.changed + chosen = await pillars_touched( + given.decider, + list(remembered), + change, + threshold=threshold, + scope=str(state["execution_id"]), + ) + # None: no decision, so no hint and every pillar. An empty list is an answer. + return {} if chosen is None else {kind: {"pillars_to_consult": chosen}} + + return task_hints + + +def outputs( + state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str] +) -> dict[str, Any]: + """The Reference's own files and manifest entries.""" + questions = customer_questions( + state.get("working", {}).get(DESIGN_RECOMMENDATIONS, {}) + ) + if questions: + # What the request did not say enough to settle, as questions to put to + # the customer. Missing information, not a fault in the design. + files[QUESTIONS_FILENAME] = "\n".join( + [ + f"# {QUESTIONS_HEADING}", + "", + ( + "The request did not say enough to settle these. Each answer " + "may change a recommendation." + ), + "", + *( + f"- **{item['pillar']}**, {item['item']} {item['question']}" + for item in questions + ), + "", + ] + ) + plan = deliverables.get(WORK_BREAKDOWN) + plan_record: dict[str, Any] | None = None + guide = GUIDE_FILENAME in files + if plan: + plan_record = plan_summary(plan.get("attachments", {}), deliverables) or None + timeline = str(plan.get("content", "")).partition("\n## Timeline\n")[2] + if guide and timeline: + # The guide and the plan are written side by side, so neither holds the + # other. The plan's timeline is added to the guide here, from the plan. + appendix = ( + "\n\n## Delivery plan\n\n" + f"From the work breakdown structure (`deliverables/" + f"{WORK_BREAKDOWN}.md`), which has the work " + "packages and the full activity sequence.\n\n" + timeline.strip() + "\n" + ) + files[GUIDE_FILENAME] = files[GUIDE_FILENAME].rstrip() + appendix + guide_document = "deliverables/solution_guide.md" + files[guide_document] = files[guide_document].rstrip() + appendix + return { + # Whether its infrastructure code was allowed published modules. + MODULES_OPTION: bool((state.get("options") or {}).get(MODULES_OPTION)), + # The plan in a few numbers: its length, and whether it fits the window. + "delivery_plan": plan_record, + "solution_guide": GUIDE_FILENAME if guide else None, + # Questions the request left open, for the customer; None when there are none. + "customer_questions": QUESTIONS_FILENAME if questions else None, + } + + +def modules_option(available: bool, default: bool) -> OptionSpec: + """Whether an Execution may use published Terraform modules: off unless the + deployment says otherwise, and refused when the provider approves no sources.""" + + def check(value: Any) -> str | None: + if not isinstance(value, bool): + return "terraform_modules must be true or false" + if value and not available: + return ( + "terraform_modules: this Cloud provider has no approved module sources" + ) + return None + + return OptionSpec( + default=default and available, + spec_field="run.terraform_modules", + check=check, + ) + + +def describe_approval(approval: Mapping[str, Any]) -> str: + return _describe_changes(approval) + _describe_target_architecture( + approval.get("target_architecture") + ) + + +CARD = CardText( + description=( + "Designs a cloud solution architecture with you: requirements discovery, " + "grounded product selection, diagram, design recommendations, " + "infrastructure-as-code and dry-run validation, packaged as a solution " + "guide." + ), + skill_id="solution-architecture", + skill_name="Cloud solution architecture", + tags=("architecture", "cloud", "terraform"), + examples=( + "Design a regional event ingestion platform on Google Cloud.", + "Migrate our on-premises order service to managed services.", + ), +) diff --git a/app/solution_architecture/kinds.py b/app/solution_architecture/kinds.py new file mode 100644 index 0000000..4ad0525 --- /dev/null +++ b/app/solution_architecture/kinds.py @@ -0,0 +1,35 @@ +"""The Reference's Phases and Deliverable kinds, from its `app/workflows/deliverables.py`.""" + +from __future__ import annotations + +from enum import StrEnum + + +class PhaseId(StrEnum): + # Scoping: what the customer wants and the facts a design depends on, agreed + # before requirements are derived from it (ADR-0008). + SCOPING = "scoping" + REQUIREMENTS_DISCOVERY = "requirements_discovery" + # Design: ends with the Target architecture, approved before any code is written. + SOLUTION_ARCHITECTURE = "solution_architecture" + SOLUTION_IMPLEMENTATION = "solution_implementation" + SOLUTION_VALIDATION = "solution_validation" + PACKAGING = "packaging" + + +PHASE_ORDER: tuple[PhaseId, ...] = tuple(PhaseId) + + +class DeliverableKind(StrEnum): + SCOPE = "scope" + REQUIREMENTS = "requirements" + TECHNICAL_DECOMPOSITION = "technical_decomposition" + PRODUCT_SELECTION = "product_selection" + DESIGN_RECOMMENDATIONS = "design_recommendations" + TARGET_ARCHITECTURE = "target_architecture" + ARCHITECTURE_DESCRIPTION = "architecture_description" + DEPLOYMENT_GUIDANCE = "deployment_guidance" + VALIDATION_RESULTS = "validation_results" + # The plan for building what was designed and validated (iteration 10). + WORK_BREAKDOWN = "work_breakdown" + SOLUTION_GUIDE = "solution_guide" diff --git a/app/solution_architecture/local.py b/app/solution_architecture/local.py new file mode 100644 index 0000000..0c27b83 --- /dev/null +++ b/app/solution_architecture/local.py @@ -0,0 +1,788 @@ +"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory. + +Terraform runs only fmt, init -backend=false, validate, plan and providers schema. No +command that changes cloud resources is ever constructed. + +A Specialist with a working copy (app/tools/workspace.py) runs the checks on it and +passes no files; `terraform_fmt` formats the working copy in place. That is what +keeps a fix cheap: the model changes a line and validates, without sending every file +again on each call. +""" + +from __future__ import annotations + +import asyncio +import difflib +import json +import os +import re +import tempfile +from collections.abc import ( + Awaitable, + Callable, + Iterable, + Mapping, + MutableMapping, + Sequence, +) +from dataclasses import dataclass, field +from pathlib import Path, PurePosixPath +from typing import Any + +from execution_engine.adk.runtime import ( + FILES_SCHEMA, + ToolResult, + ToolSpec, + files_from_argument, +) + +from app.solution_architecture.modules import ( + ModuleLookup, + allowed_namespaces, + check_module_sources, +) + +_MAX_OUTPUT = 8_000 +_MAX_OUTLINE = 4_000 # one resource type, when several are looked up together +_MAX_TYPES = 20 # resource types in one lookup +_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json") +_VARIABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$") +_MERMAID_TYPES = ( + "flowchart", + "graph", + "sequenceDiagram", + "classDiagram", + "stateDiagram", + "stateDiagram-v2", + "erDiagram", + "C4Context", + "C4Container", + "C4Component", + "C4Deployment", + "architecture-beta", + "block-beta", +) +_BRACKETS = {"]": "[", ")": "(", "}": "{"} + + +async def mermaid_check(diagram: str) -> ToolResult: + """A basic structural check; it does not render the diagram.""" + problems = [] + lines = [ + line.strip() + for line in diagram.splitlines() + if line.strip() and not line.strip().startswith("%%") + ] + if not diagram.strip(): + problems.append("the diagram is empty") + elif not lines or lines[0].split()[0] not in _MERMAID_TYPES: + problems.append( + "the first line must declare a diagram type, such as 'flowchart TD'" + ) + for number, line in enumerate(diagram.splitlines(), start=1): + stack: list[str] = [] + in_quotes = False + for char in line: + if char == '"': + in_quotes = not in_quotes + elif in_quotes: + continue + elif char in "[({": + stack.append(char) + elif char in _BRACKETS and (not stack or stack.pop() != _BRACKETS[char]): + stack.append("!") + break + if stack: + problems.append(f"Unbalanced brackets on line {number}: {line.strip()}") + if problems: + return ToolResult("Mermaid check failed: " + "; ".join(problems)) + return ToolResult("Mermaid check passed (structure only; not rendered).") + + +@dataclass +class TerraformRunner: + binary: str = "terraform" + timeout_seconds: float = 300 + # Providers are downloaded here once and reused by every later check. Without it, + # each validate or plan downloads its providers again into a scratch directory. + plugin_cache_dir: str | None = None + # The providers the schema lookup answers for, as the provider bundle pins them: + # {local name: {"source": ..., "version": ...}}. + providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict) + # Registry namespaces a `module` may come from, as the provider bundle lists + # them. `terraform init` downloads and evaluates whatever a source names, so + # with none listed every module call is refused. + module_namespaces: tuple[str, ...] = () + # Terraform's plugin cache is not safe for concurrent installs. + _init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False) + _schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False) + # resource type -> (provider label, the resource's schema block) + _schemas: dict[str, tuple[str, dict[str, Any]]] | None = field( + default=None, repr=False + ) + + async def formatted(self, files: Mapping[str, str]) -> dict[str, str] | ToolResult: + """The files formatting changes, with their new content; or why it failed.""" + refusal = _check_files(files) + if refusal: + return refusal + with tempfile.TemporaryDirectory(prefix="tf-fmt-") as tmp: + root = _write(Path(tmp), files) + code, output = await self._run( + [self.binary, "fmt", "-recursive", "-list=true"], root + ) + if code != 0: + return ToolResult(f"terraform fmt failed:\n{output}") + return { + name: (root / name).read_text() + for name in files + if (root / name).read_text() != files[name] + } + + async def fmt(self, files: Mapping[str, str]) -> ToolResult: + changed = await self.formatted(files) + if isinstance(changed, ToolResult): + return changed + if not changed: + return ToolResult("terraform fmt: all files are already formatted.") + formatted = "\n\n".join( + f"--- {name}\n{content}" for name, content in changed.items() + ) + return ToolResult( + _clip(f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}") + ) + + async def validate(self, files: Mapping[str, str]) -> ToolResult: + refusal = ( + _check_files(files) + or check_providers(files, self.providers) + or check_module_sources(files, allowed_namespaces(self.module_namespaces)) + ) + if refusal: + return refusal + with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp: + root = _write(Path(tmp), files) / _module_dir(files) + failure = await self._init(root) + if failure: + return failure + code, output = await self._run([self.binary, "validate", "-no-color"], root) + verdict = "passed" if code == 0 else "failed" + return ToolResult(_clip(f"terraform validate {verdict}:\n{output}")) + + async def plan( + self, files: Mapping[str, str], variables: Mapping[str, str] | None = None + ) -> ToolResult: + refusal = ( + _check_files(files) + or check_providers(files, self.providers) + or check_module_sources(files, allowed_namespaces(self.module_namespaces)) + ) + if refusal: + return refusal + variables = dict(variables or {}) + bad = [name for name in variables if not _VARIABLE_NAME.match(name)] + if bad: + return ToolResult(f"Refused: invalid variable names {', '.join(bad)}") + with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp: + root = _write(Path(tmp), files) / _module_dir(files) + failure = await self._init(root) + if failure: + return failure + args = [ + self.binary, + "plan", + "-no-color", + "-input=false", + "-lock=false", + "-refresh=true", + *(f"-var={name}={value}" for name, value in variables.items()), + ] + code, output = await self._run(args, root) + verdict = "completed" if code == 0 else "failed" + return ToolResult( + _clip(f"terraform plan {verdict} (nothing was applied):\n{output}") + ) + + async def schema( + self, + resource_type: str = "", + block: str = "", + find: str = "", + resource_types: Sequence[str] = (), + ) -> ToolResult: + """What a resource type accepts, from the pinned provider's own schema. + + Several resource types at once come back as outlines: every argument and + block each accepts, by name. That is one call for a whole design, where one + call per type or per setting is what used up a Specialist's budget. + """ + loaded = await self._load_schemas() + if isinstance(loaded, ToolResult): + return loaded + wanted = list( + dict.fromkeys( + name + for name in [*resource_types, *re.split(r"[,\s]+", resource_type)] + if name + ) + ) + if not wanted: + return ToolResult("Refused: name at least one resource type.") + if len(wanted) > 1: + parts = [] + for name in wanted[:_MAX_TYPES]: + if name not in loaded: + close = difflib.get_close_matches(name, loaded, n=3, cutoff=0.6) + hint = f" Close matches: {', '.join(close)}." if close else "" + parts.append( + f"{name}: not a resource type of {self._provider_labels()}." + f"{hint}" + ) + continue + parts.append(_outline_only(name, loaded[name][1])) + if len(wanted) > _MAX_TYPES: + parts.append( + f"[{len(wanted) - _MAX_TYPES} more not shown: ask for at most " + f"{_MAX_TYPES} at a time]" + ) + return ToolResult( + f"{self._provider_labels()}. * marks a required argument.\n\n" + + "\n\n".join(parts) + ) + resource_type = wanted[0] + if resource_type not in loaded: + close = difflib.get_close_matches(resource_type, loaded, n=5, cutoff=0.6) + hint = f" Close matches: {', '.join(close)}." if close else "" + return ToolResult( + f"No resource type {resource_type} in {self._provider_labels()}.{hint}" + ) + label, root = loaded[resource_type] + title = f"{resource_type} ({label})" + if 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 + for step in [part for part in block.split(".") if part]: + nested = node.get("block_types", {}).get(step) + if nested is None: + inside = ", ".join(sorted(node.get("block_types", {}))) or "none" + return ToolResult( + f"{title} has no block {block!r}: {step!r} is not a block there. " + f"Blocks at that level: {inside}." + ) + node = nested["block"] + heading = f"{title}, block {block}" if block else title + 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: + return ( + ", ".join( + f"{pin['source']} {pin['version']}" for pin in self.providers.values() + ) + or "no pinned provider" + ) + + async def _load_schemas(self) -> dict[str, tuple[str, dict[str, Any]]] | ToolResult: + async with self._schema_lock: + if self._schemas is not None: + return self._schemas + if not self.providers: + return ToolResult( + "Schema lookup is unavailable: the Cloud provider bundle pins no " + "Terraform provider." + ) + required = "\n".join( + f' {name} = {{ source = "{pin["source"]}", ' + f'version = "{pin["version"]}" }}' + for name, pin in self.providers.items() + ) + with tempfile.TemporaryDirectory(prefix="tf-schema-") as tmp: + root = Path(tmp) + (root / "versions.tf").write_text( + f"terraform {{\n required_providers {{\n{required}\n }}\n}}\n" + ) + failure = await self._init(root) + if failure: + return failure + code, output = await self._run( + [self.binary, "providers", "schema", "-json"], root + ) + if code != 0: + return ToolResult( + _clip(f"terraform providers schema failed:\n{output}") + ) + try: + data = json.loads(output) + except ValueError: + return ToolResult("terraform providers schema returned no JSON.") + labels = {pin["source"]: pin["version"] for pin in self.providers.values()} + schemas: dict[str, tuple[str, dict[str, Any]]] = {} + for address, provider in (data.get("provider_schemas") or {}).items(): + source = address.split("/", 1)[-1] # drop the registry host + label = f"{source} {labels.get(source, '')}".strip() + for name, resource in (provider.get("resource_schemas") or {}).items(): + schemas[name] = (label, resource.get("block") or {}) + self._schemas = schemas + return schemas + + async def _init(self, root: Path) -> ToolResult | None: + command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"] + if self.plugin_cache_dir: + async with self._init_lock: + code, output = await self._run(command, root) + else: + code, output = await self._run(command, root) + if code != 0: + return ToolResult(_clip(f"terraform init failed:\n{output}")) + return None + + async def _run( + self, args: list[str], cwd: Path, env: Mapping[str, str] | None = None + ) -> tuple[int, str]: + environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})} + if self.plugin_cache_dir: + cache = Path(self.plugin_cache_dir).expanduser().resolve() + cache.mkdir(parents=True, exist_ok=True) + environment["TF_PLUGIN_CACHE_DIR"] = str(cache) + # Each check runs in a scratch directory with no dependency lock file. + # Without this, Terraform downloads a cached provider again to verify it. + environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true" + try: + process = await asyncio.create_subprocess_exec( + *args, + cwd=cwd, + env=environment, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.STDOUT, + ) + except FileNotFoundError: + return 127, f"{self.binary} is not installed or not on PATH." + try: + stdout, _ = await asyncio.wait_for( + process.communicate(), timeout=self.timeout_seconds + ) + except TimeoutError: + process.kill() + await process.wait() + return 124, f"{' '.join(args[:2])} timed out after {self.timeout_seconds}s." + return process.returncode or 0, stdout.decode(errors="replace") + + +_BLOCK_TYPE = re.compile( + r'^\s*(?:resource|data)\s+"([a-z0-9]+)_[a-z0-9_]*"', re.MULTILINE +) +_PROVIDER_SOURCE = re.compile(r'^\s*source\s*=\s*"([\w.-]+/[\w.-]+)"\s*$', re.MULTILINE) +# Built into Terraform itself: terraform_data and the terraform_remote_state source. +_BUILT_IN = frozenset({"terraform"}) + + +def check_providers( + files: Mapping[str, str], pinned: Mapping[str, Mapping[str, str]] +) -> ToolResult | None: + """Refuse code that uses a provider the bundle does not pin. + + `terraform init` downloads whatever provider the code names, at whatever + version is current. A design with a source repository in it brought the GitHub + provider into generated code that way on 2026-10-11. With nothing pinned there + is nothing to hold code to, and it passes. + """ + if not pinned: + return None + names = set(pinned) | _BUILT_IN + sources = {pin["source"] for pin in pinned.values()} + code = "\n".join(text for name, text in files.items() if name.endswith(".tf")) + foreign = sorted({m.group(1) for m in _BLOCK_TYPE.finditer(code)} - names) + undeclared = sorted({m.group(1) for m in _PROVIDER_SOURCE.finditer(code)} - sources) + if not foreign and not undeclared: + return None + found = [f"resources of the {name} provider" for name in foreign] + found += [f"the provider {source}" for source in undeclared] + return ToolResult( + "Refused: the code uses " + + ", ".join(found) + + ". Only these providers may be used: " + + ", ".join(sorted(sources)) + + ". Write resources of those alone, and describe anything outside them in " + "the deployment guidance as a step the user takes." + ) + + +def _check_files(files: Mapping[str, str]) -> ToolResult | None: + if not files: + return ToolResult("Refused: provide at least one Terraform file.") + bad = [] + for name in files: + path = PurePosixPath(name) + if ( + path.is_absolute() + or ".." in path.parts + or not name.endswith(_TERRAFORM_SUFFIXES) + ): + bad.append(name) + if bad: + return ToolResult( + "Refused: file names must be relative .tf, .tf.json or .tfvars paths " + f"without '..': {', '.join(bad)}" + ) + directories = {str(PurePosixPath(name).parent) for name in files} + if len(directories) > 1: + return ToolResult( + "Refused: put all files in one directory (one root module), for example " + f"terraform/main.tf and terraform/variables.tf; got {', '.join(sorted(directories))}" + ) + return None + + +def _module_dir(files: Mapping[str, str]) -> str: + """The one directory holding the files; Terraform runs there.""" + return str(PurePosixPath(next(iter(files))).parent) + + +def _write(root: Path, files: Mapping[str, str]) -> Path: + for name, content in files.items(): + target = root / name + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(content, encoding="utf-8") + return root + + +def _clip(text: str) -> str: + return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]" + + +def _type(value: Any) -> str: + if isinstance(value, str): + return value + if isinstance(value, list) and len(value) == 2 and value[0] != "object": + return f"{value[0]} of {_type(value[1])}" + return "object" + + +def _use(attribute: Mapping[str, Any]) -> str: + if attribute.get("required"): + return "required" + return "optional" if attribute.get("optional") else "read-only" + + +def _arguments(node: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]: + """The arguments code may set: everything but the read-only ones.""" + return { + name: attribute + for name, attribute in sorted((node.get("attributes") or {}).items()) + if _use(attribute) != "read-only" + } + + +def _block_note(nested: Mapping[str, Any]) -> str: + notes = [str(nested.get("nesting_mode", "block"))] + if nested.get("min_items"): + notes.append(f"at least {nested['min_items']}") + if nested.get("max_items"): + notes.append(f"at most {nested['max_items']}") + return ", ".join(notes) + + +def _render_schema(heading: str, node: Mapping[str, Any]) -> str: + """One level in full, and the blocks beneath it as an outline of names.""" + lines = [heading, "", "Arguments:"] + arguments = _arguments(node) + for name, attribute in arguments.items(): + described = " ".join(str(attribute.get("description") or "").split())[:160] + deprecated = " DEPRECATED" if attribute.get("deprecated") else "" + lines.append( + f" {name} ({_type(attribute.get('type'))}, {_use(attribute)})" + f"{deprecated}" + (f": {described}" if described else "") + ) + if not arguments: + lines.append(" none") + + def outline(parent: Mapping[str, Any], depth: int) -> None: + for name, nested in sorted((parent.get("block_types") or {}).items()): + inner = nested.get("block") or {} + names = ", ".join( + f"{argument}*" if attribute.get("required") else argument + for argument, attribute in _arguments(inner).items() + ) + lines.append( + f"{' ' * depth}{name} {{ }} ({_block_note(nested)}): {names or '-'}" + ) + outline(inner, depth + 1) + + lines += ["", "Blocks (* marks a required argument):"] + before = len(lines) + outline(node, 1) + if len(lines) == before: + lines.append(" none") + lines += ["", "Pass `block`, such as a.b, for one block's arguments in full."] + return "\n".join(lines) + + +def _outline_only(resource_type: str, root: Mapping[str, Any]) -> str: + """One resource type as names alone: its arguments on a line, then every block + with its arguments. Enough to see whether a setting exists and where.""" + lines = [resource_type, " " + (_names_line(root) or "-")] + + def outline(parent: Mapping[str, Any], depth: int) -> None: + for name, nested in sorted((parent.get("block_types") or {}).items()): + inner = nested.get("block") or {} + lines.append(f"{' ' * depth}{name} {{ }}: {_names_line(inner) or '-'}") + outline(inner, depth + 1) + + outline(root, 1) + text = "\n".join(lines) + if len(text) > _MAX_OUTLINE: + text = text[:_MAX_OUTLINE] + "\n [cut short: look this type up alone]" + return text + + +def _names_line(node: Mapping[str, Any]) -> str: + return ", ".join( + f"{name}*" if attribute.get("required") else name + for name, attribute in _arguments(node).items() + ) + + +def _find_in_schema(title: str, root: Mapping[str, Any], wanted: str) -> str: + """Every argument or block whose name contains `wanted`, with where it sits.""" + needle = wanted.lower() + found: list[str] = [] + + def search(node: Mapping[str, Any], path: str) -> None: + for name, attribute in sorted((node.get("attributes") or {}).items()): + if needle in name.lower(): + where = f"{path}.{name}" if path else name + found.append( + f" {where} ({_type(attribute.get('type'))}, {_use(attribute)})" + ) + for name, nested in sorted((node.get("block_types") or {}).items()): + where = f"{path}.{name}" if path else name + if needle in name.lower(): + found.append(f" {where} {{ }} ({_block_note(nested)})") + search(nested.get("block") or {}, where) + + search(root, "") + if not found: + return ( + f"{title} has no argument or block named like {wanted!r}. It cannot be " + "set on this resource type." + ) + return f"{title}: {wanted!r} is found at\n" + "\n".join(found) + + +_FILES_SCHEMA: dict[str, Any] = { + **FILES_SCHEMA, + "description": "Terraform files in one directory, e.g. terraform/main.tf", +} + + +def _with_files( + method: Callable[..., Awaitable[ToolResult]], + working_copy: MutableMapping[str, str] | None = None, +) -> Callable[..., Awaitable[ToolResult]]: + """Adapt a runner method to take the FILES_SCHEMA argument. + + With a working copy, the files are the Terraform files in it and the argument is + optional: files passed anyway are written to the working copy first. + """ + + async def handler(files: Any = None, **kwargs: Any) -> ToolResult: + try: + converted = files_from_argument(files) + except TypeError as exc: + return ToolResult(f"Refused: files: {exc}") + if working_copy is None: + return await method(converted, **kwargs) + working_copy.update(converted) + return await method(_terraform_files(working_copy), **kwargs) + + return handler + + +def _terraform_files(files: Mapping[str, str]) -> dict[str, str]: + return { + name: content + for name, content in files.items() + if name.endswith(_TERRAFORM_SUFFIXES) + } + + +def _fmt_in_place( + runner: TerraformRunner, working_copy: MutableMapping[str, str] +) -> Callable[..., Awaitable[ToolResult]]: + async def format_working_copy(files: Mapping[str, str]) -> ToolResult: + changed = await runner.formatted(files) + if isinstance(changed, ToolResult): + return changed + working_copy.update(changed) + if not changed: + return ToolResult("terraform fmt: all files are already formatted.") + return ToolResult( + f"terraform fmt reformatted {len(changed)} file(s) in your working " + f"copy: {', '.join(sorted(changed))}." + ) + + return _with_files(format_working_copy, working_copy) + + +LOCAL_TOOLS: dict[str, tuple[str, str]] = { + "mermaid_check": ("general", "Check a Mermaid diagram's basic structure."), + "terraform_fmt": ("general", "Format Terraform files and return any that changed."), + "terraform_validate": ( + "general", + "Validate Terraform files offline (init -backend=false, validate).", + ), + "terraform_plan": ( + "cloud_read", + "Preview Terraform against the live cloud environment with a plan. Never applies.", + ), + "terraform_module": ( + "general", + ( + "Look up a published Terraform module: its inputs, outputs and " + "submodules, and whether it works with the pinned provider. Give " + "`source` as //, with //modules/ for " + "a submodule. `version` is optional and defaults to the latest. `find` " + "narrows the inputs to those matching the words given." + ), + ), + "terraform_schema": ( + "general", + ( + "Look up what a Terraform resource type accepts, from the provider's own " + "schema. With `resource_types`, a list: an outline of every argument " + "and block each one accepts, in one call. With `resource_type` alone: " + "the same for one type, with descriptions. `block` gives one block in " + "full. `find` says where named settings sit, or that the resource type " + "has none." + ), + ), +} + +_ON_WORKING_COPY = " Runs on your working copy; pass no files." + + +def local_tools( + names: Iterable[str], + runner: TerraformRunner, + working_copy: MutableMapping[str, str] | None = None, +) -> list[ToolSpec]: + """The named tools. With a `working_copy`, the Terraform checks run on it.""" + files_required = [] if working_copy is not None else ["files"] + suffix = _ON_WORKING_COPY if working_copy is not None else "" + + def checks(name: str, method: Callable[..., Awaitable[ToolResult]]) -> ToolSpec: + properties: dict[str, Any] = {"files": _FILES_SCHEMA} + if name == "terraform_plan": + properties["variables"] = { + "type": "object", + "additionalProperties": {"type": "string"}, + } + tier, description = LOCAL_TOOLS[name] + return ToolSpec( + name, + description + suffix, + { + "type": "object", + "properties": properties, + "required": files_required, + }, + method, + tier=tier, + ) + + builders = { + "mermaid_check": lambda: ToolSpec( + "mermaid_check", + LOCAL_TOOLS["mermaid_check"][1], + { + "type": "object", + "properties": {"diagram": {"type": "string"}}, + "required": ["diagram"], + }, + mermaid_check, + tier="general", + ), + "terraform_fmt": lambda: checks( + "terraform_fmt", + _fmt_in_place(runner, working_copy) + if working_copy is not None + else _with_files(runner.fmt), + ), + "terraform_validate": lambda: checks( + "terraform_validate", _with_files(runner.validate, working_copy) + ), + "terraform_plan": lambda: checks( + "terraform_plan", _with_files(runner.plan, working_copy) + ), + "terraform_module": lambda: ToolSpec( + "terraform_module", + LOCAL_TOOLS["terraform_module"][1], + { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": ( + "For example terraform-google-modules/network/google" + ), + }, + "version": {"type": "string", "description": "Such as 18.3.1"}, + "find": { + "type": "string", + "description": "Words to look for in input names, comma-separated", + }, + }, + "required": ["source"], + }, + ModuleLookup( + namespaces=runner.module_namespaces, + pinned={name: pin["version"] for name, pin in runner.providers.items()}, + ).describe, + tier="general", + ), + "terraform_schema": lambda: ToolSpec( + "terraform_schema", + LOCAL_TOOLS["terraform_schema"][1], + { + "type": "object", + "properties": { + "resource_type": { + "type": "string", + "description": "For example google_cloud_run_v2_service", + }, + "resource_types": { + "type": "array", + "items": {"type": "string"}, + "description": ( + "Several resource types in one call: each comes back " + "as an outline of every argument and block it accepts" + ), + }, + "block": { + "type": "string", + "description": "A nested block, such as template.containers", + }, + "find": { + "type": "string", + "description": ( + "Argument or block names to look for; separate several " + "with commas to check them in one call" + ), + }, + }, + "required": [], + }, + runner.schema, + tier="general", + ), + } + return [builders[name]() for name in names] diff --git a/app/solution_architecture/meaning.py b/app/solution_architecture/meaning.py new file mode 100644 index 0000000..f9f5f39 --- /dev/null +++ b/app/solution_architecture/meaning.py @@ -0,0 +1,112 @@ +"""Changed, or only reworded? (ADR-0007, iteration 5 step 15) + +A Specialist revising from a Baseline rewords things it was not asked to change. +Compared as text, every rewording is a change; ignoring text would miss a dropped +restriction, such as "only" removed from a Check. For each item whose text differs +from the Baseline's, this asks the decider whether the new text changes what must be +true. An item it is confident did not is listed as reworded, not changed. + +Without a decision an item stays changed: that is the safe reading. + +Measured against live Jev on 2026-10-09 with nine pairs: three rewordings scored 0.10 +to 0.22 and a renamed Element 0.30; five real changes scored 0.41 (a Check moved to +another Element), 0.61 (a dropped "only"), and 0.90 to 0.96. At 0.25 no real change +was read as a rewording. +""" + +from __future__ import annotations + +import copy +import json +import logging +from collections.abc import Mapping +from typing import Any + +from execution_engine.adk.runtime import Decider, Question + +from app.solution_architecture.chain import RECOMMENDATIONS_FILE +from app.solution_architecture.changes import CHANGED, _graph, _items + +logger = logging.getLogger(__name__) + +REWORDED = "reworded" +_TEXT_OF = { + "checks": ("statement", "applies_to", "source"), + "elements": ("name", "product", "resource_type", "component"), + "relationships": ("from", "kind", "to"), + "recommendations": ("text", "components"), +} + + +def _described(item: Mapping[str, Any], part: str) -> str: + return json.dumps( + {name: item.get(name) for name in _TEXT_OF[part] if item.get(name) is not None}, + ensure_ascii=False, + ) + + +def _by_id(deliverables: Mapping[str, Any] | None, part: str) -> dict[str, dict]: + items = ( + _items(deliverables, "design_recommendations", RECOMMENDATIONS_FILE) + if part == "recommendations" + else _graph(deliverables)[part] + ) + return {str(item.get("id")): item for item in items} + + +async def settle_meaning( + decider: Decider, + summary: Mapping[str, Any], + baseline: Mapping[str, Any] | None, + current: Mapping[str, Any] | None, + *, + unchanged_at: float = 0.25, + scope: str = "", +) -> dict[str, Any]: + """The change summary with items that were only reworded listed as such. + + An item moves from `changed` to `reworded` when the probability that its new + text changes what must be true is at or below `unchanged_at`. Each decision is + recorded under `meaning`, by id. + """ + settled = copy.deepcopy(dict(summary)) + questions: dict[str, Question] = {} + where: dict[str, str] = {} + for part in _TEXT_OF: + old, new = _by_id(baseline, part), _by_id(current, part) + for identifier in settled.get(part, {}).get(CHANGED, []): + if identifier not in old or identifier not in new: + continue + questions[identifier] = Question( + "noul", + f"Before: {_described(old[identifier], part)}\n" + f"After: {_described(new[identifier], part)}\n" + "Does the new text change what must be true of the system, as " + "opposed to saying the same thing in other words?", + ) + where[identifier] = part + if not questions: + return settled + answers = await decider.decide( + "Two versions of one item of a cloud solution architecture.", + questions, + scope=scope, + ) + if not answers: + return settled + meaning: dict[str, float] = {} + for identifier, part in where.items(): + answer = answers.get(identifier) + if answer is None or not isinstance(answer.value, (int, float)): + continue + meaning[identifier] = round(float(answer.value), 3) + if answer.value <= unchanged_at: + settled[part][CHANGED].remove(identifier) + settled[part].setdefault(REWORDED, []).append(identifier) + unrequested = settled.get("unrequested", {}).get(part) + if unrequested and identifier in unrequested: + unrequested.remove(identifier) + if not unrequested: + del settled["unrequested"][part] + settled["meaning"] = meaning + return settled diff --git a/app/solution_architecture/modules.py b/app/solution_architecture/modules.py new file mode 100644 index 0000000..fe27e13 --- /dev/null +++ b/app/solution_architecture/modules.py @@ -0,0 +1,299 @@ +"""Terraform modules from a public registry (iteration 8). + +Generated code may call a published module where one replaces several resources that +must be wired together. Two things keep that safe and checkable, and neither names a +Cloud provider: the provider bundle does. + +- **Which modules.** `terraform init` downloads whatever a `source` names and + Terraform then evaluates it. So a module is accepted only from a registry + namespace the bundle lists, at one exact version. Anything else, a Git URL, a + local path or a version range, is refused before Terraform runs. +- **What a module accepts.** A module hides the resources a Check is about. The + lookup returns a module's inputs, outputs and submodules from the registry, and + says whether its provider requirements admit the version the bundle pins. +""" + +from __future__ import annotations + +import contextvars +import json +import logging +import re +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, field +from typing import Any + +import httpx +from execution_engine.adk.runtime import ToolResult + +logger = logging.getLogger(__name__) + +REGISTRY = "https://registry.terraform.io/v1/modules" +MODULE_TOOL = "terraform_module" +# Whether the Execution a Specialist is running in opted into modules. Set when a +# Specialist starts. Unset, outside an Execution, the runner's own list applies. +MODULES_OPTED_IN: contextvars.ContextVar[bool | None] = contextvars.ContextVar( + "terraform_modules_opted_in", default=None +) +NOT_OPTED_IN = ( + "Refused: this Execution writes plain resources. Published modules are used " + "only when the Execution opts into them. Write the resources directly." +) + + +def allowed_namespaces(configured: Sequence[str]) -> tuple[str, ...]: + """The namespaces a module may come from, here and now: none when the Execution + did not opt in.""" + return () if MODULES_OPTED_IN.get() is False else tuple(configured) + + +_MODULE = re.compile(r'^\s*module\s+"([^"]+)"\s*\{', re.MULTILINE) +_SOURCE = re.compile(r'^\s*source\s*=\s*"([^"]*)"', re.MULTILINE) +_VERSION = re.compile(r'^\s*version\s*=\s*"([^"]*)"', re.MULTILINE) +_EXACT = re.compile(r"^\d+\.\d+\.\d+$") +# namespace/name/provider, with an optional //path/to/submodule +_REGISTRY_SOURCE = re.compile( + r"^([A-Za-z0-9_-]+)/([A-Za-z0-9_-]+)/([a-z0-9]+)(?://([\w./-]+))?$" +) +_MAX_INPUTS = 80 +_DESCRIPTION = 140 + + +@dataclass(frozen=True) +class ModuleCall: + name: str + source: str + version: str + + +def module_calls(files: Mapping[str, str]) -> list[ModuleCall]: + """Every `module` block in the files, with the source and version it names.""" + calls = [] + for text in files.values(): + for match in _MODULE.finditer(text): + body = _block(text, match.end()) + source = _SOURCE.search(body) + version = _VERSION.search(body) + calls.append( + ModuleCall( + match.group(1), + source.group(1) if source else "", + version.group(1) if version else "", + ) + ) + return calls + + +def _block(text: str, start: int) -> str: + """The text of a block whose opening brace ends at `start`, nested blocks + removed, so only its own arguments are read.""" + depth, own, index = 1, [], start + while index < len(text) and depth: + char = text[index] + if char == "{": + depth += 1 + elif char == "}": + depth -= 1 + elif depth == 1: + own.append(char) + index += 1 + return "".join(own) + + +def check_module_sources( + files: Mapping[str, str], namespaces: Sequence[str] +) -> ToolResult | None: + """Refuse a module that is not from an allowed registry namespace at one exact + version. None when every module call is acceptable, or there are none.""" + if any( + name.endswith(".tf.json") and '"module"' in text for name, text in files.items() + ): + return ToolResult("Refused: write module calls in .tf files, not .tf.json.") + calls = module_calls(files) + if calls and MODULES_OPTED_IN.get() is False: + return ToolResult(NOT_OPTED_IN) + problems = [] + for call in calls: + parsed = _REGISTRY_SOURCE.match(call.source) + if not parsed or parsed.group(1) not in namespaces: + allowed = ", ".join(namespaces) or "none are configured" + problems.append( + f'module "{call.name}": source "{call.source}" is not allowed. A ' + "module comes only from these registry namespaces, as " + f"//: {allowed}" + ) + elif not _EXACT.match(call.version): + problems.append( + f'module "{call.name}": set `version` to one exact version, such ' + f'as "1.2.3"; got "{call.version}"' + ) + if problems: + return ToolResult("Refused: " + "; ".join(problems) + ".") + return None + + +# --- what a module accepts -------------------------------------------------------------- + + +def admits(constraint: str, version: str) -> bool: + """Whether a Terraform version constraint, such as ">= 6.2, < 8", admits an + exact version. An unreadable term is taken to admit it.""" + wanted = _numbers(version) + for term in constraint.split(","): + match = re.match(r"^\s*(>=|<=|>|<|=|!=|~>)?\s*v?([\d.]+)", term) + if not match: + continue + operator, bound = match.group(1) or "=", _numbers(match.group(2)) + if operator == "~>": + # ~> 3.0 admits 3.x; ~> 3.1.2 admits 3.1.x from 3.1.2. + upper = [*bound[:-1]] + if upper: + upper[-1] += 1 + ok = wanted >= bound and (not upper or wanted < upper) + else: + ok = { + ">=": wanted >= bound, + "<=": wanted <= bound, + ">": wanted > bound, + "<": wanted < bound, + "=": wanted[: len(bound)] == bound, + "!=": wanted[: len(bound)] != bound, + }[operator] + if not ok: + return False + return True + + +def _numbers(version: str) -> list[int]: + return [int(part) for part in version.split(".") if part.isdigit()] + + +@dataclass +class ModuleLookup: + """Reads a module's inputs and outputs from the registry.""" + + namespaces: tuple[str, ...] = () + # The provider versions generated code is pinned to: {local name: version}. + pinned: Mapping[str, str] = field(default_factory=dict) + timeout_seconds: float = 20 + _cache: dict[str, dict[str, Any]] = field(default_factory=dict, repr=False) + + async def describe( + self, source: str = "", version: str = "", find: str = "" + ) -> ToolResult: + parsed = _REGISTRY_SOURCE.match(source.strip()) + if not parsed or parsed.group(1) not in self.namespaces: + allowed = ", ".join(self.namespaces) or "none are configured" + return ToolResult( + f'Refused: "{source}" is not a module from an allowed registry ' + f"namespace. Give //, optionally with " + f"//modules/. Allowed namespaces: {allowed}." + ) + namespace, name, provider, path = parsed.groups() + if version and not _EXACT.match(version): + return ToolResult( + 'Refused: `version` is one exact version, such as "1.2.3".' + ) + data = await self._fetch(f"{namespace}/{name}/{provider}", version) + if isinstance(data, ToolResult): + return data + part = data.get("root") or {} + if path: + wanted = path.strip("/") + part = next( + ( + item + for item in data.get("submodules") or [] + if item.get("path", "").strip("/") == wanted + ), + None, + ) + if part is None: + listed = ", ".join( + item.get("path", "") for item in data.get("submodules") or [] + ) + return ToolResult( + f"{namespace}/{name}/{provider} {data.get('version')} has no " + f"submodule at {path}. Its submodules: {listed or 'none'}." + ) + return ToolResult(self._render(data, part, source, find)) + + async def _fetch(self, module: str, version: str) -> dict[str, Any] | ToolResult: + key = f"{module}/{version}" if version else module + if key in self._cache: + return self._cache[key] + try: + async with httpx.AsyncClient(timeout=self.timeout_seconds) as client: + response = await client.get(f"{REGISTRY}/{key}") + except httpx.HTTPError as exc: + return ToolResult( + f"The module registry could not be reached ({type(exc).__name__}). " + "Write the resources directly, from the patterns and the schema." + ) + if response.status_code == 404: + return ToolResult(f"The registry has no module {module} {version}.".strip()) + if response.status_code != 200: + return ToolResult( + f"The module registry answered {response.status_code} for {module}." + ) + try: + data = response.json() + except json.JSONDecodeError: + return ToolResult(f"The registry's answer for {module} was not readable.") + self._cache[key] = data + return data + + def _render( + self, + data: Mapping[str, Any], + part: Mapping[str, Any], + source: str, + find: str, + ) -> str: + version = data.get("version", "") + lines = [f'{source} version "{version}"'] + for dependency in part.get("provider_dependencies") or []: + name, constraint = dependency.get("name", ""), dependency.get("version", "") + pin = self.pinned.get(name) + if pin and constraint and not admits(constraint, pin): + lines.append( + f"NOT USABLE: it requires {name} {constraint}, and the code is " + f"pinned to {name} {pin}. Write the resources directly." + ) + elif not pin and name: + lines.append( + f"It also uses the {name} provider ({constraint or 'any version'});" + " Terraform installs it." + ) + inputs = sorted( + part.get("inputs") or [], + key=lambda item: (not item.get("required"), item.get("name", "")), + ) + if find: + wanted = [word.strip().lower() for word in find.split(",") if word.strip()] + inputs = [ + item + for item in inputs + if any( + word + in f"{item.get('name', '')} {item.get('description', '')}".lower() + for word in wanted + ) + ] + lines.append(f"Inputs matching {find}: {len(inputs) or 'none'}") + else: + lines.append(f"Inputs ({len(inputs)}; required first):") + for item in inputs[:_MAX_INPUTS]: + need = "required" if item.get("required") else "optional" + kind = " ".join(str(item.get("type", "")).split())[:60] + about = " ".join(str(item.get("description", "")).split())[:_DESCRIPTION] + lines.append(f"- {item.get('name')} ({need}, {kind}): {about}") + if len(inputs) > _MAX_INPUTS: + lines.append(f"[{len(inputs) - _MAX_INPUTS} more; use `find`]") + outputs = [item.get("name", "") for item in part.get("outputs") or []] + if outputs and not find: + lines.append("Outputs: " + ", ".join(outputs)) + submodules = [item.get("path", "") for item in data.get("submodules") or []] + if submodules and not find: + lines.append("Submodules: " + ", ".join(submodules)) + return "\n".join(lines) diff --git a/app/solution_architecture/pillars.py b/app/solution_architecture/pillars.py new file mode 100644 index 0000000..d8f4efa --- /dev/null +++ b/app/solution_architecture/pillars.py @@ -0,0 +1,374 @@ +"""The design advisor's fan-out to one advisor per architecture-framework pillar. + +Pillar advice is working material for the design recommendations Deliverable, not a +Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's +working memory, so a Revision re-consults only the pillars its feedback touches. + +Each advisor also returns its review of the pillar's own checklist: for every item, +whether its advice addresses it, or why it does not apply. The reviews are kept +beside the advice and written into the Deliverable by code when it is submitted, so +an architect sees the whole checklist accounted for and no model spends output +copying it. +""" + +from __future__ import annotations + +import asyncio +import dataclasses +from collections.abc import Mapping, MutableMapping, Sequence +from contextlib import AsyncExitStack +from typing import Any + +from execution_engine.adk.runtime import ( + AgentRuntime, + AgentTask, + Decider, + Question, + RoleSpec, + RunLimiter, + Submitted, + ToolResult, + ToolSpec, +) + +CONSULT_TOOL = "consult_pillar_advisors" +NO_GUIDANCE = "No guidance" +ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given +CHECKLIST_KEY = "pillar_checklists" # working memory: pillar -> its checklist review +REVIEW_HEADING = "Architecture framework checklist review" +# What a Change request carries over from its Baseline's working memory. +KEPT_FOR_CHANGES = (ADVICE_KEY, CHECKLIST_KEY) +_CHANGE_LIMIT = 6_000 +NEEDS_CUSTOMER = "needs_customer_input" +STATUSES = ("addressed", "not_applicable", NEEDS_CUSTOMER, "not_addressed") +_STATUS_WORDS = { + "addressed": "Addressed", + "not_applicable": "Does not apply", + # The item applies, and the customer's request does not say what would settle + # it. That is missing information, not a fault in the design: it is reported + # with the question to put to the customer. + NEEDS_CUSTOMER: "To confirm with the customer", + "not_addressed": "Not addressed", +} +QUESTIONS_HEADING = "Questions for the customer" + + +AFFECTED = ("not at all", "only indirectly", "directly") + + +async def pillars_touched( + decider: Decider, + pillars: Sequence[str], + change: str, + *, + threshold: float = 1.5, + scope: str = "", +) -> list[str] | None: + """The pillars whose recommendations a change affects directly (ADR-0007). + + One graded question per pillar: not at all, only indirectly, directly. A pillar + at `threshold` or above, on that scale of 0 to 2, is consulted again. An empty + list means the change touches none of them. None means no decision was + available, and every pillar is consulted. + + Asked as a yes or no ("does this change call for revisiting ...?") the answer + was yes for nearly every pillar of every change; measured on 2026-10-09. + """ + if not change.strip() or not pillars: + return None + answers = await decider.decide( + f"A change to a cloud solution architecture:\n{change[:_CHANGE_LIMIT]}", + { + pillar: Question( + "score", + f"How directly does this change affect the {pillar} " + "recommendations for the workload?", + AFFECTED, + ) + for pillar in pillars + }, + scope=scope, + ) + if not answers: + return None + return [ + pillar + for pillar in pillars + if (answer := answers.get(pillar)) is not None + and isinstance(answer.value, (int, float)) + and answer.value >= threshold + ] + + +def pillar_consultation_tool( + runtime: AgentRuntime, + advisor: RoleSpec, + pillar_skills: Mapping[str, str], + extra_tools: Sequence[ToolSpec] = (), + memory: MutableMapping[str, Any] | None = None, + limiter: RunLimiter | None = None, +) -> ToolSpec: + """A tool that runs one pillar advisor per pillar, in parallel, each with its Skill. + + With `memory`, advice is remembered: naming `pillars` re-consults only those and + returns the remembered advice for the rest. + """ + + async def advise(pillar: str, brief: str) -> tuple[str, list[dict[str, str]]]: + async with AsyncExitStack() as stack: + if limiter: + await stack.enter_async_context(limiter.slot()) + return await _advise( + runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools + ) + + async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult: + # No `pillars` consults them all; an empty list consults none, and returns + # what was said before. + chosen = list(pillar_skills) if pillars is None else list(pillars) + unknown = [pillar for pillar in chosen if pillar not in pillar_skills] + if unknown: + return ToolResult( + f"Refused: unknown pillars {', '.join(unknown)}; " + f"choose from {', '.join(pillar_skills)}" + ) + async with AsyncExitStack() as stack: + if limiter: + # The calling Specialist only waits here, so its slot goes to advisors. + await stack.enter_async_context(limiter.lend()) + fresh = dict( + zip( + chosen, + await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)), + ) + ) + remembered: dict[str, str] = ( + dict(memory.get(ADVICE_KEY, {})) if memory is not None else {} + ) + reviews: dict[str, list[dict[str, str]]] = ( + dict(memory.get(CHECKLIST_KEY, {})) if memory is not None else {} + ) + sections = [] + for pillar in pillar_skills: + if pillar in fresh: + advice, review = fresh[pillar] + if not advice.startswith(NO_GUIDANCE): + remembered[pillar] = advice + reviews[pillar] = review + sections.append(f"## {pillar}\n\n{advice}") + elif pillar in remembered: + sections.append( + f"## {pillar} (from your earlier consultation)\n\n" + f"{remembered[pillar]}" + ) + if memory is not None: + memory[ADVICE_KEY] = remembered + memory[CHECKLIST_KEY] = reviews + return ToolResult("\n\n".join(sections)) + + return ToolSpec( + CONSULT_TOOL, + "Get guidance from one advisor per architecture-framework pillar, in parallel. " + "Give a brief with the workload, its requirements and the selected products. " + "Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult " + "only those; advice already given for the others is returned unchanged. An " + "empty list consults none and returns the advice already given.", + { + "type": "object", + "properties": { + "brief": {"type": "string"}, + "pillars": { + "type": "array", + "items": {"type": "string", "enum": list(pillar_skills)}, + }, + }, + "required": ["brief"], + }, + consult, + ) + + +async def _advise( + runtime: AgentRuntime, + advisor: RoleSpec, + pillar: str, + skill: str, + brief: str, + extra_tools: Sequence[ToolSpec], +) -> tuple[str, list[dict[str, str]]]: + """One advisor's advice, and its review of the pillar's checklist.""" + role = dataclasses.replace(advisor, skills=(skill,)) + task = AgentTask( + role=advisor.name, + prompt=f"Advise on the {pillar} pillar for this workload.", + context={"pillar": pillar, "brief": brief}, + ) + review: list[dict[str, str]] = [] + try: + outcome = await runtime.run( + role, task, [_submit_advice_tool(review), *extra_tools] + ) + except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others + return f"{NO_GUIDANCE}: the advisor failed ({exc}).", [] + if isinstance(outcome, Submitted): + return outcome.content.strip(), review + return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}.", [] + + +def _submit_advice_tool(review: list[dict[str, str]]) -> ToolSpec: + """`review` receives the checklist review the advisor submits with its advice.""" + + async def submit_advice(content: str, checklist: Sequence[Any] = ()) -> ToolResult: + if not content.strip(): + return ToolResult("Not submitted: the advice is empty.") + entries = [ + { + "item": " ".join(str(entry.get("item", "")).split()), + "status": str(entry.get("status", "")), + "note": " ".join(str(entry.get("note", "")).split()), + "question": " ".join(str(entry.get("question") or "").split()), + } + for entry in checklist or () + if isinstance(entry, Mapping) + and str(entry.get("item", "")).strip() + and entry.get("status") in STATUSES + ] + unasked = [ + entry["item"] + for entry in entries + if entry["status"] == NEEDS_CUSTOMER and not entry["question"] + ] + if unasked: + return ToolResult( + "Not submitted: an item to confirm with the customer needs the " + "`question` to put to them. Missing for: " + "; ".join(unasked) + ) + review[:] = entries + return ToolResult("Advice submitted.", Submitted(content)) + + text = {"type": "string"} + return ToolSpec( + "submit_advice", + "Submit your pillar recommendations as markdown, with your review of the " + "pillar's checklist. Ends your turn.", + { + "type": "object", + "properties": { + "content": text, + "checklist": { + "type": "array", + "description": "One entry for every item of the Skill's " + "validation checklist.", + "items": { + "type": "object", + "properties": { + "item": text, + "status": {"type": "string", "enum": list(STATUSES)}, + "note": { + "type": "string", + "description": "How your advice addresses it, why " + "it does not apply to this workload, or what the " + "request leaves unsaid.", + }, + "question": { + "type": "string", + "description": "For needs_customer_input only: " + "the question to put to the customer, answerable " + "by someone who knows their organisation.", + }, + }, + "required": ["item", "status", "note"], + }, + }, + }, + "required": ["content"], + }, + submit_advice, + tier="execution", + ) + + +def render_checklist_review(working: Mapping[str, Any]) -> str: + """The advisors' checklist reviews as one section of markdown tables, or "" when + there are none. Written by code from what the advisors recorded.""" + reviews = working.get(CHECKLIST_KEY) + if not isinstance(reviews, Mapping) or not any(reviews.values()): + return "" + parts = [ + f"## {REVIEW_HEADING}", + "", + ( + "Each pillar advisor's review of its pillar's checklist for this " + "workload: what its advice addresses, what does not apply and why, and " + "what the request does not say enough to settle." + ), + ] + for pillar, entries in reviews.items(): + if not entries: + continue + parts += [ + "", + f"### {pillar}", + "", + "| Checklist item | Review | How, or why not |", + "| --- | --- | --- |", + ] + parts += [ + "| " + + " | ".join( + str(value).replace("|", "\\|") + for value in ( + entry.get("item", ""), + _STATUS_WORDS.get(str(entry.get("status")), ""), + entry.get("note", ""), + ) + ) + + " |" + for entry in entries + if isinstance(entry, Mapping) + ] + questions = customer_questions(working) + if questions: + parts += [ + "", + f"### {QUESTIONS_HEADING}", + "", + ( + "The request does not say enough to settle these. They are not " + "faults in the design: each is something to ask the customer, and " + "the answer may change a recommendation." + ), + "", + "| Pillar | About | Question |", + "| --- | --- | --- |", + ] + parts += [ + "| " + + " | ".join( + value.replace("|", "\\|") + for value in (item["pillar"], item["item"], item["question"]) + ) + + " |" + for item in questions + ] + return "\n".join(parts) + "\n" + + +def customer_questions(working: Mapping[str, Any]) -> list[dict[str, str]]: + """What the advisors found the request does not say: each checklist item that + needs the customer's answer, with the question to put to them.""" + reviews = working.get(CHECKLIST_KEY) + if not isinstance(reviews, Mapping): + return [] + return [ + { + "pillar": str(pillar), + "item": str(entry.get("item", "")), + "question": str(entry.get("question", "")), + } + for pillar, entries in reviews.items() + for entry in entries or () + if isinstance(entry, Mapping) + and entry.get("status") == NEEDS_CUSTOMER + and entry.get("question") + ] diff --git a/app/solution_architecture/presentation.py b/app/solution_architecture/presentation.py new file mode 100644 index 0000000..8daba90 --- /dev/null +++ b/app/solution_architecture/presentation.py @@ -0,0 +1,173 @@ +"""Presenting an Execution to callers: prompt text and the /generate response shape.""" + +from __future__ import annotations + +import re +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import RoleSpec +from execution_engine.agent import Interaction +from execution_engine.presentation import describe_prompt as _describe_prompt + + +def describe_prompt(prompt: Mapping[str, Any]) -> str: + """What the user is asked, with what this Workflow's Approvals commit to.""" + return _describe_prompt( + prompt, + lambda approval: ( + _describe_changes(approval) + + _describe_target_architecture(approval.get("target_architecture")) + ), + ) + + +_CHANGE_WORDS = {"added": "Added", "changed": "Changed", "removed": "Removed"} + + +def _describe_changes(approval: Mapping[str, Any]) -> str: + """In a Change request: what this Phase changes against the Baseline. It comes + from the ids in the two versions, not from an agent's account.""" + if "changes" not in approval: + return "" + changes = approval["changes"] + lines = [f"This changes the architecture delivered in {approval.get('baseline')}."] + if not changes: + lines.append("Nothing in this Phase differs from it.") + for item in changes.get("requirements", []): + lines.append( + f"- Requirement {item['id']} {item['change']}: {item['text']} " + f"({item['reason']})" + ) + for part in ( + "components", + "recommendations", + "elements", + "relationships", + "checks", + ): + for change, word in _CHANGE_WORDS.items(): + ids = changes.get(part, {}).get(change) + if ids: + lines.append(f"- {word} {part}: {', '.join(ids)}") + for part, ids in changes.get("unrequested", {}).items(): + lines.append( + f"- Changed without being asked for ({part}): {', '.join(ids)}. No " + "changed requirement reaches these." + ) + return "\n".join(lines) + "\n\n" + + +def _describe_target_architecture(summary: Mapping[str, Any] | None) -> str: + """What the design Approval commits to: no code is written until it is granted.""" + if not summary: + return "" + text = ( + f"The Target architecture has {summary['elements']} Elements, " + f"{summary['relationships']} Relationships and {summary['checks']} Checks. " + "No infrastructure code is written until you approve it; the code is then " + "validated against those Checks.\n\n" + ) + for item in summary.get("not_applicable", []): + text += ( + f"Recommendation {item['recommendation']} is treated as not applicable: " + f"{item['reason']}\n" + ) + return text + ("\n" if summary.get("not_applicable") else "") + + +def to_generate_response( + interaction: Interaction, roles: Mapping[str, RoleSpec] +) -> dict[str, Any]: + """Map an Execution onto the legacy /generate response keys.""" + from app.solution_architecture.workflow import DeliverableKind + + state = interaction.state + deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {}) + ledger = state.get("ledger", {}) + + def content(kind: str) -> str | None: + item = deliverables.get(kind) + return item["content"] if item else None + + def attachment(kind: str, name: str) -> str | None: + item = deliverables.get(kind) + return item.get("attachments", {}).get(name) if item else None + + requirements = content(DeliverableKind.REQUIREMENTS) + revisions = sum( + d.get("revisions", 0) for d in ledger.get("deliverables", {}).values() + ) + submitted = [kind for kind in DeliverableKind if kind in deliverables] + skills = _skills_used(submitted, roles) + status = { + "completed": "success", + "completed_with_warnings": "completed_with_warnings", + }.get(interaction.status, interaction.status) + + return { + "execution_id": interaction.execution_id, + "session_id": state.get("session_id"), + "status": status, + "validation_passed": interaction.status == "completed", + "total_loop_iterations": revisions + 1, + "current_phase": _current_phase(ledger), + "artifacts": { + "source_discovery_doc": _section(requirements, "Current state"), + "source_mermaid_diagram": None, + "requirements_doc": requirements, + "architecture_doc": content(DeliverableKind.ARCHITECTURE_DESCRIPTION), + "mermaid_diagram": attachment( + DeliverableKind.TARGET_ARCHITECTURE, "architecture.mmd" + ), + "terraform_code": attachment( + DeliverableKind.DEPLOYMENT_GUIDANCE, "terraform/main.tf" + ), + "validation_results": content(DeliverableKind.VALIDATION_RESULTS), + "solution_guide": content(DeliverableKind.SOLUTION_GUIDE), + }, + "active_skills": skills, + "warnings": list(state.get("warnings", [])), + } + + +def _skills_used(submitted: Sequence[str], roles: Mapping[str, RoleSpec]) -> list[str]: + from app.solution_architecture.workflow import DEPENDENCY_GRAPH + + names: list[str] = [] + for kind in submitted: + role = roles.get(DEPENDENCY_GRAPH[kind].specialist) + for skill in role.skills if role else (): + if skill not in names: + names.append(skill) + return names + + +def _current_phase(ledger: Mapping[str, Any]) -> str | None: + phases: Mapping[str, str] = ledger.get("phases", {}) + for phase, status in phases.items(): + if status != "approved": + return phase + return list(phases)[-1] if phases else None + + +def _section(markdown: str | None, heading: str) -> str | None: + """The body under a heading (any level, numbering ignored), up to the next heading.""" + if not markdown: + return None + lines = markdown.splitlines() + pattern = re.compile( + rf"^#{{1,6}}\s+(?:\d+(?:\.\d+)*\.?\s+)?{re.escape(heading)}\s*$", re.IGNORECASE + ) + for index, line in enumerate(lines): + if pattern.match(line.strip()): + level = len(line.strip()) - len(line.strip().lstrip("#")) + body = [] + for following in lines[index + 1 :]: + stripped = following.strip() + hashes = len(stripped) - len(stripped.lstrip("#")) + if stripped.startswith("#") and hashes <= level: + break + body.append(following) + return "\n".join(body).strip() or None + return None diff --git a/app/solution_architecture/requirements_review.py b/app/solution_architecture/requirements_review.py new file mode 100644 index 0000000..1932e08 --- /dev/null +++ b/app/solution_architecture/requirements_review.py @@ -0,0 +1,79 @@ +"""A review of the requirements: they describe the problem, not the solution. + +Requirements discovery is kept apart from solutioning, so a requirement names no +product. That rule was an instruction the engine could not enforce; the evaluation +checked it only afterwards, against a list of product names. This asks the decider +(ADR-0007), once per requirement, whether it names a cloud product or managed +service. It never blocks: what it raises is returned to the Specialist once. +""" + +from __future__ import annotations + +import logging +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import Decider, Question + +from app.solution_architecture.chain import REQUIREMENTS_FILE, read_list +from app.solution_architecture.kinds import DeliverableKind + +logger = logging.getLogger(__name__) + +_TEXT = 200 + + +class RequirementsReview: + def __init__(self, decider: Decider, *, act: float = 0.3) -> None: + self._decider = decider + # Lower than the router's threshold, from measurement on 2026-10-08: across + # 61 requirements from three passed runs the highest answer was 0.10, and + # requirements written to name a product scored 0.34, 0.61 and 0.93. + self._act = act + + async def __call__( + self, + kind: DeliverableKind, + attachments: Mapping[str, str], + upstream: Mapping[str, Mapping[str, Any]] | None, + scope: str = "", + ) -> Sequence[str]: + """The requirements that name a product, each as a line for the Specialist.""" + if kind != DeliverableKind.REQUIREMENTS: + return () + items = [ + item + for item in read_list( + {"requirements": {"attachments": attachments}}, + "requirements", + REQUIREMENTS_FILE, + ) + if isinstance(item.get("id"), str) and isinstance(item.get("text"), str) + ] + if not items: + return () + answers = await self._decider.decide( + "Requirements for a workload, written before any product is chosen.", + { + item["id"]: Question( + "noul", + f'Requirement: "{item["text"]}". Does it name a specific cloud ' + "provider's product or managed service, as opposed to " + "describing what is needed?", + ) + for item in items + }, + scope=scope, + ) + if not answers: + return () + raised = [ + f'{item["id"]} names a product or service: "{item["text"][:_TEXT]}". ' + "Say what is needed, not what to use" + for item in items + if (answer := answers.get(item["id"])) is not None + and answer.is_yes(self._act) + ] + if raised: + logger.info("[%s] requirements review raised %d", scope, len(raised)) + return tuple(raised) diff --git a/app/solution_architecture/schema_review.py b/app/solution_architecture/schema_review.py new file mode 100644 index 0000000..b874ce5 --- /dev/null +++ b/app/solution_architecture/schema_review.py @@ -0,0 +1,169 @@ +"""A review of the Target architecture against the provider's schema, in code. + +A Check that names a setting its Element's resource type does not have cannot be met +by any code. Left alone it costs a whole Revision: the code's author finds it, the +design is reopened, and everything after it is done again. In the run of 2026-10-07 +that happened twice, with a schema lookup available to the Specialist that wrote the +Checks. + +This reads the settings each Check names and looks them up, so the design is told +before it is submitted. It is a review, not a rule: a Check is prose, and a word that +looks like a setting may be a value. What it raises is returned once. +""" + +from __future__ import annotations + +import difflib +import logging +import re +from collections.abc import Mapping, Sequence +from typing import Any + +from execution_engine.adk.runtime import ToolResult + +from app.solution_architecture.kinds import DeliverableKind +from app.solution_architecture.local import TerraformRunner +from app.solution_architecture.target_architecture import ( + GRAPH_ATTACHMENT, + GraphError, + parse_graph, +) + +logger = logging.getLogger(__name__) + +_QUOTED = re.compile(r"\"[^\"]*\"|'[^']*'") +_CODE = re.compile(r"`([^`]+)`") +# snake_case with at least one underscore, or a dotted path of lower-case names. +_NAME = re.compile( + r"(? tuple[str, ...]: + """The settings a Check's statement names, as written. + + Anything in backticks that reads as a name or a dotted path, and bare + snake_case names and dotted paths. Quoted text is a value, so it is skipped, + as are paths such as roles/x.y. + """ + found: list[str] = [] + for span in _CODE.findall(statement): + candidate = span.strip().split("=")[0].strip() + if _PATH.match(candidate) and candidate not in _LITERALS: + found.append(candidate) + bare = _QUOTED.sub(" ", _CODE.sub(" ", statement)) + found += [match.group(1).rstrip(".") for match in _NAME.finditer(bare)] + return tuple(dict.fromkeys(found)) + + +def _names(block: Mapping[str, Any]) -> set[str]: + """Every argument and block name anywhere in a resource type's schema.""" + names = set(block.get("attributes") or {}) + for name, nested in (block.get("block_types") or {}).items(): + names.add(name) + names |= _names(nested.get("block") or {}) + return names + + +def _is_missing(setting: str, known: set[str]) -> bool: + """Whether a name a Check uses is a setting the resource type lacks. + + A path is judged by the setting at its end, and only when it starts at a name + the type has. One that does not start there is a value written with dots, such + as a database flag (`cloudsql.iam_authentication`) or a service + (`run.googleapis.com`): both were raised as missing settings on 2026-10-09. + """ + first, _, rest = setting.partition(".") + if rest and first not in known: + return False + return setting.split(".")[-1] not in known + + +class SchemaReview: + def __init__(self, runner: TerraformRunner) -> None: + self._runner = runner + self._names: dict[str, set[str]] = {} + + async def __call__( + self, + kind: DeliverableKind, + attachments: Mapping[str, str], + upstream: Mapping[str, Mapping[str, Any]] | None, + scope: str = "", + ) -> Sequence[str]: + """Resource types the provider does not have, and Checks naming a setting + their Element's resource type does not have.""" + if kind != DeliverableKind.TARGET_ARCHITECTURE: + return () + try: + graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, "")) + except GraphError: + return () + schemas = await self._runner._load_schemas() + if isinstance(schemas, ToolResult): + logger.info("Schema review skipped: %s", schemas.message[:120]) + return () + + concerns: list[str] = [] + types = {element.id: element.resource_type for element in graph.elements} + for element in graph.elements: + if element.resource_type not in schemas: + close = difflib.get_close_matches( + element.resource_type, schemas, n=3, cutoff=0.6 + ) + hint = f" Close matches: {', '.join(close)}." if close else "" + concerns.append( + f"Element {element.id}: {element.resource_type} is not a " + f"resource type of the provider.{hint}" + ) + for check in graph.checks: + resource_type = types.get(check.applies_to) + if resource_type not in schemas: + continue # a Check on a Relationship, or a type already raised + known = self._names.setdefault( + resource_type, _names(schemas[resource_type][1]) + ) + missing = [ + setting + for setting in named_settings(check.statement) + if setting not in schemas and _is_missing(setting, known) + ] + if missing: + concerns.append( + f"Check {check.id}: {resource_type} has no setting named " + f"{', '.join(missing)}, so no code can meet it there. Put the " + "Check on the Element whose resource type has that setting, " + "or reword it. Leave it if that word is a value, not a setting" + ) + if concerns: + logger.info("[%s] schema review raised %d item(s)", scope, len(concerns)) + return tuple(concerns) + + +class Reviews: + """Several reviews as one: everything any of them raises.""" + + def __init__(self, reviews: Sequence[Any]) -> None: + self._reviews = tuple(reviews) + + async def __call__( + self, + kind: Any, + attachments: Mapping[str, str], + upstream: Mapping[str, Mapping[str, Any]] | None, + scope: str = "", + ) -> Sequence[str]: + raised: list[str] = [] + for review in self._reviews: + try: + raised += await review(kind, attachments, upstream, scope) + except Exception: # one review failing must not lose the others + logger.exception("A submission review failed; continuing") + return tuple(raised) diff --git a/app/solution_architecture/target_architecture.py b/app/solution_architecture/target_architecture.py new file mode 100644 index 0000000..8b799e1 --- /dev/null +++ b/app/solution_architecture/target_architecture.py @@ -0,0 +1,356 @@ +"""The Target architecture: one explicit graph, established before code (ADR-0005). + + Elements every component and the resource that realises it + Relationships how Elements connect + Checks the numbered, verifiable conditions each must meet, each traced + to the requirement or design recommendation it comes from + +This module is pure: it parses the graph, states what is wrong with it, renders it as +a diagram and as tables a person can review, and says whether the Requirements chain +through it is complete. +""" + +from __future__ import annotations + +import json +import re +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +GRAPH_ATTACHMENT = "target-architecture.json" +DIAGRAM_ATTACHMENT = "architecture.mmd" + + +@dataclass(frozen=True) +class Element: + id: str + name: str + product: str + resource_type: str + component: str | None = None # None for a supporting Element, e.g. an identity + + +@dataclass(frozen=True) +class Relationship: + id: str + source: str # "from" in the data + target: str # "to" in the data + kind: str + + +@dataclass(frozen=True) +class Check: + id: str + applies_to: str # an Element or Relationship id + statement: str + source: str # a requirement or design recommendation id + + +@dataclass(frozen=True) +class NotApplicable: + recommendation: str + reason: str + + +@dataclass(frozen=True) +class TargetArchitecture: + elements: tuple[Element, ...] + relationships: tuple[Relationship, ...] + checks: tuple[Check, ...] + not_applicable: tuple[NotApplicable, ...] = () + + @property + def check_ids(self) -> tuple[str, ...]: + return tuple(check.id for check in self.checks) + + def summary(self) -> dict[str, Any]: + """What a user approving the design is told about the graph.""" + return { + "elements": len(self.elements), + "relationships": len(self.relationships), + "checks": len(self.checks), + "not_applicable": [ + {"recommendation": item.recommendation, "reason": item.reason} + for item in self.not_applicable + ], + } + + +class GraphError(ValueError): + """The graph is not well-formed; `problems` says how, one entry per fault.""" + + def __init__(self, problems: Sequence[str]) -> None: + super().__init__("; ".join(problems)) + self.problems = tuple(problems) + + +def parse_graph(text: str) -> TargetArchitecture: + """Parse target-architecture.json, or raise GraphError naming every fault.""" + name = GRAPH_ATTACHMENT + try: + data = json.loads(text) + except ValueError as exc: + raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc + if not isinstance(data, dict): + raise GraphError( + [f"{name}: must be an object with elements, relationships and checks"] + ) + + problems: list[str] = [] + + def items(key: str, required: Sequence[str]) -> list[dict[str, str]]: + raw = data.get(key, []) + if not isinstance(raw, list): + problems.append(f"{name}.{key}: must be a list") + return [] + accepted = [] + for index, item in enumerate(raw): + where = f"{name}.{key}[{index}]" + if not isinstance(item, dict): + problems.append(f"{where}: must be an object") + continue + missing = [ + field + for field in required + if not isinstance(item.get(field), str) or not item[field].strip() + ] + if missing: + problems.append(f"{where}: needs a non-empty {', '.join(missing)}") + continue + accepted.append(item) + return accepted + + elements = tuple( + Element( + id=item["id"], + name=item["name"], + product=item["product"], + resource_type=item["resource_type"], + component=item.get("component") or None, + ) + for item in items("elements", ("id", "name", "product", "resource_type")) + ) + relationships = tuple( + Relationship(item["id"], item["from"], item["to"], item["kind"]) + for item in items("relationships", ("id", "from", "to", "kind")) + ) + checks = tuple( + Check(item["id"], item["applies_to"], item["statement"], item["source"]) + for item in items("checks", ("id", "applies_to", "statement", "source")) + ) + not_applicable = tuple( + NotApplicable(item["recommendation"], item["reason"]) + for item in items("not_applicable", ("recommendation", "reason")) + ) + + if not elements and not problems: + problems.append(f"{name}.elements: the graph has no Elements") + + seen: set[str] = set() + ids = [thing.id for group in (elements, relationships, checks) for thing in group] + for identifier in ids: + if identifier in seen: + problems.append(f"{name}: id {identifier} is used more than once") + seen.add(identifier) + + element_ids = {element.id for element in elements} + for relationship in relationships: + for end, value in (("from", relationship.source), ("to", relationship.target)): + if value not in element_ids: + problems.append( + f"{name}: Relationship {relationship.id} {end} {value}, " + "which is not an Element" + ) + targets = element_ids | {relationship.id for relationship in relationships} + for check in checks: + if check.applies_to not in targets: + problems.append( + f"{name}: Check {check.id} applies to {check.applies_to}, " + "which is not an Element or Relationship" + ) + checked = {check.applies_to for check in checks} + for element in elements: + if element.id not in checked: + problems.append(f"{name}: Element {element.id} has no Check") + + if problems: + raise GraphError(problems) + return TargetArchitecture(elements, relationships, checks, not_applicable) + + +# --- the Requirements chain through the graph ---------------------------------------- + + +def chain_gaps( + graph: TargetArchitecture, + *, + requirements: Sequence[Mapping[str, Any]], + components: Sequence[Mapping[str, Any]], + products: Sequence[Mapping[str, Any]], + recommendations: Sequence[Mapping[str, Any]], +) -> tuple[str, ...]: + """Every place the Requirements chain stops before reaching a Check. + + A functional requirement is carried by a component that has an Element, or by a + Check of its own. A non-functional requirement and a design recommendation are + each a constraint, so each must be the source of a Check (a recommendation may + instead be marked not applicable, with a reason). A constraint that lists + nothing infrastructure code can show, only what lies outside it, needs none. + """ + gaps: list[str] = [] + requirement_ids = {item["id"] for item in requirements} + recommendation_ids = {item["id"] for item in recommendations} + sources = {check.source for check in graph.checks} + realised = {element.component for element in graph.elements if element.component} + + for check in graph.checks: + if check.source not in requirement_ids | recommendation_ids: + gaps.append( + f"Check {check.id} has source {check.source}, which is not a " + "requirement or design recommendation" + ) + for element in graph.elements: + if element.component and element.component not in {c["id"] for c in components}: + gaps.append( + f"Element {element.id} realises {element.component}, " + "which is not a component" + ) + + for component in components: + if component["id"] not in realised: + gaps.append(f"Component {component['id']} has no Element") + for requirement in requirements: + if requirement["id"] in sources: + continue + served = any( + requirement["id"] in component.get("requirements", ()) + and component["id"] in realised + for component in components + ) + if requirement.get("kind") == "functional" and served: + continue + if _only_outside_code(requirement): + continue + gaps.append(f"Requirement {requirement['id']} has no Check") + for selection in products: + used = any( + element.component == selection["component"] + and element.product == selection["product"] + for element in graph.elements + ) + if not used: + gaps.append( + f"Product {selection['product']} selected for " + f"{selection['component']} appears on no Element" + ) + excused = {item.recommendation for item in graph.not_applicable} + for item in graph.not_applicable: + if item.recommendation not in recommendation_ids: + gaps.append( + f"not_applicable names {item.recommendation}, " + "which is not a design recommendation" + ) + for recommendation in recommendations: + if recommendation["id"] not in sources | excused and not _only_outside_code( + recommendation + ): + gaps.append(f"Recommendation {recommendation['id']} has no Check") + return tuple(gaps) + + +def _only_outside_code(item: Mapping[str, Any]) -> bool: + """Whether a constraint says, explicitly, that nothing it asks for can be shown + by infrastructure code.""" + return item.get("conditions") == [] and bool(item.get("outside_code")) + + +# --- the diagram is a view of the graph ---------------------------------------------- + +_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]') + + +def _label(*parts: str) -> str: + return "
".join(_UNSAFE.sub(" ", part).strip() for part in parts if part) + + +def _node_ids(ids: Iterable[str]) -> dict[str, str]: + """Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects.""" + return {identifier: f"n{index}" for index, identifier in enumerate(ids)} + + +def render_mermaid(graph: TargetArchitecture) -> str: + """The architecture diagram: every Element and Relationship, exactly once.""" + nodes = _node_ids(element.id for element in graph.elements) + lines = ["flowchart LR"] + for element in graph.elements: + lines.append( + f' {nodes[element.id]}["{_label(element.name, element.product)}"]' + ) + for relationship in graph.relationships: + lines.append( + f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| " + f"{nodes[relationship.target]}" + ) + return "\n".join(lines) + "\n" + + +# --- so are the tables a person reviews ---------------------------------------------- + + +def _cell(text: str | None) -> str: + return " ".join((text or "").replace("|", "\\|").split()) + + +def _table( + heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]] +) -> str: + lines = [ + f"## {heading}", + "", + "| " + " | ".join(columns) + " |", + "|" + "|".join(" --- " for _ in columns) + "|", + ] + lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows] + return "\n".join(lines) + + +def render_tables(graph: TargetArchitecture) -> str: + """The graph as markdown tables: what a person approving the design reads. + + Written by code, so the tables cannot disagree with the graph and no model spends + output repeating it. + """ + names = {element.id: element.name for element in graph.elements} + parts = [ + _table( + "Elements", + ("Id", "Name", "Product", "Resource type", "Component"), + ( + (e.id, e.name, e.product, e.resource_type, e.component) + for e in graph.elements + ), + ), + _table( + "Relationships", + ("Id", "From", "Kind", "To"), + ( + (r.id, names[r.source], r.kind, names[r.target]) + for r in graph.relationships + ), + ), + _table( + "Checks", + ("Id", "Applies to", "Statement", "Source"), + ((c.id, c.applies_to, c.statement, c.source) for c in graph.checks), + ), + ] + if graph.not_applicable: + parts.append( + _table( + "Not applicable", + ("Recommendation", "Reason"), + ((n.recommendation, n.reason) for n in graph.not_applicable), + ) + ) + return "\n\n".join(parts) + "\n" diff --git a/app/solution_architecture/work_breakdown.py b/app/solution_architecture/work_breakdown.py new file mode 100644 index 0000000..84b78c6 --- /dev/null +++ b/app/solution_architecture/work_breakdown.py @@ -0,0 +1,559 @@ +"""The work breakdown structure: a plan for building the Target architecture. + +A Specialist divides the build into work packages and activities and estimates each +activity's days. Everything after that is code, as it is for the architecture +diagram: the plan is checked against the design, the schedule is computed from the +days and the dependencies, and the three views a reader sees are written from the +result. So the timeline cannot disagree with the plan, and no part of the design can +be left out of it. + + work packages a hierarchy; each delivers named Elements, and is done when the + Checks on those Elements pass + activities what is done, in which work package, for how many days, after + which other activities, and by whom + schedule each activity's start and finish day, on a relative axis from + Day 0, with no more of the team's activities at once than the + team has people; and the critical path +""" + +from __future__ import annotations + +import datetime as dt +import json +import math +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from typing import Any + +from app.solution_architecture.chain import Upstream, agreed_scope, read_graph + +WORK_BREAKDOWN_FILE = "work-breakdown.json" +TIMELINE_FILE = "timeline.mmd" +DICTIONARY_HEADING = "WBS dictionary" +TEAM, CUSTOMER = "team", "customer" +OWNERS = (TEAM, CUSTOMER) +DEFAULT_TEAM_SIZE = 2 +DEFAULT_WEEK = 5 +MAX_DAYS = 120 # one activity; anything longer is a work package, not an activity +_CHART_WIDTH = 60 + + +@dataclass(frozen=True) +class Scheduled: + id: str + start: float + finish: float + critical: bool + + +def _text(value: Any) -> str: + return " ".join(str(value or "").split()) + + +def _list(value: Any) -> list[str]: + return [str(item) for item in value] if isinstance(value, list) else [] + + +def parse(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]: + """(work packages, activities, problems) from the data file.""" + name = WORK_BREAKDOWN_FILE + try: + data = json.loads(text) + except ValueError as exc: + return [], [], [f"{name}: not valid JSON ({exc})"] + if not isinstance(data, Mapping): + return [], [], [f"{name}: must be an object with work_packages and activities"] + packages = [p for p in data.get("work_packages") or [] if isinstance(p, Mapping)] + activities = [a for a in data.get("activities") or [] if isinstance(a, Mapping)] + return [dict(p) for p in packages], [dict(a) for a in activities], [] + + +def check_work_breakdown( + attachments: Mapping[str, str], upstream: Upstream | None +) -> list[str]: + name = WORK_BREAKDOWN_FILE + packages, activities, problems = parse(attachments.get(name, "")) + if problems: + return problems + if not packages: + return [f"{name}: lists no work packages"] + if not activities: + return [f"{name}: lists no activities"] + + ids = [str(p.get("id", "")) for p in packages] + problems += [f"{name}: a work package has no id"] if "" in ids else [] + problems += [ + f"{name}: work package id {dup} is used more than once" + for dup in sorted({i for i in ids if i and ids.count(i) > 1}) + ] + known = set(ids) + parents = {str(p.get("id")): p.get("parent") for p in packages} + for package in packages: + ident, parent = str(package.get("id")), package.get("parent") + if not _text(package.get("name")): + problems.append(f"{name}: {ident} has no name") + if parent is not None and str(parent) not in known: + problems.append( + f"{name}: {ident} has parent {parent}, which does not exist" + ) + seen, node = {ident}, parent + while node is not None and str(node) in parents: + if str(node) in seen: + problems.append(f"{name}: {ident} is its own ancestor") + break + seen.add(str(node)) + node = parents[str(node)] + + graph = read_graph(upstream) + if graph is not None: + elements = {element.id for element in graph.elements} + covered: set[str] = set() + for package in packages: + listed = _list(package.get("elements")) + covered.update(listed) + problems += [ + f"{name}: {package.get('id')} delivers {element}, which is not an " + "Element of the Target architecture" + for element in listed + if element not in elements + ] + left = sorted(elements - covered) + if left: + problems.append( + f"{name}: no work package delivers {', '.join(left)}; every Element " + "of the Target architecture belongs to one" + ) + + activity_ids = [str(a.get("id", "")) for a in activities] + problems += [ + f"{name}: activity id {dup} is used more than once" + for dup in sorted({i for i in activity_ids if i and activity_ids.count(i) > 1}) + ] + known_activities = set(activity_ids) + with_work = set() + for activity in activities: + ident = str(activity.get("id", "")) + if not ident or not _text(activity.get("name")): + problems.append(f"{name}: an activity needs an id and a name") + continue + within = str(activity.get("work_package", "")) + if within not in known: + problems.append(f"{name}: {ident} is in {within}, not a work package") + with_work.add(within) + days = activity.get("days") + if isinstance(days, bool) or not isinstance(days, (int, float)) or days <= 0: + problems.append(f"{name}: {ident} needs `days`, a number above 0") + elif days > MAX_DAYS: + problems.append( + f"{name}: {ident} is {days} days; split anything over {MAX_DAYS}" + ) + problems += [ + f"{name}: {ident} comes after {before}, which is not an activity" + for before in _list(activity.get("after")) + if before not in known_activities + ] + if activity.get("owner", TEAM) not in OWNERS: + problems.append(f"{name}: {ident} owner must be one of {', '.join(OWNERS)}") + has_children = {str(parent) for parent in parents.values() if parent is not None} + problems += [ + f"{name}: {ident} has no activity and no work package beneath it" + for ident in ids + if ident and ident not in with_work and ident not in has_children + ] + if not problems and _cycle(activities): + problems.append( + f"{name}: activities depend on each other in a circle: " + + " -> ".join(_cycle(activities)) + ) + return problems + + +def _cycle(activities: Sequence[Mapping[str, Any]]) -> list[str]: + """Activities that depend on each other in a circle; empty when none do.""" + after = {str(a["id"]): _list(a.get("after")) for a in activities} + state: dict[str, int] = {} + + def visit(node: str, path: list[str]) -> list[str]: + state[node] = 1 + for before in after.get(node, ()): + if state.get(before) == 1: + return ( + [*path[path.index(before) :], before] + if before in path + else [before, node] + ) + if state.get(before, 0) == 0: + found = visit(before, [*path, before]) + if found: + return found + state[node] = 2 + return [] + + for node in after: + if state.get(node, 0) == 0: + found = visit(node, [node]) + if found: + return found + return [] + + +def schedule( + activities: Sequence[Mapping[str, Any]], team_size: int = DEFAULT_TEAM_SIZE +) -> dict[str, Scheduled]: + """Each activity's start and finish day, from Day 0. + + An activity starts when everything it comes after has finished. The team's own + activities also wait for a free person: no more run at once than `team_size`. + What the customer owns, such as a supplier's lead time, takes nobody from the + team. The critical path is every activity with no slack: delay it and the end + moves. + """ + team_size = max(1, int(team_size)) + by_id = {str(a["id"]): a for a in activities} + after = {ident: _list(a.get("after")) for ident, a in by_id.items()} + days = {ident: float(a["days"]) for ident, a in by_id.items()} + # The longest chain of work that follows an activity: what to start first when + # people are short. + followers: dict[str, list[str]] = {ident: [] for ident in by_id} + for ident, befores in after.items(): + for before in befores: + followers[before].append(ident) + tail: dict[str, float] = {} + + def remaining(ident: str) -> float: + if ident not in tail: + tail[ident] = days[ident] + max( + (remaining(f) for f in followers[ident]), default=0.0 + ) + return tail[ident] + + start: dict[str, float] = {} + finish: dict[str, float] = {} + busy: list[tuple[float, float]] = [] # the team's activities already placed + pending = set(by_id) + while pending: + ready = [i for i in pending if all(b in finish for b in after[i])] + ready.sort(key=lambda i: (-remaining(i), i)) + ident = min( + ready, + key=lambda i: ( + max((finish[b] for b in after[i]), default=0.0), + -remaining(i), + i, + ), + ) + earliest = max((finish[b] for b in after[ident]), default=0.0) + if by_id[ident].get("owner", TEAM) == TEAM: + candidates = sorted({earliest, *(end for _, end in busy if end > earliest)}) + for moment in candidates: + overlapping = sum( + 1 for s, e in busy if s < moment + days[ident] and e > moment + ) + if overlapping < team_size: + earliest = moment + break + busy.append((earliest, earliest + days[ident])) + start[ident], finish[ident] = earliest, earliest + days[ident] + pending.discard(ident) + + end = max(finish.values(), default=0.0) + latest: dict[str, float] = {} + + def latest_finish(ident: str) -> float: + if ident not in latest: + latest[ident] = min( + (latest_finish(f) - days[f] for f in followers[ident]), default=end + ) + return latest[ident] + + return { + ident: Scheduled( + ident, + start[ident], + finish[ident], + critical=latest_finish(ident) - finish[ident] < 1e-6, + ) + for ident in by_id + } + + +# --- what the plan is checked against, from the agreed scope ---------------------------- + + +def _scoped(scope: Mapping[str, Any], path: str) -> Any: + """A field of the agreed scope, stated or assumed; None when it is neither.""" + node: Any = scope.get("stated") or {} + for part in path.split("."): + node = node.get(part) if isinstance(node, Mapping) else None + if node is not None: + return node + for item in scope.get("assumed") or []: + if isinstance(item, Mapping) and item.get("field") == path: + return item.get("value") + return None + + +def delivery_terms(upstream: Upstream | None) -> dict[str, Any]: + """Team size, working week, window and start date, from the agreed scope.""" + scope = agreed_scope(upstream) + + def number(path: str, default: int) -> int: + value = _scoped(scope, path) + ok = ( + isinstance(value, (int, float)) + and not isinstance(value, bool) + and value > 0 + ) + return int(value) if ok else default + + window = _scoped(scope, "delivery.window_weeks") + start = _scoped(scope, "delivery.target_start_date") + try: + start_date = dt.date.fromisoformat(str(start)) if start else None + except ValueError: + start_date = None + return { + "team_size": number("delivery.team_size", DEFAULT_TEAM_SIZE), + "team_size_stated": _scoped(scope, "delivery.team_size") is not None, + "week": number("delivery.working_days_per_week", DEFAULT_WEEK), + "window_weeks": window if isinstance(window, (int, float)) else None, + "start": start_date, + } + + +# --- the three views -------------------------------------------------------------------- + + +def _day(value: float) -> str: + return str(int(value)) if float(value).is_integer() else f"{value:.1f}" + + +def _calendar(start: dt.date, day: float, week: int) -> dt.date: + """The calendar date of a working day counted from `start`.""" + weeks, days = divmod(math.floor(day), week) + return start + dt.timedelta(days=weeks * 7 + days) + + +def render(attachments: Mapping[str, str], upstream: Upstream | None) -> str: + """The WBS dictionary, the activity sequence and the timeline, as markdown + written from the data file. "" when the file cannot be read.""" + packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) + if problems or not packages or not activities: + return "" + terms = delivery_terms(upstream) + plan = schedule(activities, terms["team_size"]) + graph = read_graph(upstream) + checks: dict[str, list[str]] = {} + for check in graph.checks if graph else (): + checks.setdefault(check.applies_to, []).append(check.id) + + parents = {str(p["id"]): p.get("parent") for p in packages} + + def depth(ident: str) -> int: + level, node = 0, parents.get(ident) + while node is not None and str(node) in parents and level < 10: + level, node = level + 1, parents.get(str(node)) + return level + + effort: dict[str, float] = {} + for activity in activities: + effort[str(activity["work_package"])] = effort.get( + str(activity["work_package"]), 0.0 + ) + float(activity["days"]) + + def cell(value: Any) -> str: + return _text(value).replace("|", "\\|") or "-" + + lines = [ + f"## {DICTIONARY_HEADING}", + "", + "Each work package, what it delivers, and the Checks that say it is done.", + "", + "| Id | Work package | Scope | Produces | Elements | Done when these pass | Skills | Days |", + "| --- | --- | --- | --- | --- | --- | --- | --- |", + ] + for package in packages: + ident = str(package["id"]) + elements = _list(package.get("elements")) + accepted = [c for element in elements for c in checks.get(element, [])] + lines.append( + "| " + + " | ".join( + [ + ident, + ("  " * depth(ident)) + cell(package.get("name")), + cell(package.get("scope")), + cell("; ".join(_list(package.get("produces")))), + cell(", ".join(elements)), + cell(", ".join(accepted)), + cell(", ".join(_list(package.get("skills")))), + _day(effort[ident]) if ident in effort else "-", + ] + ) + + " |" + ) + + ordered = sorted(activities, key=lambda a: (plan[str(a["id"])].start, str(a["id"]))) + dated = terms["start"] is not None + lines += [ + "", + "## Activity sequence", + "", + "| Id | Activity | Work package | Days | After | Start | Finish |" + + (" Dates |" if dated else "") + + " Owner | Critical |", + "| --- | --- | --- | --- | --- | --- | --- |" + + (" --- |" if dated else "") + + " --- | --- |", + ] + for activity in ordered: + item = plan[str(activity["id"])] + row = [ + str(activity["id"]), + cell(activity.get("name")), + str(activity.get("work_package")), + _day(float(activity["days"])), + cell(", ".join(_list(activity.get("after")))), + f"Day {_day(item.start)}", + f"Day {_day(item.finish)}", + ] + if dated: + begins = _calendar(terms["start"], item.start, terms["week"]) + ends = _calendar(terms["start"], max(item.finish - 1e-9, 0), terms["week"]) + row.append(f"{begins.isoformat()} to {ends.isoformat()}") + row += [str(activity.get("owner", TEAM)), "yes" if item.critical else ""] + lines.append("| " + " | ".join(row) + " |") + + total = max(item.finish for item in plan.values()) + weeks = total / terms["week"] + lines += [ + "", + "## Timeline", + "", + "```text", + *_chart(ordered, plan, total), + "```", + "", + ] + summary = ( + f"{_day(total)} working days, about {weeks:.1f} weeks, with a team of " + f"{terms['team_size']}" + + ( + "" + if terms["team_size_stated"] + else " (assumed; the scope gives no team size)" + ) + + f" and a {terms['week']}-day week." + ) + lines.append(summary) + window = terms["window_weeks"] + if window is not None: + if weeks <= window + 1e-9: + lines.append( + f"That is inside the {window}-week delivery window, with " + f"{window - weeks:.1f} weeks to spare." + ) + else: + path = [str(a["id"]) for a in ordered if plan[str(a["id"])].critical] + lines.append( + f"**That is {weeks - window:.1f} weeks over the {window}-week delivery " + f"window.** The critical path is {' -> '.join(path)}: only shortening " + "or removing work on it, or adding people where it waits for them, " + "brings the end in." + ) + theirs = [a for a in ordered if a.get("owner", TEAM) == CUSTOMER] + if theirs: + lines += ["", "The customer owns these, and the plan waits on them:"] + lines += [ + f"- {a['id']} {_text(a.get('name'))}: {_day(float(a['days']))} days" + + (f". {_text(a.get('assumption'))}" if _text(a.get("assumption")) else "") + for a in theirs + ] + lines += [ + "", + ( + "Durations are estimates made without knowing the team, and are " + "indicative. Days are working days counted from Day 0, the day work " + "starts; each of the team's activities takes one person." + ), + ] + return "\n".join(lines) + "\n" + + +def _chart( + ordered: Sequence[Mapping[str, Any]], plan: Mapping[str, Scheduled], total: float +) -> list[str]: + """The timeline as text: one row per activity along a relative day axis.""" + scale = min(1.0, _CHART_WIDTH / total) if total else 1.0 + labels = [f"{a['id']} {_text(a.get('name'))}"[:38] for a in ordered] + width = max(len(label) for label in labels) + 2 + step = max(1, math.ceil(total / 6 / 5.0) * 5) + axis = [" "] * (int(total * scale) + 8) + for day in range(0, int(total) + 1, step): + mark = str(day) + at = int(day * scale) + axis[at : at + len(mark)] = mark + rows = [" " * width + "Day " + "".join(axis).rstrip()] + for label, activity in zip(labels, ordered, strict=True): + item = plan[str(activity["id"])] + begin = round(item.start * scale) + length = max(1, round((item.finish - item.start) * scale)) + block = "░" if activity.get("owner", TEAM) == CUSTOMER else "█" + flag = " *" if item.critical else "" + rows.append(f"{label.ljust(width)} {' ' * begin}{block * length}{flag}") + rows += ["", "█ the team ░ the customer * on the critical path"] + return rows + + +def mermaid(attachments: Mapping[str, str], upstream: Upstream | None) -> str: + """A Mermaid Gantt chart on calendar dates, when the scope gives a start date. + "" otherwise: a relative plan has no dates to draw.""" + packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) + terms = delivery_terms(upstream) + if problems or not activities or terms["start"] is None: + return "" + plan = schedule(activities, terms["team_size"]) + names = {str(p["id"]): _text(p.get("name")) for p in packages} + lines = ["gantt", " dateFormat YYYY-MM-DD", " excludes weekends"] + for package in packages: + own = [ + a for a in activities if str(a.get("work_package")) == str(package["id"]) + ] + if not own: + continue + lines.append(f" section {names[str(package['id'])].replace(':', ' ')}") + for activity in sorted(own, key=lambda a: plan[str(a["id"])].start): + item = plan[str(activity["id"])] + begins = _calendar(terms["start"], item.start, terms["week"]) + tag = "crit, " if item.critical else "" + label = _text(activity.get("name")).replace(":", " ") + lines.append( + f" {label} :{tag}{activity['id']}, {begins.isoformat()}, " + f"{max(1, math.ceil(float(activity['days'])))}d" + ) + return "\n".join(lines) + "\n" + + +def summary( + attachments: Mapping[str, str], upstream: Upstream | None +) -> dict[str, Any]: + """The plan in a few numbers, for an Approval and for the Execution's record.""" + packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, "")) + if problems or not activities: + return {} + terms = delivery_terms(upstream) + plan = schedule(activities, terms["team_size"]) + total = max(item.finish for item in plan.values()) + weeks = round(total / terms["week"], 1) + return { + "work_packages": len(packages), + "activities": len(activities), + "working_days": round(total, 1), + "weeks": weeks, + "team_size": terms["team_size"], + "window_weeks": terms["window_weeks"], + "within_window": None + if terms["window_weeks"] is None + else weeks <= terms["window_weeks"], + "critical_path": [i for i, item in plan.items() if item.critical], + } diff --git a/app/solution_architecture/workflow.py b/app/solution_architecture/workflow.py new file mode 100644 index 0000000..ffb9948 --- /dev/null +++ b/app/solution_architecture/workflow.py @@ -0,0 +1,468 @@ +"""Cloud solution architecture, as a Workflow: this agent's subject. + +The graph, the data checks and the samples are the reference agent's, from its +`app/workflows/deliverables.py` and `app/adk/fake_runtime.py`, arranged into one +value by the Execution engine's example of it. +""" + +from __future__ import annotations + +import dataclasses +import functools +import json +from collections.abc import Mapping + +from execution_engine.adk import fake_runtime +from execution_engine.workflows.deliverables import DataCheck, DeliverableSpec +from execution_engine.workflows.workflow import ValidationPolicy, Workflow + +from app.solution_architecture.assessment import assess +from app.solution_architecture.chain import ( + COMPONENTS_FILE, + IMPLEMENTATION_FILE, + PRODUCTS_FILE, + RECOMMENDATIONS_FILE, + REQUIREMENTS_FILE, + SCOPE_DATA_FILE, + SCOPE_FILE, + VERDICTS_FILE, + check_components, + check_implementation, + check_products, + check_recommendations, + check_requirements, + check_scope, + check_target_architecture, + check_verdicts, + graph_structure, + validation_outcome, +) +from app.solution_architecture.changes import check_requirement_changes +from app.solution_architecture.hooks import ( + CARD, + CHANGES, + COVERAGE_REVIEWER, + GRAPH_SHAPE, + GUIDE_FILENAME, + MODULES_OPTION, + PILLAR_ADVISOR, + agreed, + approval_details, + approval_facts, + check_ids, + consultations, + describe_approval, + describe_design, + known_ids, + modules_option, + outputs, + pillar_hints, + prepare_role, + summary_lines, + task_entries, + unimplementable, + with_checklist_review, + with_graph_views, + with_modules_skill, + with_plan_views, +) +from app.solution_architecture.kinds import PHASE_ORDER, DeliverableKind, PhaseId +from app.solution_architecture.pillars import KEPT_FOR_CHANGES +from app.solution_architecture.presentation import to_generate_response +from app.solution_architecture.target_architecture import GRAPH_ATTACHMENT +from app.solution_architecture.work_breakdown import ( + WORK_BREAKDOWN_FILE, + check_work_breakdown, +) + +ABOUT = ( + "I design cloud solution architectures. Tell me, at a high level, what you want " + "built, and I will work through requirements, a target architecture, " + "infrastructure code, validation and a packaged guide, asking for your approval " + "at each Phase. Nothing was started for this message." +) + + +_K = DeliverableKind + +DEPENDENCY_GRAPH: Mapping[str, DeliverableSpec] = { + spec.kind: spec + for spec in ( + DeliverableSpec( + _K.SCOPE, + PhaseId.SCOPING, + "scope-analyst", + sections=("Scope statement",), + # The completed scope spec, for people and for reuse; and what every + # later Specialist reads of it. + attachments=(SCOPE_FILE, SCOPE_DATA_FILE), + ), + DeliverableSpec( + _K.REQUIREMENTS, + PhaseId.REQUIREMENTS_DISCOVERY, + "requirements-analyst", + depends_on=(_K.SCOPE,), + sections=( + "Functional requirements", + "Non-functional requirements", + "Current state", + "Dependencies", + ), + attachments=(REQUIREMENTS_FILE,), + ), + DeliverableSpec( + _K.TECHNICAL_DECOMPOSITION, + PhaseId.REQUIREMENTS_DISCOVERY, + "decomposer", + depends_on=(_K.REQUIREMENTS,), + sections=("Components",), + attachments=(COMPONENTS_FILE,), + ), + DeliverableSpec( + _K.PRODUCT_SELECTION, + PhaseId.SOLUTION_ARCHITECTURE, + "product-selector", + depends_on=(_K.TECHNICAL_DECOMPOSITION,), + sections=("Products and features mapping",), + attachments=(PRODUCTS_FILE,), + ), + DeliverableSpec( + _K.DESIGN_RECOMMENDATIONS, + PhaseId.SOLUTION_ARCHITECTURE, + "design-advisor", + depends_on=(_K.PRODUCT_SELECTION, _K.REQUIREMENTS), + sections=( + "Security, privacy, and compliance", + "Reliability", + "Operational excellence", + "Cost optimization", + "Performance efficiency", + "Sustainability", + ), + attachments=(RECOMMENDATIONS_FILE,), + ), + DeliverableSpec( + _K.TARGET_ARCHITECTURE, + PhaseId.SOLUTION_ARCHITECTURE, + "target-architect", + depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS), + # The Specialist writes the reasoning and the graph. On submission the + # engine adds the Elements, Relationships and Checks tables to the content + # and architecture.mmd to the attachments, both rendered from the graph. + sections=("Design rationale",), + attachments=(GRAPH_ATTACHMENT,), + graph=GRAPH_SHAPE, + ), + DeliverableSpec( + _K.ARCHITECTURE_DESCRIPTION, + PhaseId.SOLUTION_IMPLEMENTATION, + "describer", + depends_on=(_K.TARGET_ARCHITECTURE,), + sections=("Components", "Flow"), + # It describes the Elements and how they connect. A Revision that only + # adds or rewords Checks leaves it true. + written_from=graph_structure, + ), + DeliverableSpec( + _K.DEPLOYMENT_GUIDANCE, + PhaseId.SOLUTION_IMPLEMENTATION, + "iac-author", + depends_on=(_K.TARGET_ARCHITECTURE,), + sections=( + "Deployment prerequisites", + "Step-by-step deployment instructions", + ), + attachments=( + "terraform/main.tf", + "terraform/variables.tf", + IMPLEMENTATION_FILE, + ), + # The graph is all the code is written from. + reads_in_full=(), + not_shown=( + _K.REQUIREMENTS, + _K.TECHNICAL_DECOMPOSITION, + _K.PRODUCT_SELECTION, + _K.DESIGN_RECOMMENDATIONS, + ), + working_copy=_K.DEPLOYMENT_GUIDANCE, + ), + DeliverableSpec( + _K.VALIDATION_RESULTS, + PhaseId.SOLUTION_VALIDATION, + "validator", + depends_on=(_K.DEPLOYMENT_GUIDANCE,), + sections=("Deployment dry-run", "Architecture and policy analysis"), + attachments=(VERDICTS_FILE,), + # It judges the code against the Checks; the prose describing the + # design is not what it judges. + not_shown=(_K.ARCHITECTURE_DESCRIPTION,), + working_copy=_K.DEPLOYMENT_GUIDANCE, + ), + DeliverableSpec( + _K.WORK_BREAKDOWN, + PhaseId.PACKAGING, + "delivery-planner", + depends_on=(_K.VALIDATION_RESULTS,), + sections=("Approach",), + attachments=(WORK_BREAKDOWN_FILE,), + # A plan covers the design and how it is built: the graph and the code. + reads_in_full=(_K.TARGET_ARCHITECTURE, _K.DEPLOYMENT_GUIDANCE), + not_shown=( + _K.REQUIREMENTS, + _K.DESIGN_RECOMMENDATIONS, + _K.ARCHITECTURE_DESCRIPTION, + ), + ), + DeliverableSpec( + _K.SOLUTION_GUIDE, + PhaseId.PACKAGING, + "packager", + depends_on=(_K.VALIDATION_RESULTS,), + sections=( + "Executive summary and workload overview", + "Requirements and current state", + "Technical decomposition of the workload", + "Proposed solution architecture", + "Design and configuration recommendations", + "Deployment guidance", + "Validation plan", + "References", + ), + # The guide is assembled from every Deliverable's prose. + reads_in_full=tuple(_K)[:-1], + ), + ) +} + +# What each data file along the Requirements chain must hold, checked at submission. +DATA_CHECKS: Mapping[str, tuple[str, DataCheck]] = { + _K.SCOPE: (SCOPE_DATA_FILE, check_scope), + _K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements), + _K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components), + _K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products), + _K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations), + _K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture), + _K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation), + _K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts), + _K.WORK_BREAKDOWN: (WORK_BREAKDOWN_FILE, check_work_breakdown), +} + + +# Sections code appends to a Deliverable for the person reading it. A Specialist +# working from that Deliverable has the same facts as data, and is not shown them. +FOR_READERS: Mapping[str, str] = { + _K.DESIGN_RECOMMENDATIONS: "Architecture framework checklist review", +} + + +# One small, coherent Requirements chain, so sample submissions pass every link. +SAMPLE_DATA: dict[str, str] = { + "scope.yaml": "engagement:\n kind: workload\nintent:\n statement: Accept events.\n", + "scope.json": json.dumps( + { + "kind": "workload", + "stated": {"intent": {"statement": "Accept events."}}, + "to_decide": [], + "to_ask": [], + "not_applicable": [], + } + ), + "requirements.json": json.dumps( + [ + {"id": "FR-1", "kind": "functional", "text": "Accept events."}, + { + "id": "NFR-1", + "kind": "non_functional", + "text": "99.9% availability.", + "conditions": ["The service stays available when one instance fails."], + }, + ] + ), + "components.json": json.dumps( + [{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}] + ), + "products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]), + "recommendations.json": json.dumps( + [ + { + "id": "DR-1", + "pillar": "security", + "text": "Use a dedicated identity.", + "components": ["C-1"], + "conditions": ["The service runs as an identity nothing else uses."], + } + ] + ), + "target-architecture.json": json.dumps( + { + "elements": [ + { + "id": "E-1", + "name": "Ingress service", + "component": "C-1", + "product": "Example Run", + "resource_type": "example_run_service", + }, + { + "id": "E-2", + "name": "Ingress identity", + "product": "Example IAM", + "resource_type": "example_service_account", + }, + ], + "relationships": [ + {"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"} + ], + "checks": [ + { + "id": "K-1", + "applies_to": "E-1", + "statement": "The service runs at least two instances.", + "source": "NFR-1", + }, + { + "id": "K-2", + "applies_to": "E-2", + "statement": "The identity is used by this service only.", + "source": "DR-1", + }, + ], + } + ), + "implementation.json": json.dumps( + [ + {"check": "K-1", "file": "terraform/main.tf", "address": "example.run"}, + {"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"}, + ] + ), + "work-breakdown.json": json.dumps( + { + "work_packages": [ + { + "id": "WP-1", + "name": "Ingress", + "parent": None, + "elements": ["E-1", "E-2"], + "scope": "The service and its identity.", + "produces": ["a running service"], + "skills": ["platform engineering"], + } + ], + "activities": [ + { + "id": "A-1", + "work_package": "WP-1", + "name": "Create the identity", + "days": 1, + "after": [], + }, + { + "id": "A-2", + "work_package": "WP-1", + "name": "Deploy the service", + "days": 2, + "after": ["A-1"], + }, + ], + } + ), + "verdicts.json": json.dumps( + { + "dry_run": {"verdict": "pass", "evidence": "terraform validate passed."}, + "checks": [ + {"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."}, + {"check": "K-2", "verdict": "pass", "evidence": "One binding."}, + ], + "proposed_additions": [], + } + ), +} + + +def _approval_details(phase, deliverables, baseline): + return approval_details( + phase, + deliverables, + baseline, + in_phase=[ + str(kind) for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase == phase + ], + design_phase=PhaseId.SOLUTION_ARCHITECTURE, + ) + + +WORKFLOW = Workflow( + name="solution-architecture", + about=ABOUT, + phases=tuple(PHASE_ORDER), + deliverables=DEPENDENCY_GRAPH, + final=_K.SOLUTION_GUIDE, + data_checks=DATA_CHECKS, + baseline_checks={_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirement_changes)}, + for_readers=FOR_READERS, + spec_deliverable=_K.SCOPE, + validation=ValidationPolicy( + kind=_K.VALIDATION_RESULTS, + data_file=VERDICTS_FILE, + implementation=_K.DEPLOYMENT_GUIDANCE, + design=_K.TARGET_ARCHITECTURE, + read=validation_outcome, + check_ids=check_ids, + unimplementable=unimplementable, + known_ids=known_ids, + ), + on_submit={ + _K.DESIGN_RECOMMENDATIONS: with_checklist_review, + _K.WORK_BREAKDOWN: with_plan_views, + _K.TARGET_ARCHITECTURE: with_graph_views, + }, + approval_details=_approval_details, + approval_facts=approval_facts, + summary_lines=summary_lines, + agreed=agreed, + changes=CHANGES, + subject="a cloud solution architecture", + describe_design=describe_design, + prepare_role=prepare_role, + task_entries=task_entries, + task_hints=pillar_hints(), + kept_for_changes=tuple(KEPT_FOR_CHANGES), + final_file=GUIDE_FILENAME, + outputs=outputs, + assess=assess, + options={MODULES_OPTION: modules_option(available=False, default=False)}, + card=CARD, + done="The solution architecture is complete and approved.", + describe_approval=describe_approval, + response=to_generate_response, + roles=(PILLAR_ADVISOR,), + optional_roles=(COVERAGE_REVIEWER,), + adjust_roles=with_modules_skill, + samples=SAMPLE_DATA, +) + + +def with_pillars( + pillar_skills: Mapping[str, str], workflow: Workflow = WORKFLOW +) -> Workflow: + """The Workflow for a provider bundle's pillar Skills: one advisor for each.""" + return dataclasses.replace(workflow, role_tools=consultations(pillar_skills)) + + +def with_modules( + available: bool, default: bool = False, workflow: Workflow = WORKFLOW +) -> Workflow: + """The Workflow for a provider that does, or does not, approve module sources.""" + return dataclasses.replace( + workflow, options={MODULES_OPTION: modules_option(available, default)} + ) + + +# The Reference's tests call these as functions of its one graph. +inputs_of = WORKFLOW.inputs_of +dependencies_for = WORKFLOW.dependencies_for +shown = WORKFLOW.shown +deliverables_in = WORKFLOW.deliverables_in +check_submission = WORKFLOW.check_submission +sample_submission = functools.partial(fake_runtime.sample_submission, WORKFLOW) diff --git a/docs/adr/0001-langgraph-orchestrates-phases-not-google-adk.md b/docs/adr/0001-langgraph-orchestrates-phases-not-google-adk.md new file mode 100644 index 0000000..c88fab3 --- /dev/null +++ b/docs/adr/0001-langgraph-orchestrates-phases-not-google-adk.md @@ -0,0 +1,14 @@ +--- +status: superseded by ADR-0003 +--- + +# LangGraph orchestrates Phases, not Google ADK + +Phases are orchestrated by a LangGraph `StateGraph`, as the KAB Workflow Agent standard (`kyndryl-agent-builder/docs/KAB_WORKFLOW_AGENT_IMPLEMENTATION_GUIDE.md`) requires, rather than by Google ADK `Runner`/`LoopAgent`. The earlier "ADK" orchestration was a local compatibility layer that never used the real `google-adk` package, so it added a pretend seam with one adapter and diverged from the platform standard; we deleted it. Real ADK remains welcome *inside* a Phase (e.g. an `LlmAgent` for LLM-driven design) — just not as the thing that sequences Phases. + +> **Reopened (2026-09-15).** [ADR-0002](0002-skills-are-the-portable-unit-of-behaviour.md) makes Skills, loaded by a framework's own skill runtime, the portable unit of behaviour. This ADR assumed our code sequences the Phases. If the Skill sequences them instead, the choice here reduces to which skill runtime to wire first, and "ADK only inside a Phase" no longer holds. Still true regardless: the compat stubs are fiction and should go. + +## Considered Options + +- **Real `google-adk` as orchestrator**: rejected; departs from the KAB workflow standard and would require async event-stream plumbing for no capability LangGraph lacks (conditional edges cover the Review round). +- **Plain in-process pipeline, no framework**: rejected; neither KAB template uses it, and LangGraph already gives us conditional routing and a path to checkpointing if a human approval gate is added later. diff --git a/docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md b/docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md new file mode 100644 index 0000000..3e1884f --- /dev/null +++ b/docs/adr/0002-skills-are-the-portable-unit-of-behaviour.md @@ -0,0 +1,25 @@ +--- +status: accepted +--- + +# Skills are the portable unit of behaviour + +This agent exists to replace the [`google-cloud-solution-architecture`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-solution-architecture/SKILL.md) skill with an agent that runs anywhere. Its solution-architecture behaviour lives in Skills that follow the [Agent Skills specification](https://agentskills.io/specification) (`SKILL.md` plus `references/`, `assets/` and `scripts/`). The agent framework's own skill runtime loads them: Google ADK's `SkillToolset`, or LangChain's skills pattern (Deep Agents `skills=` / `SkillsMiddleware`). Our code supplies the tooling those Skills call on: grounding, IaC validation and environment scanning. It doesn't restate the work the Skills describe. + +Google Cloud is the first and, for now, only Cloud provider. Other hyperscalers should be addable as new Skills plus new tooling, without rewriting the agent's core. + +## Refinements (2026-09-15) + +- **Hybrid sequencing.** Our code owns Phase boundaries and the Approvals between Phases. Within a Phase, the Skill, run by the skill runtime, decides the work. We rejected letting the Skill sequence everything: Phase checkpoints give us resumable, recordable, testable progress. We rejected code-owned Phase bodies because they would bypass the Skill. +- **Hierarchical and ReAct, not linear.** Work isn't a fixed chain. Agents are organised in a hierarchy that follows the dependencies between Deliverables. Work whose dependencies are satisfied may proceed independently, and every agent reasons and acts in a ReAct loop of thought, tool call and observation. An Orchestrator sits above one Specialist per Deliverable, and a Specialist fans out further only where its work splits into independent parts. Code declares the dependency graph, and the Orchestrator chooses what to do next within it. The engine is recorded in [ADR-0003](0003-langgraph-holds-state-adk-agents-reason.md). +- **Interactive by default.** Executions are multi-turn with user Approval, as the upstream Skill requires. A pre-approved mode serves batch and evaluation runs. +- **Vendored upstream Skill.** `google-cloud-solution-architecture` is copied unmodified and pinned to an upstream commit. Our additions live in separate Skills for our own tooling, so upstream changes arrive as a diff. +- **Discovery through the provider's own MCP servers.** Current-state discovery and documentation grounding go through the remote MCP servers each Cloud provider hosts, for example Google Cloud's Resource Manager, Asset Inventory, Compute, GKE and Developer Knowledge servers, and the AWS MCP Server. Code carries no hand-written cloud API clients. Only reviewed read-only MCP tools are exposed, and reading a user's cloud requires their permission. +- **Cloud provider as configuration.** A Cloud provider is a configured bundle of Skills, tools and remote MCP servers. There's no provider interface in code until a second Cloud provider exists, but core module names carry no provider prefix. + +## Consequences + +- Framework-specific code is confined to wiring a skill runtime and registering tools, so moving to another framework is a new wiring, not a rewrite. +- Skills in `app/skills/` must conform to the specification: kebab-case `name` matching the directory, a `description` of when to use the Skill, and no custom `phase:` key. They don't today. (2026-10-06: those five Skills were deleted with the original pipeline. The engine loads only the conforming Skills under `skills/`, and `app/skills/` holds the discovery and validation code.) +- This reopens [ADR-0001](0001-langgraph-orchestrates-phases-not-google-adk.md) and the Phase pipeline spec (`.scratch/phase-pipeline/spec.md`). [ADR-0003](0003-langgraph-holds-state-adk-agents-reason.md) settles the engine and supersedes ADR-0001. +- Both known skill runtimes are young: ADK marks Skills *Experimental* (Python ≥ 1.25.0), and Deep Agents skills are new. Pin versions. diff --git a/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md b/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md new file mode 100644 index 0000000..90c6c7b --- /dev/null +++ b/docs/adr/0003-langgraph-holds-state-adk-agents-reason.md @@ -0,0 +1,27 @@ +--- +status: accepted +supersedes: ADR-0001 +--- + +# LangGraph holds Execution state; ADK agents reason and act + +An Execution is a hierarchy of ReAct agents shaped by the dependencies between Deliverables ([ADR-0002](0002-skills-are-the-portable-unit-of-behaviour.md)). + +- **LangGraph holds the Execution.** A LangGraph `StateGraph` holds the dependency graph and each Deliverable's state. It checkpoints after every step and pauses with `interrupt()` whenever the user must answer or approve. This follows the KAB workflow standard and the platform's `langgraph-workflow-agent`. +- **ADK agents reason and act.** The Orchestrator and every Specialist is an ADK `LlmAgent`, each running its own ReAct loop, with a `SkillToolset` for progressive Skill loading. This follows the platform's `google-adk-base-agent/app/skills_integration.py`. +- **Agents sit behind one interface.** Each agent runs behind a single agent-runtime interface, so LangChain Deep Agents can be added as a second implementation without touching the graph. + +The dependency graph is declared as data in code. The Orchestrator picks what to do next through tools that refuse work whose dependencies aren't met. Dependencies are guaranteed by code, while ordering and parallelism are the model's choice. + +> **Amended (2026-10-07) by [ADR-0007](0007-jev-is-the-orchestrators-decision-point.md), accepted.** The Orchestrator is now a router: it decides by readings and a playbook in code, with Jev for the judgements, and runs no language model to choose an action. That replaces "the Orchestrator ... is an ADK `LlmAgent`" above and reverses the third option rejected below. Specialists are unaffected and still reason on language models. + +## Considered Options + +- **ADK end to end** (root `LlmAgent` with `sub_agents`/`AgentTool`, and ADK sessions for pauses): rejected. It departs from the KAB workflow standard, and LangGraph's checkpointed `interrupt()` is the proven platform path for resumable user Approvals. +- **Deep Agents end to end** (`create_deep_agent(skills=, subagents=)`): viable, and it compiles to LangGraph. It was deferred rather than rejected: ADK `SkillToolset` already has working prior art on this platform, and Deep Agents stays reachable as the second implementation of the agent-runtime interface. +- **Code runs the dependency graph with no Orchestrator model**: rejected. The top level wouldn't be ReAct, and the Skill's conversational flexibility (such as skipping work the user says is already approved) would need hand-coding. + +## Consequences + +- There are two frameworks in one process. Framework types stay inside the agent-runtime implementation and never appear in graph state. +- ADK Skills are *Experimental* (Python ≥ 1.25.0), so pin the version. diff --git a/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md b/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md new file mode 100644 index 0000000..7b37cdd --- /dev/null +++ b/docs/adr/0004-lessons-and-overlays-arrive-as-skills.md @@ -0,0 +1,46 @@ +--- +status: accepted +--- + +# Lessons and overlays arrive as Skills + +An Execution starts clean ([CONTEXT.md](../../CONTEXT.md)) unless it is a Change request with a named Baseline ([ADR-0006](0006-a-change-request-starts-from-a-baseline-execution.md)), so nothing one Execution learns may flow into the next as hidden state. What an Execution gets wrong is still worth keeping. We decide that everything that changes how agents behave between Executions is a Skill change, of one of two kinds. + +- **Lessons.** Each Execution records **lesson candidates**: Revisions and their reasons, validator findings, tool refusals, the user's change requests, and work that stopped. An offline curator proposes lessons from candidates across Executions. A person approves each one. An approved lesson is added to a lessons Skill that the provider bundle assigns to roles. +- **Overlays.** An organisation's standards or one engagement's constraints are written as their own Skills. The provider bundle lists the ones every Execution loads. A caller may name further overlay Skills when it starts an Execution. + +Vendored Skills stay unmodified ([ADR-0002](0002-skills-are-the-portable-unit-of-behaviour.md)); lessons and overlays sit beside them. + +## Decisions + +Accepted by the owner on 2026-10-08, agreeing to each of these: + +1. **No lesson takes effect without a person's approval.** The curator proposes; it never edits a Skill that agents load. We prefer slower learning to an agent that rewrites its own instructions. +2. **A lesson must be shown to help.** It is kept only if the evaluation, run with and without it, holds quality and lowers Revisions, time or tokens. +3. **Lessons are per Cloud provider.** The lessons Skill is listed in that provider's bundle, since most lessons name its products. +4. **Overlay Skills come only from directories the deployment configures.** A caller names an overlay by its Skill name; it cannot upload one. Each passes the same Agent Skills validation as bundled Skills, and an unknown name refuses the Execution at the start. +5. **Every Execution records the Skills it loaded and a content hash of each,** so a result can be traced to the instructions that produced it. +6. **Lesson candidates are client data.** They quote user feedback and name resources. They are stored with the Execution's records, never in the repository, and a lesson is written so that it carries no client detail. + +## Considered Options + +- **Memory carried between Executions** (a vector store of past Deliverables or feedback, retrieved at run time): rejected. It breaks "every Execution starts clean", can leak one client's content into another's Execution, and cannot be reviewed or rolled back as a diff. +- **Automatic Skill edits** (the curator applies lessons directly): rejected for now. Without review, one bad Execution can degrade every later one, and nothing ties a regression to its cause. +- **Editing the vendored Skills in place**: rejected by ADR-0002. Upstream changes must arrive as a clean diff. +- **Overlays as prompt text passed by the caller**: rejected. Free text bypasses Skill validation and progressive loading, and it is an injection path. + +## Consequences + +- Learning is slow by design: a lesson reaches agents only after capture, proposal, review and an evaluation run. +- The evaluation must be able to see a difference a Skill makes. Its structural checks cannot, so the judged checks and the thresholds on Revisions, time and tokens become part of the loop. +- The glossary gains **Lesson candidate**, **Lesson** and **Overlay Skill**. +- Skills can no longer be loaded once at start-up for all Executions: the runtime must resolve a role's Skills per Execution. + +## As built (2026-10-09) + +Two points differ from the text above; the decisions stand. + +- **Default overlays are a deployment setting, not part of the provider bundle.** `DEFAULT_OVERLAY_SKILLS` names the overlays every Execution loads. Whose standards apply belongs to the deployment and the caller, not to a Cloud provider. +- **Skills are still loaded once at start-up.** The runtime loads every provider Skill and every overlay in the configured folders when it starts, and an Execution chooses among them. An overlay added to a folder needs a restart. + +Decision 2 has a first result: on one benchmark case run each way, the lessons held quality and removed a Revision. One lesson was retired because the fault was in a review, not in the agents. diff --git a/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md b/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md new file mode 100644 index 0000000..89475fe --- /dev/null +++ b/docs/adr/0005-the-target-architecture-is-an-explicit-graph.md @@ -0,0 +1,49 @@ +--- +status: accepted +--- + +# The target architecture is an explicit graph, and code comes after it + +Today the design passes from Specialist to Specialist as prose, and the infrastructure code is written before anyone has stated what it must satisfy. In an evaluation run on 2026-10-06 the validator found 4 problems, then 7, then 5 different ones, across three Revisions of the same Terraform: the bar was discovered after the code existed, and it moved. We decide that the **Target architecture** is one explicit graph, held as data, that is established before any infrastructure code is written, and that everything after it is derived from it and checked against it. + +The graph has three kinds of thing: + +- **Elements**: every component of the solution and the resource that realises it, with the product selected for it. +- **Relationships**: how Elements connect: calls, publishes to, reads from, is granted access to. +- **Checks**: on each Element and Relationship, the numbered, verifiable conditions it must meet. Each Check names the requirement or design recommendation it comes from. + +This makes the **Requirements chain** explicit: every requirement leads to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. A link that is missing is refused, not discovered later. + +## Who provides what + +The user states what they want to achieve, at a high level, in the Workflow request, and answers the questions that only they can answer. The agents produce everything in the graph: every Element, Relationship and Check is derived by Specialists from the requirements, the Cloud provider's architecture framework and its documented best practices. The user never writes or edits the graph. They approve it, from a summary, before code is written. + +## What changes + +- **A new Deliverable, the Target architecture,** follows product selection and design recommendations. Its graph is an attachment; its content is the readable summary. +- **Completeness is a submission rule.** The Target architecture is refused when a requirement, a selected product or a design recommendation has no Element or Check, or when a Relationship or Check refers to an Element that is not in the graph. +- **Later Deliverables are views of the graph.** The architecture diagram is rendered from its Elements and Relationships. The architecture description describes them. The deployment guidance implements every Element, Relationship and Check. +- **Validation is a verdict per Check,** pass or fail with evidence, not a list the validator composes on each pass. Something the validator notices that the graph lacks is a proposed addition to the Target architecture. It cannot fail the code. If it matters, the Target architecture is revised, and the code follows. + +## Decisions + +Accepted by the owner on 2026-10-07, with each of these: + +1. **The user approves the Target architecture before code is written.** The solution architecture Phase splits in two: design, which ends with the Target architecture, and implementation, which holds the deployment guidance. The upstream Skill has four Phases; this makes five, and is a deliberate departure from it. +2. **A new Specialist produces the Target architecture.** The design advisor stays responsible for recommendations only. +3. **Code renders the diagram from the graph.** No model draws it, so the picture cannot disagree with the architecture, and the diagrammer role goes. + +## Considered Options + +- **Keep the prose chain and tighten the validator's instructions**: rejected. The validator would still decide what to check after the code exists, and nothing would make two passes agree. +- **A build plan for the infrastructure code only**, beside the architecture: rejected. It would be a second description of the same system, free to drift from the diagram and the description. The graph has to be the architecture itself. +- **Let the infrastructure code be the model** and derive the diagram and checks from Terraform: rejected. It puts code first, which is the order that failed, and it ties the architecture to one infrastructure-as-code tool. +- **Raise the Revision limit**: rejected. It spends more on a loop that has no fixed target. + +## Consequences + +- Requirements reach code through data, not prose, so a requirement that nothing implements is caught when the Target architecture is submitted. +- A Revision either closes a known Check or it does not. Validation findings stop growing between passes. +- More is decided before code: the Specialist that writes the Target architecture carries work the infrastructure author and validator did implicitly, and a gap in the graph now costs a Revision of the Target architecture and everything after it. +- The Phase list is no longer the upstream Skill's. The solution guide still follows the upstream template; only where Approvals fall changes. +- The vocabulary of the graph is part of the glossary: Target architecture, Element, Relationship, Check, Requirements chain. "Dependency" keeps its existing meaning, between Deliverables. diff --git a/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md b/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md new file mode 100644 index 0000000..67e9402 --- /dev/null +++ b/docs/adr/0006-a-change-request-starts-from-a-baseline-execution.md @@ -0,0 +1,40 @@ +--- +status: accepted +--- + +# A change request starts from a baseline Execution + +A user's requirements change after an architecture has been delivered. They need to say what has changed, at a high level, and get the architecture updated, not rebuilt from nothing with no link to what was agreed before. Today that is impossible by design: every Execution starts clean, and a Session or Customer case only groups Executions. We decide that a caller may start an Execution as a **Change request** against a **Baseline**: a completed Execution of the same Customer case. The new Execution begins from the Baseline's approved Deliverables and the user's description of what has changed, and it delivers a full, updated set plus a statement of what changed and why. + +This is the one, explicit exception to "every Execution starts clean". It is named by the caller, limited to the same Customer case, and recorded in the Execution's manifest. Nothing flows between Executions unless a Baseline is named. + +## How a Change request runs + +- **The user says what changed,** in the Workflow request, at the same high level as an original request: "retention goes from 30 days to 7 years", "it must now also serve a second region". It becomes the next statement in the Customer case's Intent history. +- **The agents work out the consequences.** The requirements analyst revises the Baseline's requirements, keeping every id that still holds and marking each requirement added, changed or removed. Each later Specialist starts from the Baseline's version of its Deliverable and changes only what the changed requirements reach. +- **The Requirements chain shows the reach.** Because requirements, components, Elements and Checks carry ids ([ADR-0005](0005-the-target-architecture-is-an-explicit-graph.md)), a changed requirement leads to the Elements and Checks it touches. Everything it does not reach is carried over unchanged. +- **The user approves the change, not the whole.** Each Approval shows what was added, changed and removed against the Baseline. +- **Validation covers every Check,** carried over or new, so an unchanged part that a change has broken is still caught. + +## Decisions + +Accepted by the owner on 2026-10-07, with each of these: + +1. **A Change request is a new Execution,** with its own id, Approvals and files. The Baseline is never modified, so every delivered version of a Customer case's architecture remains on record. +2. **The Baseline must be a completed Execution of the same Customer case.** One case can never start from another's work. +3. **The output is complete, not a patch.** A Change request delivers the full updated Deliverables and a change summary, so the latest Execution of a case always stands on its own. +4. **A Change request may itself be a Baseline,** so a case's Executions form a line of versions. + +## Considered Options + +- **Reopen the completed Execution** and revise its Deliverables in place: rejected. It destroys the record of what was delivered and approved, and an Execution that never ends cannot be audited. +- **Start clean and ask the user to restate everything** with the change included: rejected. It loses every decision and Approval already made, changes parts nobody asked to change, and gives no account of what differs. +- **Carry context automatically within a Customer case:** rejected. Hidden carry-over is what "starts clean" exists to prevent; the caller must choose the Baseline. +- **Deliver only a diff** of the Deliverables: rejected. The reader would have to assemble the current architecture from a chain of patches. + +## Consequences + +- "Every Execution starts clean" becomes "every Execution starts clean unless the caller names a Baseline". The glossary entries for Execution, Session and Customer case change to say so, and gain **Change request** and **Baseline**. +- This depends on ADR-0005. Without ids along the Requirements chain there is nothing to trace a change through, and a Change request would be a rewrite with extra context. +- A Change request against a Baseline produced by older Skills is revised under the Skills loaded now; the change summary can therefore include changes the user did not ask for. They must be shown as such. +- Lesson candidates gain a strong signal: what users change after delivery. diff --git a/docs/adr/0007-jev-is-the-orchestrators-decision-point.md b/docs/adr/0007-jev-is-the-orchestrators-decision-point.md new file mode 100644 index 0000000..c49c7ed --- /dev/null +++ b/docs/adr/0007-jev-is-the-orchestrators-decision-point.md @@ -0,0 +1,90 @@ +--- +status: accepted +--- + +# Jev is the Orchestrator's decision point, and the Orchestrator is a router + +[ADR-0003](0003-langgraph-holds-state-adk-agents-reason.md) made the Orchestrator a reasoning agent on a large language model. In practice its turns are slow and mostly mechanical: in the evaluation run of 2026-10-06 it took about 7 of 35 minutes, and stalled four times before doing the only thing available. We decide that the Orchestrator follows the agent-control pattern Vercel describes for Jev ([Jev in AI agent loops](https://vercel.com/i/jev-agent-control)): Jev, a decision model that answers typed questions with probabilities, proposes the next action; application code checks that it is allowed, carries it out and records it; a generative model only writes what the user reads. Specialists are unchanged: they still reason and write on language models. + +## Who owns what + +| Responsibility | Owner in the pattern | Here | +|---|---|---| +| Interpret the request | A model with supplied context | The requirements analyst and the Specialists after it | +| Propose the next action | The decision model | Jev, asked typed questions about the Execution's state | +| Check permission | Application code | The Ledger: Dependencies, Approvals, the Revision limit, the cloud-read gate | +| Execute the action | The tool runner | The Orchestrator's existing tools, called by code | +| Update state | Application code | The Execution graph and its checkpoint | +| Explain the result | A generative model | One small model call that writes an Approval summary or a question, from data it is given | + +## The Orchestrator is a router + +With Jev as its decision point, the Orchestrator's job is routing: it reads what has arrived and the state of the Execution, asks Jev which route applies, and dispatches. It does no work of its own. There are four routes to choose. + +| What is routed | The routes Jev chooses between | Who is dispatched | +|---|---|---| +| A message that starts something | a new Workflow request; a Change request against a Baseline; a question about work already delivered; not something this agent does | a full Execution; an Execution from the Baseline; the reply writer, from the delivered files; a polite refusal | +| A message inside an Execution | an answer to a waiting question; a request to change submitted work, and which Deliverable; anything else | the Specialist that asked; a Revision of that Deliverable; a question back to the user | +| A validation outcome | revise the code; revise the Target architecture; proceed | the IaC author; the target architect; the Approval | +| Ready work, in a Change request | which Deliverables the change reaches, and which carry over from the Baseline unchanged | only the Specialists whose Deliverables are reached | + +Which Specialist produces a given Deliverable is still fixed by the dependency graph: Jev chooses the route, never the worker for it. And the Ledger still refuses a route whose Dependencies or Approvals are not met. + +## How a turn is decided: readings, disposition, playbook + +The owner's model for this is a four-stage pipeline: readings of what arrived, a disposition worked out in code, further readings of the state, and a playbook that takes the first group that applies and, within it, the strongest action whose conditions hold, escalating when no group applies. + +1. **Readings.** Facts about the turn. Most are read from the Ledger and the Execution's data by code: are questions waiting, is a Phase complete, is work ready, which Checks failed, did a Check fail twice running. The ones that need judgement are typed answers from Jev: is the user asking for a change (yes or no), which Deliverable would have to change first (a choice), how specific are they (a score), does a gap in the Target architecture leave a requirement unmet (yes or no). Jev reads; it never picks the action. +2. **Disposition.** Code turns a judged reading into act, queue or close by threshold: a probability of 0.75 or more is acted on, 0.15 or less is dropped, and anything between is put to the user. A choice with confidence under 0.6 is not relied on. The thresholds are settings. +3. **Playbook.** Ordered groups; the first that applies is taken, and within it the strongest action whose conditions hold: + + | Group | Actions, strongest first | + |---|---| + | The user asked for a change | revise the Deliverable it affects; else ask them to confirm which and what | + | Questions are waiting | relay them | + | Validation decided | revise the Target architecture (a Check failed twice running, or a gap that matters); else revise the code (a Check failed); else ask about the gaps; else proceed | + | A Phase is complete | request its Approval | + | Work is ready | delegate all of it | + | Packaging is approved | finish | + | No group applies | escalate: ask the user, or end with warnings when there is none | + +4. **Permission.** Every action goes through the Orchestrator's tools, so the Ledger refuses what is not allowed whatever was decided, and the playbook then takes the next action that is. A typed answer can still be wrong. +5. **Record.** Each decision is kept in the Execution's state: the turn, the group, the action and what Jev answered with its confidence. +6. **Reply.** A generative model writes only what the user reads, the summary they approve a Phase from, out of data it is given. It runs after the decision and cannot change it. When it fails, the summary is assembled from the same data. + +A failed call to Jev is not an answer. The client returns nothing, and the reading falls back to a rule that acts only on what is certain: a change is acted on when the Deliverable is named outright, and a gap is revised for when it names a real requirement or cannot be verified. + +## Decisions + +Accepted by the owner on 2026-10-07, with each of these: + +1. **No language model decides what the Orchestrator does.** Jev reads, and the playbook in code decides. A generative model writes user-facing text only. This replaces the part of ADR-0003 that makes the Orchestrator a reasoning agent. +2. **Low confidence goes to the user, not to another model.** Below a decision's threshold, an interactive Execution asks the user in plain terms; a pre-approved one takes the safest allowed action and records a warning. +3. **Jev being unreachable does not stop an Execution.** After a fixed retry budget the Orchestrator falls back to the fixed order of its seven steps, in code, and records that it did. +4. **What is sent to Jev is the Execution's state, not its content:** Deliverable names and statuses, Check ids and verdicts, and the user's latest message. Deliverable text and discovered cloud data are not sent for an Orchestrator decision. +5. **The Orchestrator routes; Jev chooses the route.** That covers what kind of work a message starts, where a message inside an Execution goes, where a validation outcome goes, and, in a Change request, which Deliverables are reached. Jev never chooses which Specialist produces a Deliverable: the dependency graph fixes that. +6. **In a new Execution every Deliverable is still produced.** Routing does not skip a Specialist for a new Workflow request, because each later Deliverable is checked against the ones before it. Skipping happens only in a Change request, where the Baseline supplies what is carried over. + +## Considered Options + +- **A smaller language model as Orchestrator:** rejected by the owner. It keeps the slow, open-ended turn and the stalls, at lower cost. +- **No generative model at all, with fixed wording for summaries and questions:** this ADR's first draft. Rejected to follow the pattern, which pairs Jev with a generative model for replies: an Approval summary is what a person decides from and reads better written than assembled. +- **Code only, with fixed rules:** rejected. It cannot tell what a user's free-text reply is asking for. +- **Code for the mechanical steps and the existing model for judgement:** rejected in favour of one decision point. It keeps two ways of deciding and the large model in the loop. + +## Consequences + +- Jev is reached through TypeSafe AI's Python SDK, `typesafe-sdk`, pinned exactly (owner, 2026-10-07). `app/tools/jev.py` is the only module that imports it. +- The Orchestrator as a language-model agent is kept behind the setting `ORCHESTRATOR=model`, for the tests that drive the Ledger's rules in arbitrary order and for comparing the two in an evaluation. The default is `router`. Remove the setting once the router is proven. + +- The Orchestrator's instructions in `agents/orchestrator.md` become the wording of Jev's questions and the brief for the reply writer, held in a Skill or the provider bundle so they stay reviewable and portable. +- Jev becomes a dependency of every interactive Execution. Its availability, latency, rate limits and data retention must be known before this is built; none is documented publicly. +- Decisions become measurable: each has a confidence, so thresholds can be tuned from recorded Executions. +- An unusual request that fits none of the questions is handled by asking the user, where a language model might have improvised. + +## As built (2026-10-09) + +- **Jev is used beyond the Orchestrator.** It also chooses the pillars a change touches and the Skill references a Specialist reads first, checks remote MCP replies and the user's text for instructions aimed at the agent, tells a rewording from a change, and scores each Execution's design recommendations. Each has a fallback in code and is a setting. +- **Decision 4 covers Orchestrator decisions only.** These other uses do send content: design recommendations, Check and Element text, remote MCP replies and the Workflow request. Jev's data retention is therefore a question about Deliverable content, and it is still unanswered by the vendor. +- **Jev did not become a hard dependency.** Without a key, or when a call fails, every decision takes its fallback and the Execution continues. +- **The fourth route, which Deliverables a change reaches, is decided in code** from the changed requirements and the Requirements chain, not by Jev. diff --git a/docs/adr/0008-scoping-starts-from-a-scope-spec.md b/docs/adr/0008-scoping-starts-from-a-scope-spec.md new file mode 100644 index 0000000..bcad489 --- /dev/null +++ b/docs/adr/0008-scoping-starts-from-a-scope-spec.md @@ -0,0 +1,59 @@ +--- +status: accepted +--- + +# Scoping starts from a scope spec + +An Execution began from the customer's request, a sentence or two saved word for word, and the requirements analyst filled everything else with assumptions. Most of what went wrong downstream traced to what nobody had stated, and nothing told the customer how much of their design rested on assumption. We decide that an engagement is scoped from a **scope spec**: a structured file that states what the customer wants and the facts a design depends on, which may arrive complete, partly filled or not at all, and which the customer approves before requirements begin. + +The Intent stays the customer's own words. The scope spec sits beside it as the agreed, structured form. + +## What the spec is + +- **A file of fields from a catalogue.** A Skill holds the catalogue: each field's type, when it must be settled, the question to ask for it, and guidance for a default. The catalogue names no Cloud provider. A provider's bundle supplies the allowed values for the fields it leaves to a provider, in that provider's terms. +- **Every field says one of four things.** A value is the customer's statement. `ask`, or the field left out, means not known. `decide` leaves the choice to the agent, recorded as an assumption. `not_applicable` asks and assumes nothing. +- **Whether a field is settled is read by code.** No model decides what is missing. +- **Fields are essential, important or optional,** and which is which depends on the kind of engagement: a workload, a platform foundation or a migration. +- **It carries the customer's own words and requirements:** the statement verbatim, the requirements they stated with their own ids, and what they excluded. +- **It carries how to run the agent,** so one file starts an Execution. + +## Decisions + +Accepted by the owner on 2026-10-11, with each of these: + +1. **The file supplied is never altered.** The agent writes a completed copy beside it, with what it assumed, what is still unknown, where each value came from, and a status. +2. **A choice the customer states binds the design.** A product, a topology or a setting written in the spec is a constraint every Specialist honours. The rule that requirements name no products is about what the agents introduce, not what the customer has already decided. +3. **A platform foundation is in scope,** alongside the application workloads the agent was built on. +4. **An engagement and a Customer case are the same thing.** A spec may name either; an engagement reference is turned into the case's id. +5. **The spec is provider-agnostic in shape.** Provider vocabulary enters only as values a provider's bundle allows. +6. **An essential field that is not settled refuses a start that has nobody to ask.** With someone present it is asked for. +7. **Scoping becomes a Phase the customer approves,** before requirements discovery. +8. **Where the spec and a prose request disagree, the spec wins.** + +## Considered Options + +- **Judge the free-text request against a list of topics** with a model or Jev: the first proposal. Rejected once a spec was on the table: a field that is filled or not is a fact, and a judgement about prose is not. +- **One file the agent completes in place:** rejected. An author must be able to see that what they wrote is what was used. +- **Keep product names out of the spec, as out of requirements:** rejected. A customer who has decided on an interconnect or a named appliance has stated a constraint; refusing to record it would lose it. +- **A separate spec for platform foundations:** rejected. One catalogue with tiers by kind serves both, and a migration is usually some of each. + +## Consequences + +- The Requirements chain gains a start: a requirement traces to the customer's own requirement id or to a spec field. +- The requirements analyst stops being where questions are asked and assumptions made. That moves to scoping. +- A Change request may be an edited spec, compared field by field in code. +- An evaluation case may be a spec, in place of answers matched by pattern. +- The glossary gains **Scope spec** and **Scoping**, and Customer case says that an engagement is the same thing. +- A platform foundation is new work for the agents. It needs its own evaluation case before it is relied on. +- The spec holds client names and details. Like lesson candidates it is client data: kept with the Customer case, never in the repository, apart from the fictional benchmark specs. + +This is built in stages; `.agents/plans/iter-09-scoping/` says which are done. + +## As built (2026-10-12) + +- Built: the catalogue and reading a spec in code; scoping as the first Phase, completed in conversation or by assumption; a spec drafted from a sentence; a stated choice refused unless a requirement carries it; the status following the Execution; a Change request starting from the delivered scope. +- **Answers are given in conversation.** Supplying an edited file part-way through is not handled. +- **A Change request is still stated in prose.** Comparing an edited spec with the delivered one, field by field, is not built. +- **Exclusions are not checked in code.** They are free text; the Specialists are told, and in the first landing-zone run they complied. +- **An organisation's standards are not part of the spec.** They still arrive as overlay Skills ([ADR-0004](0004-lessons-and-overlays-arrive-as-skills.md)). Carrying them in the spec as stated requirements was discussed on 2026-10-12 and left undecided; it would amend that ADR. +- A platform foundation has run twice with real models, as `case-08-landing-zone`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..3524904 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,51 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the codebase. + +## Before exploring, read these + +- **`CONTEXT.md`** at the repo root, or +- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo (most repos): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +Multi-context repo (presence of `CONTEXT-MAP.md` at the root): + +``` +/ +├── CONTEXT-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..0209a19 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,30 @@ +# Issue tracker: Local Markdown + +Issues and specs for this repo live as markdown files in `.scratch/`. + +## Conventions + +- One feature per directory: `.scratch//` +- The spec is `.scratch//spec.md` +- Implementation issues are one file per ticket at `.scratch//issues/-.md`, numbered from `01`, never a single combined tickets file +- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings) +- Comments and conversation history append to the bottom of the file under a `## Comments` heading + +## When a skill says "publish to the issue tracker" + +Create a new file under `.scratch//` (creating the directory if needed). + +## When a skill says "fetch the relevant ticket" + +Read the file at the referenced path. The user will normally pass the path or the issue number directly. + +## Wayfinding operations + +Used by `/wayfinder`. The **map** is a file with one **child** file per ticket. + +- **Map**: `.scratch//map.md` (the Notes / Decisions-so-far / Fog body). +- **Child ticket**: `.scratch//issues/NN-.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`. +- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`. +- **Frontier**: scan `.scratch//issues/` for files that are open, unblocked, and unclaimed; first by number wins. +- **Claim**: set `Status: claimed` and save before any work. +- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..b716855 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Triage Labels + +The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. + +Edit the right-hand column to match whatever vocabulary you actually use. diff --git a/docs/operations/mcp-access.md b/docs/operations/mcp-access.md new file mode 100644 index 0000000..219606a --- /dev/null +++ b/docs/operations/mcp-access.md @@ -0,0 +1,68 @@ +# Remote MCP access: Google Cloud + +How to give the solution architect agent safe, read-only access to Google Cloud's hosted MCP servers. The servers the agent uses, and the only tools it may call on each, are listed in [`providers/gcp.yaml`](../../providers/gcp.yaml). + +## How the agent limits itself + +- **Allowlist.** An agent is only ever offered tools named in a server's `allow` list. Every other tool on the server is invisible to it. +- **Read-only check at startup.** If any allowlisted tool doesn't declare `readOnlyHint: true`, the agent refuses to start. +- **Content excluded.** Tools that return data content are excluded even though they are read-only: Cloud SQL `execute_sql_readonly`, Cloud Storage `read_object`/`read_text`/`list_objects`, and generic Kubernetes reads that can return Secrets (`get_k8s_resource`, `describe_k8s_resource`). +- **Permission per Execution.** Tools that read your environment (`cloud_read`) run only after the user grants permission in that Execution. Pre-approved Executions deny it unless the caller passes `allow_cloud_read=true`, in the request or in the scope spec's `run` section. When it is denied, the cloud-read tools are not offered to the agents at all. + +- **Replies are checked.** When Jev is configured, a server's reply that reads as instructions to the agent, as opposed to information, is withheld from the Specialist and logged (`JEV_GUARDRAIL`). Without Jev, replies pass through. + +These are defence in depth. Enforce read-only access in Google Cloud as well. + +## Set up a project the agent may read + +1. **Enable the APIs** of the products you want discovered. A product's MCP endpoint is available once its API is enabled, for example `compute.googleapis.com`, `container.googleapis.com`, `run.googleapis.com`, `sqladmin.googleapis.com`, `pubsub.googleapis.com`, `cloudasset.googleapis.com`, `monitoring.googleapis.com` and `networkmanagement.googleapis.com`. A disabled API shows up as a recorded discovery gap, not a failure. +2. **Create a dedicated service account** for the agent, and grant it only: + - `roles/mcp.toolUser`, to call MCP tools + - `roles/viewer`, or narrower viewer roles for the products in scope + - `roles/cloudasset.viewer`, for asset inventory and IAM analysis +3. **Deny read-write tool calls** for every principal with an IAM deny policy. Save the policy as `policy.json`: + + ```json + { + "rules": [ + { + "denyRule": { + "deniedPrincipals": ["principalSet://goog/public:all"], + "deniedPermissions": ["mcp.googleapis.com/tools.call"], + "denialCondition": { + "title": "Deny read-write tools", + "expression": "api.getAttribute('mcp.googleapis.com/tool.isReadOnly', false) == false" + } + } + } + ] + } + ``` + + Then attach it to the project: + + ```bash + gcloud iam policies create mcp-deny-policy \ + --attachment-point=cloudresourcemanager.googleapis.com/projects/PROJECT_ID \ + --kind=denypolicies \ + --policy-file=policy.json + ``` + +4. **Give the agent credentials.** It authenticates with Application Default Credentials: the attached service account on Cloud Run or GKE, or `GOOGLE_APPLICATION_CREDENTIALS` locally. Set `MCP_QUOTA_PROJECT` when quota should be charged to a project other than the credentials' project. + +For local development, `gcloud auth application-default login` supplies ADC for your user. + +## Reviewing the allowlists + +Upstream tool sets change. To review them: + +1. Refresh the snapshot. `tools/list` works without credentials, and the script lists tools without calling any: + + ```bash + .venv/bin/python scripts/list-mcp-tools.py gcp --json --no-auth > providers/reviews/gcp-mcp-tools.json + ``` + +2. Read the diff. For each new read-only tool, decide whether it returns inventory or configuration metadata (allow it) or data content or secrets (leave it out). +3. Update the `allow` lists in `providers/gcp.yaml`. `tests/test_providers.py` fails if an allowlisted tool is missing from the snapshot or isn't read-only. + +Last reviewed 2026-09-16, against all 12 servers. diff --git a/eval/datasets/judge/calibration.json b/eval/datasets/judge/calibration.json new file mode 100644 index 0000000..562f245 --- /dev/null +++ b/eval/datasets/judge/calibration.json @@ -0,0 +1,20 @@ +{ + "runs": 3, + "questions": 32, + "labelled": 0, + "judges": { + "jev": { + "answered": 32, + "stability": 1.0, + "agreement_with_labels": null, + "mean_answer": 0.37 + }, + "gemini": { + "answered": 32, + "stability": 0.92, + "agreement_with_labels": null, + "mean_answer": 0.32 + } + }, + "between_judges": 0.91 +} diff --git a/eval/datasets/judge/case-02-design-recommendations.md b/eval/datasets/judge/case-02-design-recommendations.md new file mode 100644 index 0000000..ee56333 --- /dev/null +++ b/eval/datasets/judge/case-02-design-recommendations.md @@ -0,0 +1,44 @@ +# Design Recommendations + +This document outlines the architectural configurations and best practices applied to the components of the high-scale data ingestion pipeline. These recommendations integrate the functional and non-functional requirements (NFRs) with guidance from the Google Cloud Well-Architected Framework pillar advisors to ensure a secure, reliable, cost-optimized, and high-performing system. + +## Security, privacy, and compliance + +To protect the ingestion endpoint from volumetric DDoS attacks and Layer 7 exploits, a Global External Application Load Balancer with Google Cloud Armor is deployed. This fulfills the requirement for strict perimeter isolation while serving the 10,000 RPS traffic over TLS 1.2+ (**DR-1**). + +The architecture implements a zero-trust model where all internal pipeline components (Cloud Run, Pub/Sub, Cloud Storage, BigQuery) communicate privately via VPC Service Controls and direct VPC egress (**DR-3**). All processes run under dedicated, least-privilege IAM service accounts, tightly binding permissions to only the required resources (**DR-4**). To meet regulatory data protection mandates and ensure cryptographic sovereignty, all persistent data across the Pub/Sub staging buffer, Cloud Storage sink, and BigQuery quarantine store is encrypted with Customer-Managed Encryption Keys (CMEK) (**DR-2**). + +## Reliability + +Reliability is anchored on minimizing data loss (RPO 0) and avoiding systemic failures under heavy load. The ingestion endpoint mitigates the risk of cold-start latency spikes by maintaining a minimum instance baseline, allowing it to sustainably absorb traffic bursts without violating the 200ms p95 latency target (**DR-5**). + +Within the asynchronous pipeline, downstream processing degradation is isolated from ingestion. The Pub/Sub validation subscription utilizes a dead-letter policy with bounded delivery attempts (5 retries) to redirect unparseable poison-pill messages to BigQuery, preventing queue head-of-line blocking (**DR-6**). Additionally, the valid record storage sink leverages multi-region replication and object versioning to guarantee data durability even during a regional outage or accidental deletion event (**DR-7**). Finally, the Cloud Run services utilize explicit startup and liveness probes to ensure traffic is only routed to healthy, fully-initialized containers (**DR-8**). + +## Operational excellence + +A foundational principle of operational excellence is reproducible, reviewable, and automated changes. Every pipeline component—from IAM bindings to Pub/Sub schemas and serverless runtimes—is defined declaratively as Infrastructure as Code (Terraform) (**DR-9**). This declarative approach acts as the primary recovery mechanism to satisfy the RTO < 60 minutes disaster recovery objective. + +## Cost optimization + +Cost optimizations prioritize scaling tightly with business demand. Both the Ingestion and Validation Cloud Run services are configured to allocate CPU only during request processing, meaning they incur zero compute costs when idle, perfectly matching the strict scale-to-zero requirement (**DR-10**). + +Storage costs are minimized through aggressive lifecycle management. The Pub/Sub buffer retains messages only for a shortened 48-hour window, as RPO=0 durability is fulfilled by the downstream sinks (**DR-11**). The Cloud Storage bucket transitions older validated batches to Nearline storage after 30 days (**DR-12**), and the BigQuery dead-letter quarantine datasets enforce a 30-day automated partition expiration to prevent unbound storage accumulation of malformed payloads (**DR-13**). + +## Performance efficiency + +To sustain the 10,000 RPS throughput requirement with sub-second latencies, the pipeline leverages advanced serverless execution features. Both Cloud Run services use Execution Environment Gen 2 and Startup CPU Boost to optimize network packet processing and eliminate initialization drag (**DR-14**). The Ingestion service's concurrency is explicitly tuned to handle high parallel request volumes (e.g., 80 concurrent requests per instance), preventing excessive container scale-out thrashing (**DR-15**). + +Between the buffer and the processing tier, the Validation Engine relies on a Pub/Sub push subscription to immediately invoke the validation containers, minimizing pull polling overhead and reducing end-to-end event latency (**DR-16**). + +## Sustainability + +To minimize the workload's carbon footprint, all services are provisioned together within a Google Cloud region boasting a high Carbon-Free Energy (CFE) score (e.g., `europe-west1` or `us-central1`) (**DR-17**). + +Energy waste is further curtailed by enforcing schema compliance at the initial Pub/Sub buffer boundary, dropping malformed payloads early and preventing wasted validation compute cycles (**DR-19**). Lastly, the Quarantine Replay Processor is architected as an on-demand Cloud Run Job rather than an always-on polling consumer, aligning energy expenditure directly to actual remediation activity (**DR-18**). + +## Assumptions + +As this design was produced in pre-approved mode, the following assumptions were made: +- **Cloud Region Selection**: We assume the selection of a specific region (like `europe-west1` or `us-central1`) will balance the multi-zone availability requirements with the high CFE targets for sustainability. +- **Micro-batching**: We assume the Validation Engine service includes internal micro-batching logic to aggregate records before writing to Cloud Storage, avoiding excessive single-object API calls that could degrade performance. +- **Trace Sampling & Logging**: Observability costs will be governed by sampling Cloud Trace ingestion and filtering out routine Cloud Run health check (`/healthz`) logs out-of-band via standard project sinks. \ No newline at end of file diff --git a/eval/datasets/judge/case-03-design-recommendations.md b/eval/datasets/judge/case-03-design-recommendations.md new file mode 100644 index 0000000..50485b7 --- /dev/null +++ b/eval/datasets/judge/case-03-design-recommendations.md @@ -0,0 +1,56 @@ +# Design Recommendations + +## Assumptions + +Since `pre_approved` is `true`, the following assumptions govern these design recommendations: +- The workload is deployed regionally in a low-carbon region (a region with CFE% >= 75%) to meet sustainability goals. +- Cloud SQL for PostgreSQL is configured in a high-availability (multi-zone) topology to meet the 99.9% uptime requirement, avoiding cross-region replication. +- Cloud Run handles the compute scaling, scaling down to 0 instances outside of business hours to optimize costs. +- The Corporate Identity Provider integrates with Identity-Aware Proxy (IAP) to authenticate users at the load balancer. +- All application and operational logs are stored in a centralized Google Cloud Storage bucket locked for 365 days. + +## Security, privacy, and compliance + +To enforce a zero-trust model and meet security, privacy, and compliance requirements, the architecture implements several layers of defense: + +- **Identity-Aware Proxy (IAP)**: Protects the Cloud Run service by authenticating corporate users at the external load balancer before traffic reaches the application (DR-2). +- **Network Security**: The Load Balancer enforces a custom SSL policy restricting traffic to TLS 1.2+ (DR-1). The Cloud Run service itself restricts ingress to `internal-and-cloud-load-balancing` so it cannot be accessed directly via the public internet (DR-3). Outbound traffic from Cloud Run is routed strictly through the VPC using Direct VPC Egress (DR-4). +- **Least Privilege and Secrets**: Cloud Run operates using a dedicated, user-managed service account (DR-5) with permissions limited to accessing necessary secrets from Secret Manager (DR-8) and connecting to the database. These secrets are injected dynamically into the runtime environment (DR-9). +- **Database Security**: Cloud SQL is isolated from the public internet by disabling public IPv4 and connecting via Private Service Connect/VPC peering (DR-6). It enforces IAM authentication and SSL/TLS connections (DR-7). +- **Compliance Logging**: To meet the 365-day immutable audit log requirement, a Cloud Logging sink routes all audit events to a dedicated Cloud Storage bucket configured with a 365-day retention policy (DR-10). + +## Reliability + +High availability and disaster recovery are essential to meeting the 99.9% uptime and RTO/RPO requirements: + +- **High Availability**: Cloud SQL for PostgreSQL is configured for regional high availability, maintaining a synchronous standby replica in a secondary zone to allow automatic failover during a disruption (DR-11). +- **Disaster Recovery**: Automated daily backups are retained for at least 7 days, and Point-in-Time Recovery (PITR) is enabled via Write-Ahead Logging (WAL) to guarantee an RPO of 1 hour or less (DR-12). +- **Health Checking**: The load balancer utilizes backend health checks to continuously monitor the health of the Cloud Run instances, routing traffic away from degraded containers (DR-13). + +## Operational excellence + +Operations are streamlined through comprehensive observability and automated alerting: + +- **Monitoring and Alerting**: Cloud Monitoring captures metrics across all components. Alert policies are specifically configured to trigger when Cloud Run HTTP 5xx error rates exceed 1% over a 5-minute window, and when Cloud SQL CPU or storage utilization exceeds 80% (DR-16). +- **Centralized Logs**: All system metrics, application logs, and traces are centralized within Google Cloud's operations suite for rapid incident response. + +## Cost optimization + +The architecture leverages serverless characteristics to align cloud spend with active business usage: + +- **Scale to Zero**: Cloud Run is configured with a minimum instance count of 0, ensuring that compute resources scale down entirely during off-hours, weekends, and periods of inactivity, drastically reducing idle costs (DR-14). +- **Right-sized Database**: While high availability is required, autoscaling storage ensures that database disk space is only paid for when consumed. + +## Performance efficiency + +Sub-second page loads and transactional consistency are maintained through optimized storage and networking: + +- **Database Performance**: Cloud SQL is provisioned with high-throughput SSD storage and automatic storage expansion to maintain low-latency read/write operations for booking transactions without hitting IOPS ceilings (DR-15). +- **Connection Optimization**: By using VPC-native private connections and keeping all traffic within the same region, network latency between Cloud Run and Cloud SQL is minimized. + +## Sustainability + +Environmental impact is mitigated by selecting the right region and eliminating idle resource waste: + +- **Low-Carbon Region**: All resources are deployed in a region with a Carbon-Free Energy (CFE) score of 75% or higher, directly lowering the gross carbon emissions of the workload (DR-17). +- **Dynamic Scaling**: Utilizing Cloud Run's scale-to-zero capabilities (DR-14) ensures that the application does not consume power for idle compute instances outside of business hours. \ No newline at end of file diff --git a/eval/datasets/judge/labels.json b/eval/datasets/judge/labels.json new file mode 100644 index 0000000..d3d4ac6 --- /dev/null +++ b/eval/datasets/judge/labels.json @@ -0,0 +1,226 @@ +[ + { + "id": "case-02-design-recommendations.security.0", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Shift-left security: Are automated security scans integrated into the CI/CD pipeline?", + "label": null + }, + { + "id": "case-02-design-recommendations.security.1", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Zero trust: Is Cloud Identity used as a centralized identity provider for managing user lifecycles and federation?", + "label": null + }, + { + "id": "case-02-design-recommendations.reliability.2", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? Game days or chaos engineering practices are regularly held to validate failure recovery.", + "label": null + }, + { + "id": "case-02-design-recommendations.reliability.3", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? The system architecture incorporates patterns like circuit breakers, retries with exponential backoff, and rate limiting to support graceful degradation.", + "label": null + }, + { + "id": "case-02-design-recommendations.operational-excellence.4", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Operational readiness: A formal framework or set of criteria exists to assess operational readiness before production deployment.", + "label": null + }, + { + "id": "case-02-design-recommendations.operational-excellence.5", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Culture of improvement: A documented strategy is in place for regularly reviewing and adapting cloud operations to industry advancements.", + "label": null + }, + { + "id": "case-02-design-recommendations.cost-optimization.6", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Network Egress: Data transfer is minimized by keeping traffic regional, using **Cloud CDN**, and leveraging **Standard Network Tier** where appropriate. High-volume on-premises traffic uses **Direct Peering** or **Cloud Interconnect** (always verify if hybrid connectivity is involved).", + "label": null + }, + { + "id": "case-02-design-recommendations.cost-optimization.7", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Granular Visibility: BigQuery billing export is enabled and used for regular cost reviews.", + "label": null + }, + { + "id": "case-02-design-recommendations.performance-optimization.8", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Monitoring and continuous improvement: Automated dashboards and alerts are configured for key performance indicators (KPIs).", + "label": null + }, + { + "id": "case-02-design-recommendations.performance-optimization.9", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Elasticity: The architecture leverages serverless or managed services to dynamically match capacity to load.", + "label": null + }, + { + "id": "case-02-design-recommendations.sustainability.10", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Cloud sustainability: AI is used as a catalyst for profitability and resilience to streamline operations, or sustainability is integrated into the design process to create positive feedback loops.", + "label": null + }, + { + "id": "case-02-design-recommendations.sustainability.11", + "document": "case-02-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Continuously measure and improve: Applications are instrumented to measure the specific carbon intensity of software features, or automated exports of Carbon Footprint data to BigQuery are configured for deep analysis.", + "label": null + }, + { + "id": "case-02-design-recommendations.quality.specific", + "document": "case-02-design-recommendations.md", + "kind": "graded", + "text": "Are the recommendations specific to this workload and its stated requirements, as opposed to generic best practice that would fit any workload?", + "label": null + }, + { + "id": "case-02-design-recommendations.quality.actionable", + "document": "case-02-design-recommendations.md", + "kind": "graded", + "text": "Does each recommendation name the concrete setting, feature or configuration to apply, so an engineer could act on it without more research?", + "label": null + }, + { + "id": "case-02-design-recommendations.quality.trade_offs", + "document": "case-02-design-recommendations.md", + "kind": "graded", + "text": "Where pillars pull in different directions (for example cost against reliability), is the trade-off named and a resolution recommended?", + "label": null + }, + { + "id": "case-02-design-recommendations.quality.traceable", + "document": "case-02-design-recommendations.md", + "kind": "graded", + "text": "Can each recommendation be traced to a requirement or constraint of the workload?", + "label": null + }, + { + "id": "case-03-design-recommendations.security.16", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Zero trust: Are private connectivity methods (Cloud Interconnect, VPN) used for internal traffic?", + "label": null + }, + { + "id": "case-03-design-recommendations.security.17", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Security by design: Is defense-in-depth implemented at the network, host, and application layers?", + "label": null + }, + { + "id": "case-03-design-recommendations.reliability.18", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? The architecture avoids single points of failure through cross-zone or cross-region redundancy.", + "label": null + }, + { + "id": "case-03-design-recommendations.reliability.19", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? Application and infrastructure health checks are configured to trigger automated failovers.", + "label": null + }, + { + "id": "case-03-design-recommendations.operational-excellence.20", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Resource optimization: Resource utilization is regularly reviewed using recommendations from Active Assist or performance data.", + "label": null + }, + { + "id": "case-03-design-recommendations.operational-excellence.21", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Operational readiness: A formal framework or set of criteria exists to assess operational readiness before production deployment.", + "label": null + }, + { + "id": "case-03-design-recommendations.cost-optimization.22", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Rightsizing: Resources are regularly adjusted based on rightsizing suggestions provided by Active Assist Recommender.", + "label": null + }, + { + "id": "case-03-design-recommendations.cost-optimization.23", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Granular Visibility: BigQuery billing export is enabled and used for regular cost reviews.", + "label": null + }, + { + "id": "case-03-design-recommendations.performance-optimization.24", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Elasticity: Auto-scaling rules are configured and validated to handle variable demand.", + "label": null + }, + { + "id": "case-03-design-recommendations.performance-optimization.25", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Monitoring and continuous improvement: Distributed tracing and profiling tools are used to identify code-level bottlenecks.", + "label": null + }, + { + "id": "case-03-design-recommendations.sustainability.26", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Cloud sustainability: AI is used as a catalyst for profitability and resilience to streamline operations, or sustainability is integrated into the design process to create positive feedback loops.", + "label": null + }, + { + "id": "case-03-design-recommendations.sustainability.27", + "document": "case-03-design-recommendations.md", + "kind": "yes_no", + "text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Promote a culture of sustainability: Abstract carbon metrics are transformed into tangible progress indicators in annual reports, or sustainability is treated as a first-class technical requirement (NFR) tied to KPIs and performance reviews.", + "label": null + }, + { + "id": "case-03-design-recommendations.quality.specific", + "document": "case-03-design-recommendations.md", + "kind": "graded", + "text": "Are the recommendations specific to this workload and its stated requirements, as opposed to generic best practice that would fit any workload?", + "label": null + }, + { + "id": "case-03-design-recommendations.quality.actionable", + "document": "case-03-design-recommendations.md", + "kind": "graded", + "text": "Does each recommendation name the concrete setting, feature or configuration to apply, so an engineer could act on it without more research?", + "label": null + }, + { + "id": "case-03-design-recommendations.quality.trade_offs", + "document": "case-03-design-recommendations.md", + "kind": "graded", + "text": "Where pillars pull in different directions (for example cost against reliability), is the trade-off named and a resolution recommended?", + "label": null + }, + { + "id": "case-03-design-recommendations.quality.traceable", + "document": "case-03-design-recommendations.md", + "kind": "graded", + "text": "Can each recommendation be traced to a requirement or constraint of the workload?", + "label": null + } +] diff --git a/eval/datasets/solution_cases.json b/eval/datasets/solution_cases.json new file mode 100644 index 0000000..b4697fc --- /dev/null +++ b/eval/datasets/solution_cases.json @@ -0,0 +1,565 @@ +[ + { + "id": "case-01-event-driven-http", + "name": "Event-driven regional webhook ingestion", + "workflow_request": "Design an event-driven regional HTTP application on Google Cloud that accepts incoming webhooks, validates their signatures, durably enqueues payloads for asynchronous processing, and retains raw events for 30 days for replay and audit.", + "required_products": [ + "Cloud Run", + "Pub/Sub", + "Cloud Storage" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west2 (London). Data must stay in the UK." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover", + "99.9% monthly availability. RTO 1 hour, RPO 5 minutes for accepted events. No multi-region DR in phase one." + ], + [ + "traffic|volume|throughput|scale|peak|requests per|rps|payload", + "Average 50 webhooks per second, peaks of 500 per second for 10 minutes. Payloads up to 256 KB." + ], + [ + "latency|response time|performance", + "Acknowledge each webhook within 300 ms at p95." + ], + [ + "security|compliance|encrypt|privacy|gdpr|pci|access|identity|auth", + "UK GDPR applies. Google-managed encryption keys are acceptable. Senders sign requests with HMAC-SHA256 shared secrets; only processing services may read events." + ], + [ + "cost|budget|spend", + "Under 1,500 GBP a month at average load; prefer pay-per-use." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "This is a new workload; nothing runs today." + ], + [ + "depend|integrat|downstream|upstream|consum", + "Processed events go to an existing internal REST API that is reachable over HTTPS; it can be slow or unavailable for minutes." + ], + [ + "operat|monitor|logging|alert|team|support", + "A small platform team of three uses Terraform and wants managed services and Cloud Monitoring alerts." + ], + [ + "sustainab|carbon", + "Prefer low-carbon regions when there is no other constraint, but the UK residency requirement wins." + ], + [ + "retention|replay|audit|archive", + "Keep raw events 30 days, then delete. Replay must be possible for any event in that window." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "thresholds": { + "revisions": 2, + "seconds": 3000, + "tokens": 5000000 + } + }, + { + "id": "case-02-high-scale-ingestion", + "name": "High-scale containerised data ingestion pipeline", + "workflow_request": "Create a high-scale containerised data ingestion pipeline on Google Cloud with least-privilege service identities and automated validation of incoming records.", + "required_products": [ + "Pub/Sub", + "Cloud Storage", + "BigQuery" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "us-central1, single region." + ], + [ + "source|producer|incoming|where.*data|format|schema", + "About 200 IoT gateways send JSON records over HTTPS; each record has a published JSON schema version." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover", + "99.5% availability; RTO 4 hours, RPO 15 minutes. Losing accepted records is not acceptable." + ], + [ + "traffic|volume|throughput|scale|peak|records per|rps|size", + "2 TB a day, about 20,000 records per second at peak, records under 10 KB." + ], + [ + "latency|fresh|real.?time|batch", + "Records must be queryable for analytics within 5 minutes of arrival." + ], + [ + "security|compliance|encrypt|privacy|access|identity|auth|least", + "No regulated data. Each component gets its own service account with least privilege; gateways authenticate with per-device credentials." + ], + [ + "validat|invalid|reject|quarantine|dead", + "Invalid records go to a quarantine location with the validation error, and are reprocessable after a fix." + ], + [ + "cost|budget|spend", + "Around 8,000 USD a month; optimise storage costs for data older than 90 days." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Today a single Kafka VM on premises collects records; it is being retired." + ], + [ + "analytic|query|consum|report|downstream|depend", + "Analysts query the data with SQL; dashboards refresh every 15 minutes." + ], + [ + "operat|monitor|logging|alert|team|support|container|kubernetes|gke", + "The team runs containers and prefers serverless containers over managing Kubernetes clusters." + ], + [ + "retention|archive|keep", + "Keep raw records one year and curated tables three years." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "thresholds": { + "revisions": 3, + "seconds": 3600, + "tokens": 8500000 + } + }, + { + "id": "case-03-internal-web-app", + "name": "Internal booking web application with a relational database", + "workflow_request": "Design an internal web application on Google Cloud for staff to book meeting rooms and equipment, backed by a managed relational database, available only to employees signed in with the corporate identity provider, with application secrets kept out of code and configuration.", + "required_products": [ + "Cloud Run", + "Cloud SQL", + "Secret Manager" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west1 (Belgium). All users are in the EU." + ], + [ + "user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps", + "About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover|backup", + "99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days." + ], + [ + "latency|response time|performance", + "Pages should load within 1 second at p95." + ], + [ + "identity|sign.?in|login|sso|auth|idp|access", + "Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group." + ], + [ + "security|compliance|encrypt|privacy|gdpr|secret|credential|password", + "GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days." + ], + [ + "data|database|schema|relational|postgres|mysql|size|storage", + "PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history." + ], + [ + "cost|budget|spend", + "Under 600 EUR a month; the database can be small." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Bookings are kept in a shared spreadsheet today; there is no data to migrate." + ], + [ + "depend|integrat|calendar|email|notif|downstream|upstream", + "Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one." + ], + [ + "operat|monitor|logging|alert|team|support|deploy|ci|pipeline", + "Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space." + ], + [ + "network|vpc|private|internet|egress|ingress", + "No public database endpoint; the database must use private IP only." + ], + [ + "sustainab|carbon", + "No specific requirement." + ], + [ + "retention|audit|archive|delete", + "Keep booking history 2 years, then delete; keep audit logs 1 year." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "thresholds": { + "revisions": 3, + "seconds": 3200, + "tokens": 8000000 + } + }, + { + "id": "case-04-interactive-web-app", + "name": "Internal booking web application with a relational database (interactive)", + "workflow_request": "Design an internal web application on Google Cloud for staff to book meeting rooms and equipment, backed by a managed relational database, available only to employees signed in with the corporate identity provider, with application secrets kept out of code and configuration.", + "required_products": [ + "Cloud Run", + "Cloud SQL", + "Secret Manager" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west1 (Belgium). All users are in the EU.", + "requirements" + ], + [ + "user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps", + "About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second.", + "requirements" + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover|backup", + "99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days.", + "requirements" + ], + [ + "latency|response time|performance", + "Pages should load within 1 second at p95.", + "requirements" + ], + [ + "identity|sign.?in|login|sso|auth|idp|access", + "Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group.", + "requirements" + ], + [ + "security|compliance|encrypt|privacy|gdpr|secret|credential|password", + "GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days.", + "requirements" + ], + [ + "data|database|schema|relational|postgres|mysql|size|storage", + "PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history.", + "requirements" + ], + [ + "cost|budget|spend", + "Under 600 EUR a month; the database can be small.", + "requirements" + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Bookings are kept in a shared spreadsheet today; there is no data to migrate.", + "requirements" + ], + [ + "depend|integrat|calendar|email|notif|downstream|upstream", + "Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one.", + "requirements" + ], + [ + "operat|monitor|logging|alert|team|support|deploy|ci|pipeline", + "Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space.", + "requirements" + ], + [ + "network|vpc|private|internet|egress|ingress", + "No public database endpoint; the database must use private IP only.", + "requirements" + ], + [ + "sustainab|carbon", + "No specific requirement.", + "requirements" + ], + [ + "retention|audit|archive|delete", + "Keep booking history 2 years, then delete; keep audit logs 1 year.", + "requirements" + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ], + [ + ".", + "Approved. Please proceed.", + "^(?!requirements$)" + ] + ], + "interactive": true, + "thresholds": { + "revisions": 2, + "seconds": 3400, + "tokens": 7500000 + } + }, + { + "id": "case-05-change-retention", + "name": "A change to a delivered event-driven service: retention goes from 30 days to 7 years", + "workflow_request": "Design an event-driven regional HTTP application on Google Cloud that accepts incoming webhooks, validates their signatures, durably enqueues payloads for asynchronous processing, and retains raw events for 30 days for replay and audit.", + "change": "One thing has changed since this was delivered. Raw events must now be kept for 7 years instead of 30 days, to meet a new audit obligation, and must not be deletable during that time. Everything else stays as it is.", + "required_products": [ + "Cloud Run", + "Pub/Sub", + "Cloud Storage" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west2 (London). Data must stay in the UK." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover", + "99.9% monthly availability. RTO 1 hour, RPO 5 minutes for accepted events. No multi-region DR in phase one." + ], + [ + "traffic|volume|throughput|scale|peak|requests per|rps|payload", + "Average 50 webhooks per second, peaks of 500 per second for 10 minutes. Payloads up to 256 KB." + ], + [ + "latency|response time|performance", + "Acknowledge each webhook within 300 ms at p95." + ], + [ + "security|compliance|encrypt|privacy|gdpr|pci|access|identity|auth", + "UK GDPR applies. Google-managed encryption keys are acceptable. Senders sign requests with HMAC-SHA256 shared secrets; only processing services may read events." + ], + [ + "cost|budget|spend", + "Under 1,500 GBP a month at average load; prefer pay-per-use." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "This is a new workload; nothing runs today." + ], + [ + "depend|integrat|downstream|upstream|consum", + "Processed events go to an existing internal REST API that is reachable over HTTPS; it can be slow or unavailable for minutes." + ], + [ + "operat|monitor|logging|alert|team|support", + "A small platform team of three uses Terraform and wants managed services and Cloud Monitoring alerts." + ], + [ + "sustainab|carbon", + "Prefer low-carbon regions when there is no other constraint, but the UK residency requirement wins." + ], + [ + "retention|replay|audit|archive", + "Keep raw events 30 days, then delete. Replay must be possible for any event in that window." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ] + }, + { + "id": "case-06-organisation-standards", + "name": "Internal booking web application, under an organisation's standards (overlay Skill)", + "workflow_request": "Design an internal web application on Google Cloud for staff to book meeting rooms and equipment, backed by a managed relational database, available only to employees signed in with the corporate identity provider, with application secrets kept out of code and configuration.", + "required_products": [ + "Cloud Run", + "Cloud SQL", + "Secret Manager" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west1 (Belgium). All users are in the EU." + ], + [ + "user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps", + "About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover|backup", + "99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days." + ], + [ + "latency|response time|performance", + "Pages should load within 1 second at p95." + ], + [ + "identity|sign.?in|login|sso|auth|idp|access", + "Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group." + ], + [ + "security|compliance|encrypt|privacy|gdpr|secret|credential|password", + "GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days." + ], + [ + "data|database|schema|relational|postgres|mysql|size|storage", + "PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history." + ], + [ + "cost|budget|spend", + "Under 600 EUR a month; the database can be small." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Bookings are kept in a shared spreadsheet today; there is no data to migrate." + ], + [ + "depend|integrat|calendar|email|notif|downstream|upstream", + "Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one." + ], + [ + "operat|monitor|logging|alert|team|support|deploy|ci|pipeline", + "Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space." + ], + [ + "network|vpc|private|internet|egress|ingress", + "No public database endpoint; the database must use private IP only." + ], + [ + "sustainab|carbon", + "No specific requirement." + ], + [ + "retention|audit|archive|delete", + "Keep booking history 2 years, then delete; keep audit logs 1 year." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "overlay_skills": [ + "example-organisation-standards" + ], + "code_standards": [ + { + "name": "only approved regions", + "forbid": "\"(?!europe-west[14]\")(?:us|europe|asia|australia|northamerica|southamerica|me|africa)-[a-z]+[0-9]+\"" + }, + { + "name": "names are built from variables", + "require": "name\\s*=\\s*\"\\$\\{(?:var|local)\\.[a-z_]+\\}-" + }, + { + "name": "the environment comes from a variable", + "require": "var\\.environment\\b" + }, + { + "name": "label workload", + "require": "\\bworkload\\b\\s*=" + }, + { + "name": "label environment", + "require": "\\benvironment\\b\\s*=" + }, + { + "name": "label owner", + "require": "\\bowner\\b\\s*=" + }, + { + "name": "label cost-centre", + "require": "\"?cost[-_]centre\"?\\s*=" + } + ] + }, + { + "id": "case-07-approved-modules", + "name": "Internal booking web application, with published Terraform modules opted into", + "workflow_request": "Design an internal web application on Google Cloud for staff to book meeting rooms and equipment, backed by a managed relational database, available only to employees signed in with the corporate identity provider, with application secrets kept out of code and configuration.", + "required_products": [ + "Cloud Run", + "Cloud SQL", + "Secret Manager" + ], + "scripted_answers": [ + [ + "region|location|geograph", + "A single region, europe-west1 (Belgium). All users are in the EU." + ], + [ + "user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps", + "About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second." + ], + [ + "availability|uptime|sla|rto|rpo|disaster|recover|backup", + "99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days." + ], + [ + "latency|response time|performance", + "Pages should load within 1 second at p95." + ], + [ + "identity|sign.?in|login|sso|auth|idp|access", + "Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group." + ], + [ + "security|compliance|encrypt|privacy|gdpr|secret|credential|password", + "GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days." + ], + [ + "data|database|schema|relational|postgres|mysql|size|storage", + "PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history." + ], + [ + "cost|budget|spend", + "Under 600 EUR a month; the database can be small." + ], + [ + "current|existing|today|on-prem|migrat|legacy", + "Bookings are kept in a shared spreadsheet today; there is no data to migrate." + ], + [ + "depend|integrat|calendar|email|notif|downstream|upstream", + "Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one." + ], + [ + "operat|monitor|logging|alert|team|support|deploy|ci|pipeline", + "Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space." + ], + [ + "network|vpc|private|internet|egress|ingress", + "No public database endpoint; the database must use private IP only." + ], + [ + "sustainab|carbon", + "No specific requirement." + ], + [ + "retention|audit|archive|delete", + "Keep booking history 2 years, then delete; keep audit logs 1 year." + ], + [ + "approve|confirm|proceed|look right|any changes|happy", + "Approved. Please proceed." + ] + ], + "terraform_modules": true + }, + { + "id": "case-08-landing-zone", + "name": "A regulated platform foundation, started from a scope spec", + "scope": "landing-zone.yaml", + "required_products": [ + "Cloud Interconnect", + "Shared VPC", + "Cloud KMS" + ], + "scripted_answers": [ + [ + ".*", + "Proceed on the scope spec as supplied. Where it says decide, choose a sensible default and record it as an assumption." + ] + ] + } +] diff --git a/eval/datasets/specs/landing-zone.yaml b/eval/datasets/specs/landing-zone.yaml new file mode 100644 index 0000000..e26e30d --- /dev/null +++ b/eval/datasets/specs/landing-zone.yaml @@ -0,0 +1,117 @@ +# A benchmark scope spec: a regulated platform foundation. A fictional customer. +schema_version: 1 + +metadata: + engagement_id: case-08-landing-zone + client_name: Example Payments UK + author: Evaluation + revision: "1.0.0" + +engagement: + kind: platform_foundation + +intent: + statement: | + We are a UK-regulated payment platform expanding into Google Cloud. We need an + enterprise-grade landing zone ready in under 10 weeks to support our core payments + engine. All payment processing must comply with DORA and PCI-DSS v4.0. We have + existing on-premises systems that require private, low-latency connectivity over a + 10Gbps dedicated interconnect. We use Entra ID for corporate single sign-on and + GitHub Actions for our delivery pipelines. Security requires that all egress + traffic flows through centralised inspection appliances before touching the public + internet, and customer data must be encrypted with keys we control. + requirements: + - id: REQ-01 + category: Timeline + statement: Platform foundation must be ready for workload ingestion within 10 weeks. + - id: REQ-02 + category: Compliance + statement: Must achieve DORA resiliency alignment and PCI-DSS v4.0 perimeter isolation. + - id: REQ-03 + category: Networking + statement: 10Gbps on-premises hybrid connectivity; centralised inspection appliances for egress. + - id: REQ-04 + category: Identity and security + statement: Workload identity federation with GitHub Actions; Entra ID single sign-on; customer-managed encryption keys. + exclusions: + - Application container deployment; workloads are managed by application squads. + - An active-active secondary region in phase 1; warm standby is acceptable. + success_criteria: decide + +estate: + cloud_provider: gcp + mode: greenfield + regions: + primary: europe-west2 + secondary: europe-west1 + resiliency_tier: warm_standby + data_residency: United Kingdom and European Union + existing_systems: On-premises payment systems that stay in place and connect over the interconnect. + +workload: + users: not_applicable + availability: + target: decide + hours: always + recovery_time: decide + recovery_point: decide + +compliance: + industry: financial_services + frameworks: [DORA, ISO27001, PCI_DSS_v4] + data_classification: confidential + encryption: + type: cmek + key_rotation_days: 90 + audit_logging: + retention_days: 365 + immutable_retention_policy: true + +networking: + exposure: internal_only + topology: shared_vpc_hub_and_spoke + hybrid_connectivity: + enabled: true + type: cloud_interconnect + bandwidth_gbps: 10 + egress_control: + model: centralized_appliance + appliance_vendor: decide + cidr_allocations: decide + +governance: + identity_source_of_truth: Entra ID + pipeline_authentication: workload identity federation + environment_tiers: + - {name: development, archetype: corp_workload} + - {name: staging, archetype: corp_workload} + - {name: production, archetype: pci_regulated_workload} + +operations: + operating_model: central platform team brokering access for application squads + support_hours: always + monitoring: decide + change_process: decide + +integrations: decide + +delivery: + window_weeks: 10 + commercial_model: fixed_price_milestone + iac_tooling: terraform + ci_cd: GitHub Actions + team_size: 3 + working_days_per_week: 5 + +cost: + monthly_budget: decide + currency: GBP + +constraints: + products_required: decide + products_forbidden: decide + +run: + pre_approved: true + allow_cloud_read: false + terraform_modules: false diff --git a/k8s/configmap.yaml b/k8s/configmap.yaml new file mode 100644 index 0000000..0884d6c --- /dev/null +++ b/k8s/configmap.yaml @@ -0,0 +1 @@ +# TODO: generation subagent fills this in. diff --git a/k8s/deployment.yaml b/k8s/deployment.yaml new file mode 100644 index 0000000..0884d6c --- /dev/null +++ b/k8s/deployment.yaml @@ -0,0 +1 @@ +# TODO: generation subagent fills this in. diff --git a/k8s/service.yaml b/k8s/service.yaml new file mode 100644 index 0000000..0884d6c --- /dev/null +++ b/k8s/service.yaml @@ -0,0 +1 @@ +# TODO: generation subagent fills this in. diff --git a/providers/gcp.yaml b/providers/gcp.yaml new file mode 100644 index 0000000..6ee2e80 --- /dev/null +++ b/providers/gcp.yaml @@ -0,0 +1,230 @@ +# Cloud provider bundle: Google Cloud. +# Loaded by app/providers.py; select with CLOUD_PROVIDER=gcp. See ADR-0002. +name: gcp + +skills_dirs: + - skills/vendor/google + - skills + +output_template: skills/vendor/google/google-cloud-solution-architecture/assets/output-template.md + +# Model ids: gemini/ runs on ADK's native Gemini client (Vertex AI or the Gemini +# API, chosen by environment); any other LiteLLM id runs through LiteLLM. Explicit +# versions, because -latest aliases are not served on Vertex AI (checked 2026-09-16). +# Reasoning-heavy roles use Pro; drafting and per-pillar advice use Flash. +models: + default: gemini/gemini-3.8-flash + roles: + orchestrator: gemini/gemini-3.1-pro-preview + product-selector: gemini/gemini-3.1-pro-preview + design-advisor: gemini/gemini-3.1-pro-preview + target-architect: gemini/gemini-3.1-pro-preview + iac-author: gemini/gemini-3.1-pro-preview + validator: gemini/gemini-3.1-pro-preview + lesson-curator: gemini/gemini-3.1-pro-preview + # The same reading the validator makes of a design's coverage, made earlier. + coverage-reviewer: gemini/gemini-3.1-pro-preview + # Dividing and estimating the build is judgement about the whole design. + delivery-planner: gemini/gemini-3.1-pro-preview + # A lighter model for a role's first attempt, used when MODEL_TIERS is on. Only a + # role whose work is checked by something else belongs here: the code is checked + # by terraform validate and by the validator. The validator is the check, and a + # weaker one that passes everything would look like an improvement. + first_attempt: + iac-author: gemini/gemini-3.8-flash + # Seconds one model request may take, for roles whose replies are long. Other + # roles get MODEL_TIMEOUT_SECONDS. The target architect timed out at 180 s in both + # attempts of the 2026-10-07 run. + timeout_seconds: + target-architect: 420 + iac-author: 300 + validator: 300 # timed out five times at 180 s in a run of 2026-10-07 + packager: 300 + coverage-reviewer: 300 + delivery-planner: 300 + +# Skills each role may load. Role files stay provider-neutral; the bundle names Skills. +role_skills: + orchestrator: [google-cloud-solution-architecture] + scope-analyst: [scoping] + requirements-analyst: [google-cloud-solution-architecture, requirements-chain, cloud-discovery] + decomposer: [google-cloud-solution-architecture, requirements-chain] + product-selector: [google-cloud-solution-architecture, requirements-chain] + design-advisor: [google-cloud-solution-architecture, requirements-chain] + describer: [google-cloud-solution-architecture] + target-architect: [google-cloud-solution-architecture, requirements-chain] + iac-author: [google-cloud-solution-architecture, requirements-chain, iac-validation, google-cloud-iac-patterns] + validator: [google-cloud-solution-architecture, requirements-chain, iac-validation] + delivery-planner: [requirements-chain] + packager: [google-cloud-solution-architecture] + +# Where approved lessons are published (ADR-0004). A Specialist is given this Skill +# once it holds lessons for that Specialist's Deliverable. +lessons_skill: google-cloud-lessons + +# The scope spec (ADR-0008). `skill` holds its catalogue, which names no Cloud +# provider. `values` are what this provider allows for the fields the catalogue +# leaves to a provider, in this provider's own terms. +scope: + skill: scoping + values: + estate.cloud_provider: [gcp] + compliance.encryption.type: [cmek, cmek_hsm] + networking.topology: [single_vpc, shared_vpc, shared_vpc_hub_and_spoke] + networking.hybrid_connectivity.type: [cloud_vpn, cloud_interconnect, partner_interconnect] + +# One advisor per architecture-framework pillar; each loads only its pillar's Skill. +pillar_skills: + security: google-cloud-waf-security + reliability: google-cloud-waf-reliability + operational-excellence: google-cloud-waf-operational-excellence + cost-optimization: google-cloud-waf-cost-optimization + performance-optimization: google-cloud-waf-performance-optimization + sustainability: google-cloud-waf-sustainability + +tools: + general: [mermaid_check, terraform_fmt, terraform_validate, terraform_schema, terraform_module] + cloud_read: [terraform_plan] + +# The Terraform providers generated code is written for. One exact version, so the +# schema lookup, the patterns Skill and validation all describe the same provider. +# The 2026-10-07 run left five different versions in the plugin cache. +terraform: + required_providers: + google: + source: hashicorp/google + version: 8.6.0 + # Published modules. Generated code is plain resources unless an Execution opts + # into modules; then a `module` may come only from these registry namespaces, at + # one exact version. `terraform init` downloads and evaluates whatever a source + # names, so anything else is refused before Terraform runs. `skill` holds the + # modules known to work with the provider pinned above, and is given, with the + # terraform_module tool, only to an Execution that opted in. + modules: + namespaces: [terraform-google-modules] + skill: google-cloud-iac-modules + # Not usable on 2026-10-09: each required a google provider below 8. Run + # scripts/check-terraform-modules.py to see whether that has changed. + watch: + - terraform-google-modules/lb-http/google + - terraform-google-modules/pubsub/google + - terraform-google-modules/bigquery/google + - terraform-google-modules/kubernetes-engine/google + - terraform-google-modules/log-export/google + - terraform-google-modules/event-function/google + - terraform-google-modules/scheduled-function/google + - terraform-google-modules/bastion-host/google + +mcp_auth: + kind: google_adc # Application Default Credentials bearer token; sends X-Goog-User-Project + +# Remote MCP servers hosted by Google Cloud (streamable HTTP). +# `allow` lists name the only tools ever exposed. Reviewed 2026-09-16 against each +# server's live tools/list (scripts/list-mcp-tools.py): inventory and configuration +# metadata only, every tool readOnlyHint=true. Deliberately excluded even though +# read-only: data content (Cloud SQL execute_sql_readonly, Storage read_object/read_text, +# list_objects), generic Kubernetes reads that can return Secrets (get_k8s_resource, +# describe_k8s_resource), and every write. See docs/operations/mcp-access.md. +mcp_servers: + developer_knowledge: + url: https://developerknowledge.googleapis.com/mcp + tier: general # public documentation, no customer data + allow: + - search_documents + - get_documents + - answer_query + resource_manager: + url: https://cloudresourcemanager.googleapis.com/mcp + tier: cloud_read + allow: + - search_projects + asset_inventory: + url: https://cloudasset.googleapis.com/mcp + tier: cloud_read + allow: + - list_assets + - analyze_iam_policy + preview: true + compute: + url: https://compute.googleapis.com/mcp + tier: cloud_read + allow: + - list_instances + - get_instance_basic_info + - list_instance_attached_disks + - list_instance_group_managers + - get_instance_group_manager_basic_info + - list_instance_templates + - get_instance_template_properties + - list_disks + - get_disk_basic_info + - list_reservations + - list_commitments + gke: + url: https://container.googleapis.com/mcp + tier: cloud_read + allow: + - list_clusters + - get_cluster + - list_node_pools + - get_node_pool + - get_k8s_version + cloud_run: + url: https://run.googleapis.com/mcp + tier: cloud_read + allow: + - list_services + - get_service + cloud_sql: + url: https://sqladmin.googleapis.com/mcp + tier: cloud_read + allow: + - list_instances + - get_instance + storage: + url: https://storage.googleapis.com/storage/mcp + tier: cloud_read + allow: + - list_buckets + pubsub: + url: https://pubsub.googleapis.com/mcp + tier: cloud_read + allow: + - list_topics + - get_topic + - list_subscriptions + - get_subscription + iam: + url: https://iam.googleapis.com/mcp + tier: cloud_read + allow: + - list_roles + - get_role + - list_deny_policies + - get_deny_policy + monitoring: + url: https://monitoring.googleapis.com/mcp + tier: cloud_read + allow: + - list_alert_policies + - get_alert_policy + - list_dashboards + - list_metric_descriptors + - list_timeseries + network_intelligence: + url: https://networkmanagement.googleapis.com/mcp + tier: cloud_read + allow: + - list_connectivity_tests + - get_connectivity_test + preview: true + +role_mcp_servers: + requirements-analyst: + [resource_manager, asset_inventory, compute, gke, cloud_run, cloud_sql, storage, pubsub, iam, monitoring] + product-selector: [developer_knowledge] + describer: [developer_knowledge] + design-advisor: [developer_knowledge] + target-architect: [developer_knowledge] + pillar-advisor: [developer_knowledge] + validator: [iam, network_intelligence] diff --git a/providers/reviews/gcp-mcp-tools.json b/providers/reviews/gcp-mcp-tools.json new file mode 100644 index 0000000..5a47208 --- /dev/null +++ b/providers/reviews/gcp-mcp-tools.json @@ -0,0 +1,854 @@ +{ + "developer_knowledge": { + "url": "https://developerknowledge.googleapis.com/mcp", + "tools": [ + { + "name": "search_documents", + "read_only": true, + "allowed": true, + "description": "Use this tool to find documentation about Google developer products. The documents contain official APIs, code snippets, release notes, best practices, guides, debugging info, and more. It covers the " + }, + { + "name": "answer_query", + "read_only": true, + "allowed": true, + "description": "Use answer_query to get a grounded answer to a query about Google developer products. This tool has limited quota. This tool will synthesize information from the corpus to generate an answer to the qu" + }, + { + "name": "get_documents", + "read_only": true, + "allowed": true, + "description": "Use this tool to retrieve the full content of a single document or up to 20 documents in a single call. The document names should be obtained from the `parent` field of results from a call to the `sea" + } + ] + }, + "resource_manager": { + "url": "https://cloudresourcemanager.googleapis.com/mcp", + "tools": [ + { + "name": "search_projects", + "read_only": true, + "allowed": true, + "description": "Searches for Google Cloud projects. This tool may be used whenever any tools or conversation context requires a GCP project. A SearchProjects call with an empty query will return all projects the user" + } + ] + }, + "asset_inventory": { + "url": "https://cloudasset.googleapis.com/mcp", + "tools": [ + { + "name": "list_assets", + "read_only": true, + "allowed": true, + "description": "List assets from Cloud Asset Inventory" + }, + { + "name": "analyze_iam_policy", + "read_only": true, + "allowed": true, + "description": "Analyzes Google Cloud IAM allow policies to determine who can do what on which resources. It can perform policy analysis such as finding resources accessible to a principal, finding principals with ac" + }, + { + "name": "export_iam_analysis_results", + "read_only": false, + "allowed": false, + "description": "Analyzes Google Cloud IAM policies asynchronously and exports the results to a BigQuery dataset or Google Cloud Storage bucket. Use this for large-scale analysis (for example, expanding resources or i" + }, + { + "name": "get_iam_policy_analysis_status", + "read_only": true, + "allowed": false, + "description": "Polls the status of a long-running IAM Policy Analyzer operation. Use this *only* to pass the operation `name` returned by the `export_iam_analysis_results` tool. If the operation is finished, the `do" + } + ] + }, + "compute": { + "url": "https://compute.googleapis.com/mcp", + "tools": [ + { + "name": "create_instance", + "read_only": false, + "allowed": false, + "description": "Create a new Google Compute Engine virtual machine (VM) instance. Requires project, zone, and instance name as input. If machine_type is not provided, it defaults to `e2-medium`. If image_project and " + }, + { + "name": "delete_instance", + "read_only": false, + "allowed": false, + "description": "Delete a Google Compute Engine virtual machine (VM) instance. Requires project, zone, and instance name as input. Proceed only if there is no error in response and the status of the operation is `DONE" + }, + { + "name": "start_instance", + "read_only": false, + "allowed": false, + "description": "Starts a Google Compute Engine virtual machine (VM) instance. Requires project, zone, and instance name as input. Proceed only if there is no error in response and the status of the operation is `DONE" + }, + { + "name": "stop_instance", + "read_only": false, + "allowed": false, + "description": "Stops a Google Compute Engine virtual machine (VM) instance. Requires project, zone, and instance name as input. Proceed only if there is no error in response and the status of the operation is `DONE`" + }, + { + "name": "reset_instance", + "read_only": false, + "allowed": false, + "description": "Resets a Google Compute Engine virtual machine (VM) instance. Requires project, zone, and instance name as input. Proceed only if there is no error in response and the status of the operation is `DONE" + }, + { + "name": "get_instance_basic_info", + "read_only": true, + "allowed": true, + "description": "Get basic information about a Compute Engine VM instance, including its name, ID, status, machine type, creation timestamp, and attached guest accelerators. Requires project, zone, and instance name a" + }, + { + "name": "set_instance_machine_type", + "read_only": false, + "allowed": false, + "description": "Sets the machine type for a stopped Google Compute Engine instance to the specified machine type. Requires project, zone, instance name and machine type as input. Proceed only if there is no error in " + }, + { + "name": "list_instance_attached_disks", + "read_only": true, + "allowed": true, + "description": "Lists the disks attached to a Compute Engine virtual machine (VM) instance. For each attached disk, the response includes details such as kind, type, mode, saved state, source, device name, index, boo" + }, + { + "name": "list_instances", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine virtual machine (VM) instances. Details for each instance include name, ID, status, machine type, creation timestamp, and attached guest accelerators. Use other tools to get more " + }, + { + "name": "get_instance_group_manager_basic_info", + "read_only": true, + "allowed": true, + "description": "Get basic information about a Compute Engine managed instance group (MIG), including its name, ID, instance template, base instance name, target size, target stopped size, target suspended size, statu" + }, + { + "name": "list_instance_group_managers", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine managed instance groups (MIGs). Details for each MIG include name, ID, instance template, base instance name, target size, target stopped size, target suspended size, status and c" + }, + { + "name": "list_managed_instances", + "read_only": true, + "allowed": false, + "description": "Lists managed instances for a given managed instance group (MIG). For each instance, details include id, instance URL, instance status, and current action. Requires project, zone, and MIG name as inpu" + }, + { + "name": "list_instance_templates", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine instance templates. Details for each instance template include name, ID, description, machine type, region, and creation timestamp. Requires project as input." + }, + { + "name": "get_instance_template_basic_info", + "read_only": true, + "allowed": false, + "description": "Get basic information about a Compute Engine instance template, including its name, ID, description, machine type, region, and creation timestamp. Requires project and instance template name as input." + }, + { + "name": "get_instance_template_properties", + "read_only": true, + "allowed": true, + "description": "Get instance properties of a Compute Engine instance template. This includes properties such as description, tags, machine type, network interfaces, disks, metadata, service accounts, scheduling optio" + }, + { + "name": "get_disk_basic_info", + "read_only": true, + "allowed": true, + "description": "Get basic information about a Compute Engine disk, including its name, ID, description, creation timestamp, size, type, status, last attach timestamp, and last detach timestamp. Requires project, zone" + }, + { + "name": "get_disk_performance_config", + "read_only": true, + "allowed": false, + "description": "Get performance configuration of a Compute Engine disk, including its type, size, provisioned IOPS, provisioned throughput, physical block size, storage pool and access mode. Requires project, zone, a" + }, + { + "name": "list_disks", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine disks. Details for each disk include name, ID, description, creation timestamp, size, type, status, last attach timestamp, and last detach timestamp. Requires project and zone as " + }, + { + "name": "list_accelerator_types", + "read_only": true, + "allowed": false, + "description": "Lists the available Google Compute Engine accelerator types. Requires project and zone as input. Returns accelerator types, including id, creation timestamp, name, description, deprecated, zone, and m" + }, + { + "name": "list_machine_types", + "read_only": true, + "allowed": false, + "description": "Lists the available Google Compute Engine machine types. Requires project and zone as input. Returns machine types, including id, creationTimestamp, name, description, guest cpus, memory, image space," + }, + { + "name": "list_images", + "read_only": true, + "allowed": false, + "description": "Lists Compute Engine Images. Details for each image include name, ID, status, family, and creation timestamp. Requires project as input." + }, + { + "name": "get_zone_operation", + "read_only": true, + "allowed": false, + "description": "Get details of a zone operation, including its id, name, status, creation timestamp, error, warning, HTTP error message and HTTP error status code. Requires project, zone, and operation name as input." + }, + { + "name": "get_reservation_basic_info", + "read_only": true, + "allowed": false, + "description": "Get Compute Engine reservation basic info including name, ID, creation timestamp, zone, status, specific reservation required, commitment, and linked commitments. Requires project, zone, and reservati" + }, + { + "name": "get_reservation_details", + "read_only": true, + "allowed": false, + "description": "Get Compute Engine reservation details. Returns reservation details including name, ID, status, creation timestamp, specific reservation properties like machine type, guest accelerators and local SSDs" + }, + { + "name": "list_reservations", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine reservations. Details for each reservation include name, ID, creation timestamp, zone, status, specific reservation required, commitment, and linked commitments. Requires project " + }, + { + "name": "list_commitments", + "read_only": true, + "allowed": true, + "description": "Lists Compute Engine Commitments in a region. Details for each commitment include name, ID, status, plan, type, resources, and creation, start and end timestamps. Requires project and region as input." + }, + { + "name": "get_commitment_basic_info", + "read_only": true, + "allowed": false, + "description": "Get basic information about a Compute Engine Commitment, including its name, ID, status, plan, type, resources, and creation, start and end timestamps. Requires project, region, and commitment name as" + }, + { + "name": "list_commitment_reservations", + "read_only": true, + "allowed": false, + "description": "Lists reservations for a Compute Engine Commitment. Returns reservation details including name, ID, status, creation timestamp, specific reservation properties like machine type, guest accelerators an" + }, + { + "name": "list_snapshots", + "read_only": true, + "allowed": false, + "description": "Lists snapshots in a project providing basic information per snapshot including name, id, status, creation time, disk size, storage bytes, source disk, and source disk id. Requires project as input." + } + ] + }, + "gke": { + "url": "https://container.googleapis.com/mcp", + "tools": [ + { + "name": "list_k8s_api_resources", + "read_only": true, + "allowed": false, + "description": "Retrieves the available API groups and resources from a Kubernetes cluster. This is similar to running `kubectl api-resources`." + }, + { + "name": "check_k8s_auth", + "read_only": true, + "allowed": false, + "description": "Checks whether an action is allowed on a Kubernetes resource. This is similar to running `kubectl auth can-i`." + }, + { + "name": "describe_k8s_resource", + "read_only": true, + "allowed": false, + "description": "Shows the details of a specific Kubernetes resource. This is similar to running `kubectl describe`." + }, + { + "name": "list_k8s_events", + "read_only": true, + "allowed": false, + "description": "Retrieves events from a Kubernetes cluster. This is similar to running `kubectl events`." + }, + { + "name": "get_k8s_resource", + "read_only": true, + "allowed": false, + "description": "Gets one or more Kubernetes resources from a cluster. Resources can be filtered by type, name, namespace, and label selectors. Returns the resources in YAML format. This is similar to running `kubectl" + }, + { + "name": "get_k8s_cluster_info", + "read_only": true, + "allowed": false, + "description": "Gets cluster endpoint information. This is similar to running `kubectl cluster-info`." + }, + { + "name": "get_k8s_version", + "read_only": true, + "allowed": true, + "description": "Retrieves Kubernetes client and server versions for a given cluster. This is similar to running `kubectl version`." + }, + { + "name": "get_k8s_rollout_status", + "read_only": true, + "allowed": false, + "description": "Checks the current rollout status of a Kubernetes resource. This is similar to running `kubectl rollout status`." + }, + { + "name": "list_clusters", + "read_only": true, + "allowed": true, + "description": "Lists GKE clusters in a given project and location. Location can be a region, zone, or '-' for all locations." + }, + { + "name": "create_cluster", + "read_only": false, + "allowed": false, + "description": "Creates a new GKE cluster in a given project and location. It's recommended to read the [GKE documentation](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/configuration-overview) to und" + }, + { + "name": "update_cluster", + "read_only": false, + "allowed": false, + "description": "Updates a specific GKE cluster." + }, + { + "name": "get_cluster", + "read_only": true, + "allowed": true, + "description": "Gets the details of a specific GKE cluster." + }, + { + "name": "list_operations", + "read_only": true, + "allowed": false, + "description": "Lists GKE operations in a given project and location. Location can be a region, zone, or '-' for all locations." + }, + { + "name": "get_operation", + "read_only": true, + "allowed": false, + "description": "Gets the details of a specific GKE operation." + }, + { + "name": "cancel_operation", + "read_only": false, + "allowed": false, + "description": "Cancels a specific GKE operation." + }, + { + "name": "create_node_pool", + "read_only": false, + "allowed": false, + "description": "Creates a node pool for a specific GKE cluster." + }, + { + "name": "list_node_pools", + "read_only": true, + "allowed": true, + "description": "Lists the node pools for a specific GKE cluster." + }, + { + "name": "get_node_pool", + "read_only": true, + "allowed": true, + "description": "Gets the details of a specific node pool within a GKE cluster." + }, + { + "name": "update_node_pool", + "read_only": false, + "allowed": false, + "description": "Updates a specific node pool within a GKE cluster." + }, + { + "name": "get_k8s_logs", + "read_only": true, + "allowed": false, + "description": "Gets logs from a Kubernetes container in a pod. This is similar to running `kubectl logs`." + }, + { + "name": "apply_k8s_manifest", + "read_only": false, + "allowed": false, + "description": "Applies a Kubernetes manifest to a cluster using server-side apply. This is similar to running `kubectl apply --server-side`." + }, + { + "name": "delete_k8s_resource", + "read_only": false, + "allowed": false, + "description": "Deletes a Kubernetes resource from a cluster. This is similar to running `kubectl delete`." + }, + { + "name": "patch_k8s_resource", + "read_only": false, + "allowed": false, + "description": "Patches a Kubernetes resource. This is similar to running `kubectl patch`." + } + ] + }, + "cloud_run": { + "url": "https://run.googleapis.com/mcp", + "tools": [ + { + "name": "get_service", + "read_only": true, + "allowed": true, + "description": "Get info about a Cloud Run service, such as its URI and whether the deploy succeeded." + }, + { + "name": "list_services", + "read_only": true, + "allowed": true, + "description": "List Cloud Run services in a given Google Cloud project and region." + }, + { + "name": "deploy_service_from_image", + "read_only": false, + "allowed": false, + "description": "Deploy a container image from Artifact Registry or Docker Hub as a Cloud Run service." + }, + { + "name": "deploy_service_from_archive", + "read_only": false, + "allowed": false, + "description": "Deploy a Cloud Run service directly from a self-contained source code archive (.tar.gz)," + }, + { + "name": "deploy_service_from_file_contents", + "read_only": false, + "allowed": false, + "description": "Deploys a Cloud Run service directly from local source files. This method is suitable for" + } + ] + }, + "cloud_sql": { + "url": "https://sqladmin.googleapis.com/mcp", + "tools": [ + { + "name": "list_instances", + "read_only": true, + "allowed": true, + "description": "List all Cloud SQL instances in the project." + }, + { + "name": "get_instance", + "read_only": true, + "allowed": true, + "description": "Get the details of a Cloud SQL instance." + }, + { + "name": "create_instance", + "read_only": false, + "allowed": false, + "description": "Initiates the creation of a Cloud SQL instance." + }, + { + "name": "execute_sql", + "read_only": false, + "allowed": false, + "description": "Execute any valid SQL statement, including data definition language (DDL)," + }, + { + "name": "execute_sql_readonly", + "read_only": true, + "allowed": false, + "description": "Execute any valid read only SQL statement on a Cloud SQL instance." + }, + { + "name": "get_operation", + "read_only": true, + "allowed": false, + "description": "Get the status of a long-running operation. A long-running operation can take several" + }, + { + "name": "create_user", + "read_only": false, + "allowed": false, + "description": "Create a database user for a Cloud SQL instance." + }, + { + "name": "update_user", + "read_only": false, + "allowed": false, + "description": "Update a database user for a Cloud SQL instance. A common use case for" + }, + { + "name": "clone_instance", + "read_only": false, + "allowed": false, + "description": "Create a Cloud SQL instance as a clone of a source instance." + }, + { + "name": "update_instance", + "read_only": false, + "allowed": false, + "description": "Partially updates the configuration settings of a Cloud SQL instance." + }, + { + "name": "list_users", + "read_only": true, + "allowed": false, + "description": "List all database users for a Cloud SQL instance." + }, + { + "name": "create_backup", + "read_only": false, + "allowed": false, + "description": "Takes a backup on a Cloud SQL instance. Always populate the project and instance fields on" + }, + { + "name": "restore_backup", + "read_only": false, + "allowed": false, + "description": "Restores a backup to a Cloud SQL instance." + }, + { + "name": "import_data", + "read_only": false, + "allowed": false, + "description": "Import data into a Cloud SQL instance." + }, + { + "name": "postgres_upgrade_precheck", + "read_only": false, + "allowed": false, + "description": "Checks if a Cloud SQL for PostgreSQL instance is ready for a major version upgrade to the" + } + ] + }, + "storage": { + "url": "https://storage.googleapis.com/storage/mcp", + "tools": [ + { + "name": "list_buckets", + "read_only": true, + "allowed": true, + "description": "Lists the buckets of a project." + }, + { + "name": "list_objects", + "read_only": true, + "allowed": false, + "description": "Lists the objects in a bucket." + }, + { + "name": "create_bucket", + "read_only": false, + "allowed": false, + "description": "Creates a bucket in a project." + }, + { + "name": "delete_bucket", + "read_only": false, + "allowed": false, + "description": "Deletes a bucket from a project." + }, + { + "name": "read_text", + "read_only": true, + "allowed": false, + "description": "DEPRECATED: Use `read_object` instead. Reads non-binary text content from an object." + }, + { + "name": "read_object", + "read_only": true, + "allowed": false, + "description": "Reads an object from Cloud Storage. Supports both text and binary content (it will output text for text content and binary for binary content)." + }, + { + "name": "write_text", + "read_only": false, + "allowed": false, + "description": "Writes text content to an object, overwriting any existing content." + }, + { + "name": "delete_object", + "read_only": false, + "allowed": false, + "description": "Deletes an object from Cloud Storage." + }, + { + "name": "get_object_metadata", + "read_only": true, + "allowed": false, + "description": "Gets the metadata of an object." + } + ] + }, + "pubsub": { + "url": "https://pubsub.googleapis.com/mcp", + "tools": [ + { + "name": "create_topic", + "read_only": false, + "allowed": false, + "description": "Create a new Cloud Pub/Sub topic." + }, + { + "name": "update_topic", + "read_only": false, + "allowed": false, + "description": "Update an existing Cloud Pub/Sub topic." + }, + { + "name": "delete_topic", + "read_only": false, + "allowed": false, + "description": "Delete an existing Cloud Pub/Sub topic." + }, + { + "name": "get_topic", + "read_only": true, + "allowed": true, + "description": "Get the configuration of a Cloud Pub/Sub topic." + }, + { + "name": "list_topics", + "read_only": true, + "allowed": true, + "description": "List all Cloud Pub/Sub topics in a given project." + }, + { + "name": "create_subscription", + "read_only": false, + "allowed": false, + "description": "Create a new Cloud Pub/Sub subscription to a given topic." + }, + { + "name": "update_subscription", + "read_only": false, + "allowed": false, + "description": "Update an existing Cloud Pub/Sub subscription." + }, + { + "name": "delete_subscription", + "read_only": false, + "allowed": false, + "description": "Delete an existing Cloud Pub/Sub subscription." + }, + { + "name": "get_subscription", + "read_only": true, + "allowed": true, + "description": "Get the configuration of a Cloud Pub/Sub subscription." + }, + { + "name": "list_subscriptions", + "read_only": true, + "allowed": true, + "description": "List all Cloud Pub/Sub subscriptions in a given project." + }, + { + "name": "create_snapshot", + "read_only": false, + "allowed": false, + "description": "Create a new Cloud Pub/Sub snapshot from a given subscription." + }, + { + "name": "delete_snapshot", + "read_only": false, + "allowed": false, + "description": "Delete an existing Cloud Pub/Sub snapshot." + }, + { + "name": "get_snapshot", + "read_only": true, + "allowed": false, + "description": "Get the configuration of a Cloud Pub/Sub snapshot." + }, + { + "name": "list_snapshots", + "read_only": true, + "allowed": false, + "description": "List all Cloud Pub/Sub snapshots in a given project." + }, + { + "name": "publish", + "read_only": false, + "allowed": false, + "description": "Publish a series of one or more messages to an existing topic." + } + ] + }, + "iam": { + "url": "https://iam.googleapis.com/mcp", + "tools": [ + { + "name": "list_deny_policies", + "read_only": true, + "allowed": true, + "description": "Lists IAM v2 deny policies attached to a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "get_deny_policy", + "read_only": true, + "allowed": true, + "description": "Gets the details, metadata, and rules of an IAM v2 deny policy attached to a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "create_deny_policy", + "read_only": false, + "allowed": false, + "description": "Creates a new IAM v2 deny policy attached to a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "update_deny_policy", + "read_only": false, + "allowed": false, + "description": "Updates an existing IAM v2 deny policy attached to a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "delete_deny_policy", + "read_only": false, + "allowed": false, + "description": "Permanently deletes an IAM v2 deny policy from a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "get_deny_policy_status", + "read_only": true, + "allowed": false, + "description": "Gets the status of a long-running operation initiated by creating, updating, or deleting an IAM v2 deny policy." + }, + { + "name": "list_roles", + "read_only": true, + "allowed": true, + "description": "Lists every custom IAM role that is defined for a Google Cloud project. Orgs and folders are not supported." + }, + { + "name": "get_role", + "read_only": true, + "allowed": true, + "description": "Gets the definition of a custom role. Orgs are not supported." + }, + { + "name": "create_role", + "read_only": false, + "allowed": false, + "description": "Creates a new custom IAM role for a project. Orgs are not supported." + }, + { + "name": "update_role", + "read_only": false, + "allowed": false, + "description": "Updates the definition of an existing custom IAM role. Orgs are not supported." + }, + { + "name": "delete_role", + "read_only": false, + "allowed": false, + "description": "Deletes a custom IAM role, making it inactive. Orgs are not supported." + }, + { + "name": "undelete_role", + "read_only": false, + "allowed": false, + "description": "Restores (undeletes) a previously deleted custom IAM role. Orgs are not supported." + } + ] + }, + "monitoring": { + "url": "https://monitoring.googleapis.com/mcp", + "tools": [ + { + "name": "list_timeseries", + "read_only": true, + "allowed": true, + "description": "Lists time series data from the Google Cloud Monitoring API" + }, + { + "name": "query_range", + "read_only": true, + "allowed": false, + "description": "Evaluate a PromQL query in a range of time" + }, + { + "name": "get_alert_policy", + "read_only": true, + "allowed": true, + "description": "Use this as the primary tool to get information about a specific alerting policy. Alerting policies define the conditions under which you want to be notified about issues with your services. This is u" + }, + { + "name": "list_alert_policies", + "read_only": true, + "allowed": true, + "description": "Use this as the primary tool to list the alerting policies in a Google Cloud project. Alerting policies define the conditions under which you want to be notified about issues with your services. This " + }, + { + "name": "get_alert", + "read_only": true, + "allowed": false, + "description": "Use this as the primary tool to get information about a specific alert. An alert is the representation of a violation of an alert policy. This is useful for understanding the details of a specific ale" + }, + { + "name": "list_alerts", + "read_only": true, + "allowed": false, + "description": "Use this as the primary tool to list the alerts in a Google Cloud project. An alert is the representation of a violation of an alert policy. This is useful for understanding current and past violation" + }, + { + "name": "list_metric_descriptors", + "read_only": true, + "allowed": true, + "description": "Use this as the primary tool to discover the types of metrics available in a Google Cloud project. This is a good first step to understanding what data is available for monitoring and building dashboa" + }, + { + "name": "list_dashboards", + "read_only": true, + "allowed": true, + "description": "Use this as the primary tool to retrieve a list of existing custom monitoring dashboards in a Google Cloud project. Custom monitoring dashboards let users view and analyze data from different sources " + }, + { + "name": "get_dashboard", + "read_only": true, + "allowed": false, + "description": "Use this as the primary tool to retrieve a single specific custom monitoring dashboard from a Google Cloud project using the resource name of the requested dashboard. Custom monitoring dashboards let " + } + ] + }, + "network_intelligence": { + "url": "https://networkmanagement.googleapis.com/mcp", + "tools": [ + { + "name": "create_connectivity_test", + "read_only": false, + "allowed": false, + "description": "Creates and runs a Connectivity Test from the source to the destination endpoint. Test runs are billable after the project exceeds its free limit. Note that only test runs with results other than 'UND" + }, + { + "name": "get_connectivity_test", + "read_only": true, + "allowed": true, + "description": "Gets the details of a specific Connectivity Test." + }, + { + "name": "list_connectivity_tests", + "read_only": true, + "allowed": true, + "description": "Lists all Connectivity Tests owned by a project." + }, + { + "name": "delete_connectivity_test", + "read_only": false, + "allowed": false, + "description": "Deletes a specific Connectivity Test." + }, + { + "name": "get_networkmanagement_connectivity_test_iam_policy", + "read_only": true, + "allowed": false, + "description": "Gets the IAM access control policy for a Network Management resource. The 'resource' parameter must be the fully-qualified resource name, for example: 'projects/{project_id}/locations/global/connectiv" + }, + { + "name": "set_networkmanagement_connectivity_test_iam_policy", + "read_only": false, + "allowed": false, + "description": "Sets the IAM access control policy for a Network Management resource. The 'resource' parameter must be the fully-qualified resource name, for example: 'projects/{project_id}/locations/global/connectiv" + }, + { + "name": "test_networkmanagement_connectivity_test_iam_permissions", + "read_only": true, + "allowed": false, + "description": "Returns permissions that a caller has on the specified Network Management resource. The 'resource' parameter must be the fully-qualified resource name, for example: 'projects/{project_id}/locations/gl" + } + ] + } +} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..40e98c7 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,33 @@ +[project] +name = "solution-architecture-agent" +version = "0.1.0" +description = "Turns a request for a cloud solution into a reviewed architecture, its infrastructure code and its plan." +requires-python = ">=3.12" +# The Execution engine is installed from its own repository. Locally: +# pip install -e ../orchestration_engine --config-settings editable_mode=compat +# A container build takes it from a named build context (see Dockerfile). +dependencies = ["execution-engine"] + +[project.optional-dependencies] +dev = [ + "pytest>=8.0.0", + "pytest-asyncio>=0.23.0", + "ruff>=0.6.0", + "mypy>=1.11.0", + "types-pyyaml>=6.0.0", +] + +[tool.setuptools.packages.find] +include = ["app*"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +cache_dir = ".cache/pytest" +asyncio_mode = "auto" +asyncio_default_fixture_loop_scope = "function" + +[tool.ruff] +cache-dir = ".cache/ruff" + +[tool.mypy] +cache_dir = ".cache/mypy" diff --git a/scripts/check-terraform-modules.py b/scripts/check-terraform-modules.py new file mode 100644 index 0000000..c97f89c --- /dev/null +++ b/scripts/check-terraform-modules.py @@ -0,0 +1,97 @@ +#!/usr/bin/env python3 +"""Review the published Terraform modules a provider bundle's modules Skill uses. + +For each module the Skill's examples call: the version pinned there, the latest in +the registry, and whether the latest still works with the pinned provider. For each +module the bundle lists under `terraform.modules.watch`, which could not be used +when last looked at: whether its latest version now can. + +It reads the public registry and changes nothing. Raising a pinned version is a +change to the Skill's example, which `tests/test_iac_modules.py` then validates. + +Usage: .venv/bin/python scripts/check-terraform-modules.py [provider] +""" + +from __future__ import annotations + +import asyncio +import re +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from execution_engine.adk.runtime import ToolResult +from execution_engine.providers import load_provider + +from app.solution_architecture.modules import ModuleLookup, admits, module_calls + +_HCL = re.compile(r"^```hcl\n(.*?)^```", re.MULTILINE | re.DOTALL) + + +def _blocked(part: dict, pinned: dict[str, str]) -> list[str]: + """The provider requirements of a module that the pinned versions do not meet.""" + return [ + f"{need.get('name')} {need.get('version')}" + for need in part.get("provider_dependencies") or [] + if need.get("name") in pinned + and need.get("version") + and not admits(need["version"], pinned[need["name"]]) + ] + + +async def main(provider: str) -> int: + bundle = load_provider(provider) + if not bundle.terraform_modules_skill: + print(f"The {provider} bundle names no modules Skill.") + return 0 + pinned = {name: pin["version"] for name, pin in bundle.terraform_providers.items()} + lookup = ModuleLookup(namespaces=bundle.terraform_module_namespaces, pinned=pinned) + skill = bundle.skills[bundle.terraform_modules_skill].path + + used: dict[str, set[str]] = {} + for reference in sorted((skill / "references").glob("*.md")): + code = "\n".join(_HCL.findall(reference.read_text(encoding="utf-8"))) + for call in module_calls({"main.tf": code}): + used.setdefault(call.source.split("//")[0], set()).add(call.version) + + stale = 0 + print(f"Pinned providers: {pinned}\n\nModules the Skill uses:") + for module, versions in sorted(used.items()): + data = await lookup._fetch(module, "") + if isinstance(data, ToolResult): + print(f" {module}: {data.message}") + continue + latest = str(data.get("version", "?")) + blocked = _blocked(data.get("root") or {}, pinned) + note = "up to date" if versions == {latest} else f"latest is {latest}" + if versions != {latest}: + stale += 1 + if blocked: + note += f"; the latest needs {', '.join(blocked)}, so stay on the pin" + print(f" {module} {', '.join(sorted(versions))}: {note}") + + print("\nModules that could not be used when last looked at:") + usable = 0 + for name in bundle.terraform_modules_watch: + data = await lookup._fetch(name, "") + if isinstance(data, ToolResult): + print(f" {name}: {data.message}") + continue + blocked = _blocked(data.get("root") or {}, pinned) + if blocked: + print(f" {name} {data.get('version')}: still needs {', '.join(blocked)}") + else: + usable += 1 + print( + f" {name} {data.get('version')}: NOW USABLE with the pinned provider" + ) + print( + f"\n{stale} pinned module(s) have a newer version; {usable} watched " + "module(s) can now be used." + ) + return 0 + + +if __name__ == "__main__": + sys.exit(asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "gcp"))) diff --git a/scripts/list-mcp-tools.py b/scripts/list-mcp-tools.py new file mode 100644 index 0000000..35cd320 --- /dev/null +++ b/scripts/list-mcp-tools.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""List every tool a provider bundle's remote MCP servers offer, with read-only hints. + +Use it to review allowlists: only list tools; this never calls one. + +Usage: .venv/bin/python scripts/list-mcp-tools.py [provider] [--json] [--no-auth] + +--no-auth lists without credentials; Google Cloud MCP servers allow tools/list anonymously. +""" + +from __future__ import annotations + +import asyncio +import json +import sys +from pathlib import Path +from typing import Any + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +from execution_engine.config import get_settings +from execution_engine.providers import load_provider +from execution_engine.tools.mcp import McpClient, NoAuth, auth_from_config + + +async def main(provider: str, as_json: bool, no_auth: bool) -> int: + bundle = load_provider(provider) + auth = ( + NoAuth() + if no_auth + else auth_from_config(bundle.mcp_auth, get_settings().MCP_QUOTA_PROJECT) + ) + report: dict[str, dict[str, Any]] = {} + for server in bundle.mcp_servers.values(): + try: + tools = await McpClient(server, auth, timeout=30).list_tools() + except Exception as exc: # noqa: BLE001 - report every server + report[server.id] = { + "url": server.url, + "error": f"{type(exc).__name__}: {exc}", + } + continue + report[server.id] = { + "url": server.url, + "tools": [ + { + "name": tool.name, + "read_only": tool.read_only, + "allowed": tool.name in server.allow, + "description": tool.description.split("\n")[0][:200], + } + for tool in tools + ], + } + if as_json: + print(json.dumps(report, indent=2)) + return 0 + for server_id, entry in report.items(): + print(f"\n== {server_id} ({entry['url']})") + if "error" in entry: + print(f" ERROR {entry['error'][:200]}") + continue + for tool in entry["tools"]: + flag = "RO" if tool["read_only"] else "RW" + allowed = "allowed" if tool["allowed"] else "" + print(f" [{flag}] {tool['name']:<40} {allowed:<8} {tool['description']}") + return 0 + + +if __name__ == "__main__": + args = [a for a in sys.argv[1:] if not a.startswith("--")] + sys.exit( + asyncio.run( + main( + args[0] if args else "gcp", + "--json" in sys.argv, + "--no-auth" in sys.argv, + ) + ) + ) diff --git a/scripts/sync-vendored-skills.sh b/scripts/sync-vendored-skills.sh new file mode 100755 index 0000000..b86b704 --- /dev/null +++ b/scripts/sync-vendored-skills.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +# Re-vendor upstream Agent Skills from github.com/google/skills at a pinned commit. +# +# Usage: scripts/sync-vendored-skills.sh [<40-char commit sha>] +# +# Replaces skills/vendor/google/ wholesale, then rewrites SHA256SUMS and VENDOR.md. +# Never edit vendored files by hand: review the upstream diff, then re-run this script. +set -euo pipefail + +REPO="google/skills" +DEFAULT_COMMIT="81a31a6e4300425598a69fd96c8e843c947ae308" +COMMIT="${1:-$DEFAULT_COMMIT}" +SKILLS=( + google-cloud-solution-architecture + google-cloud-waf-security + google-cloud-waf-reliability + google-cloud-waf-cost-optimization + google-cloud-waf-operational-excellence + google-cloud-waf-performance-optimization + google-cloud-waf-sustainability +) + +if [[ ! "$COMMIT" =~ ^[0-9a-f]{40}$ ]]; then + echo "error: commit must be a full 40-character sha, got '$COMMIT'" >&2 + exit 1 +fi + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +DEST="$ROOT/skills/vendor/google" +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +echo "Fetching $REPO@$COMMIT" +curl -fsSL "https://codeload.github.com/$REPO/tar.gz/$COMMIT" | tar -xz -C "$TMP" +SRC="$TMP/skills-$COMMIT" +[[ -d "$SRC" ]] || { echo "error: unexpected archive layout in $TMP" >&2; exit 1; } + +rm -rf "$DEST" +mkdir -p "$DEST" +for skill in "${SKILLS[@]}"; do + [[ -f "$SRC/skills/cloud/$skill/SKILL.md" ]] || { echo "error: $skill not found upstream" >&2; exit 1; } + cp -R "$SRC/skills/cloud/$skill" "$DEST/$skill" +done +cp "$SRC/LICENSE" "$DEST/LICENSE" + +( + cd "$DEST" + find . -type f ! -name SHA256SUMS ! -name VENDOR.md | sed 's#^\./##' | LC_ALL=C sort \ + | while IFS= read -r file; do sha256sum "$file"; done > SHA256SUMS +) + +{ + echo "# Vendored Agent Skills: google/skills" + echo + echo "Unmodified copies of upstream Agent Skills. Do not edit these files; re-run" + echo "\`scripts/sync-vendored-skills.sh \` and review the diff instead (ADR-0002)." + echo + echo "- Source: https://github.com/$REPO" + echo "- Commit: \`$COMMIT\`" + echo "- Synced: $(date -u +%Y-%m-%d)" + echo "- Licence: Apache License 2.0, see \`LICENSE\`" + echo "- Integrity: \`SHA256SUMS\` lists every vendored file; \`tests/test_vendored_skills.py\` verifies it." + echo + echo "## Skills" + echo + for skill in "${SKILLS[@]}"; do + echo "- \`$skill\` (upstream \`skills/cloud/$skill\`)" + done +} > "$DEST/VENDOR.md" + +echo "Vendored ${#SKILLS[@]} skills into ${DEST#"$ROOT"/}" diff --git a/skills/cloud-discovery/SKILL.md b/skills/cloud-discovery/SKILL.md new file mode 100644 index 0000000..976886a --- /dev/null +++ b/skills/cloud-discovery/SKILL.md @@ -0,0 +1,38 @@ +--- +name: cloud-discovery +description: >- + Discovers and documents the current state of a workload's existing cloud + environment through the Cloud provider's read-only MCP discovery tools. Use + when requirements discovery needs the as-is architecture of resources that + already run in the user's cloud project or account. +metadata: + scope: requirements-discovery +--- + +# Cloud discovery + +Describe what actually exists, so requirements rest on facts rather than recollection. + +## Before you discover + +Your discovery tools read the user's live cloud environment. The first call may pause the Execution to ask the user's permission. When permission is refused, work only from what the user tells you. + +Ask the user which project, subscription or account and which regions hold the workload, unless the request already says. Discover only there. + +## Steps + +1. **Inventory first.** Use the broadest inventory tool available (an asset inventory or project search) to list the resource types and counts in scope. +2. **Detail what matters.** For each resource type that belongs to the workload, call the product's list and get tools for configuration: sizes, regions and zones, scaling, networking, identities and their roles. +3. **Map relationships.** Connect compute to its data stores, messaging, load balancers and identities, from configuration you have read, not from names alone. +4. **Record gaps.** When a tool reports a discovery gap (a server that's unavailable, an API that isn't enabled, a permission that's missing), list it under `Assumptions / discovery gaps` with the resource type it leaves unknown. + +## Writing the current state + +Under the `Current state` heading, give: + +- a component inventory table: component, resource type, location, key configuration +- the relationships between components as a short list +- observed operational signals, such as alert policies and dashboards, when discovered +- `Assumptions / discovery gaps` + +Report what exists, not what should change; recommendations belong to later Deliverables. Never include secrets, credentials, object contents or database rows, even when a tool returns them. diff --git a/skills/google-cloud-iac-modules/SKILL.md b/skills/google-cloud-iac-modules/SKILL.md new file mode 100644 index 0000000..eeb224d --- /dev/null +++ b/skills/google-cloud-iac-modules/SKILL.md @@ -0,0 +1,56 @@ +--- +name: google-cloud-iac-modules +description: >- + Published Terraform modules from the terraform-google-modules organisation + that are known to validate against the pinned hashicorp/google provider: VPC + network with Cloud NAT, private Cloud SQL for PostgreSQL, Cloud Storage + buckets and Cloud KMS. Use when writing Terraform for an Element that one of + these modules covers, to decide whether a module or plain resources fit and to + call the module correctly. +metadata: + scope: deployment guidance, validation results + provider: hashicorp/google 8.6.0 + modules: terraform-google-modules +--- + +# Google Cloud IaC modules + +You have this Skill because this Execution opted into published modules: `terraform_modules` is true in your context. Without that, infrastructure code is plain resources and a module call is refused. + +A published module replaces several resources that must be wired together with one call that a team already maintains. It also hides the resources a Check is about. Use one only where the first outweighs the second. + +## When to use a module + +Use a module when **all** of these hold: + +1. It is in the table below. Those are the only modules checked against `hashicorp/google` 8.6.0; a test validates each one's example here. +2. It replaces three or more resources that depend on each other, such as a network with its subnets and firewall rules, or a private database with the peering it needs. +3. Every Check on the Elements it covers can be met through one of its inputs. Confirm with `terraform_module`. + +Otherwise write the resources directly, from the patterns Skill. A single resource, such as one service account, one topic or one secret, is always written directly. + +| For | Module | Version | Reference | +| --- | --- | --- | --- | +| VPC, subnets, firewall rules, and Cloud NAT | `terraform-google-modules/network/google` and `terraform-google-modules/cloud-nat/google` | 18.3.1, 7.1.0 | `references/network.md` | +| Cloud SQL for PostgreSQL on a private address | `terraform-google-modules/sql-db/google//modules/postgresql` with `//modules/private_service_access` | 28.3.0 | `references/cloud-sql.md` | +| A Cloud Storage bucket with retention, lifecycle, encryption and grants | `terraform-google-modules/cloud-storage/google//modules/simple_bucket` | 12.4.1 | `references/cloud-storage.md` | +| A key ring, keys and their grants | `terraform-google-modules/kms/google` | 4.2.1 | `references/kms.md` | + +Not usable with this provider version, so write these directly: the load balancer (`lb-http`), Pub/Sub, BigQuery, GKE, log export and the function modules all require `google` below 8. `terraform_module` says so for any module you look up. + +## Rules for every module call + +- `source` is `terraform-google-modules//google`, with `//modules/` when the table gives one. `version` is one exact version. `terraform_validate` refuses any other source, a Git URL, a local path or a version range. +- Keep `terraform/versions.tf` from the patterns Skill unchanged. A module's own provider requirements are met by it. +- Pass every environment-specific value from a variable, as for resources. +- Before using an input the reference does not show, call `terraform_module` with `find` set to its name. +- Set every input a Check depends on, even when the module's default already gives that value. A Check is verified from a value written in the code; a default left unset can only be argued from the module's documentation, and changes when the module does. +- A module takes names, not always ids: read which one an input wants. Pass another module's output where one depends on the other, so Terraform orders them. + +## Checks on an Element a module creates + +A Check is still about the resource: "the instance has no public IP address". The code meets it through a module input. + +- In `implementation.json`, `address` names the module and the input: `module.database.ip_configuration.ipv4_enabled`. +- When no input sets what a Check needs, the module does not fit that Element. Write its resources directly; do not mark the Check unimplementable, since the resource type does have the setting. +- When validating, read the input's value in the code and confirm with `terraform_module` what that input sets. An input left at its default is judged by the default the lookup shows, and the verdict says the value is a default and not set in the code. A Check is not verifiable only when neither the code nor the module's documentation shows what the resource will get. diff --git a/skills/google-cloud-iac-modules/references/cloud-sql.md b/skills/google-cloud-iac-modules/references/cloud-sql.md new file mode 100644 index 0000000..93601e1 --- /dev/null +++ b/skills/google-cloud-iac-modules/references/cloud-sql.md @@ -0,0 +1,102 @@ +# Cloud SQL for PostgreSQL on a private address + +A PostgreSQL instance reachable only inside a VPC, with the private services access it needs. Replaces a reserved range, a service networking connection, the instance, its database and its user. + +- The instance must wait for the peering: pass `module.private_access.peering_completed` in `module_depends_on`. +- `ip_configuration.ipv4_enabled = false` is what removes the public address. `private_network` is the network's self link. +- `availability_type = "REGIONAL"` gives a standby in a second zone. +- `deletion_protection` is the Terraform guard; `deletion_protection_enabled` is the guard in the API. Set both from a variable. +- With `enable_default_user = true` the module generates a password and exposes it as an output. Prefer IAM database authentication: set `enable_default_user = false`, add the `cloudsql.iam_authentication` flag and list `iam_users`. +- `random_instance_name = true` adds a suffix, which lets an instance be recreated: a deleted instance's name is reserved for a week. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "network_name" { + type = string + description = "Name of the VPC the database is reached from." +} + +variable "network_self_link" { + type = string + description = "Self link of that VPC." +} + +variable "app_service_account_email" { + type = string + description = "Service account that connects to the database." +} + +variable "deletion_protection" { + type = bool + description = "Whether the instance is protected from deletion." + default = true +} + +module "private_access" { + source = "terraform-google-modules/sql-db/google//modules/private_service_access" + version = "28.3.0" + + project_id = var.project_id + vpc_network = var.network_name + prefix_length = 20 +} + +module "database" { + source = "terraform-google-modules/sql-db/google//modules/postgresql" + version = "28.3.0" + + project_id = var.project_id + region = var.region + name = "workload" + random_instance_name = true + database_version = "POSTGRES_16" + edition = "ENTERPRISE" + tier = "db-custom-2-7680" + availability_type = "REGIONAL" + disk_autoresize = true + + deletion_protection = var.deletion_protection + deletion_protection_enabled = var.deletion_protection + + ip_configuration = { + ipv4_enabled = false + private_network = var.network_self_link + ssl_mode = "ENCRYPTED_ONLY" + } + + backup_configuration = { + enabled = true + start_time = "02:00" + point_in_time_recovery_enabled = true + retained_backups = 14 + retention_unit = "COUNT" + } + + database_flags = [ + { + name = "cloudsql.iam_authentication" + value = "on" + } + ] + + db_name = "app" + enable_default_user = false + iam_users = [ + { + id = "app" + email = var.app_service_account_email + } + ] + + module_depends_on = [module.private_access.peering_completed] +} +``` diff --git a/skills/google-cloud-iac-modules/references/cloud-storage.md b/skills/google-cloud-iac-modules/references/cloud-storage.md new file mode 100644 index 0000000..a9bb276 --- /dev/null +++ b/skills/google-cloud-iac-modules/references/cloud-storage.md @@ -0,0 +1,68 @@ +# Cloud Storage bucket + +One bucket with its retention, lifecycle rules, encryption and grants. Use the module when the bucket has several of those; a plain bucket is one resource and is written directly. + +- The module turns on uniform bucket-level access (`bucket_policy_only`) and `public_access_prevention = "enforced"` unless told otherwise. +- `retention_policy.retention_period` is in seconds. `is_locked = true` cannot be undone, and the bucket cannot then be deleted until every object has aged out: take it from a variable. +- `lifecycle_rules` takes `action` and `condition` as maps; condition values that are lists are given as comma-separated strings. +- `encryption.default_kms_key_name` needs the Cloud Storage service agent to hold the encrypter/decrypter role on the key first. +- `iam_members` grants on the bucket only, with `_iam_member`, so grants made elsewhere are kept. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "lock_retention" { + type = bool + description = "Whether the retention policy is locked. Locking cannot be undone." + default = false +} + +variable "reader_service_account_email" { + type = string + description = "Service account that reads the archive." +} + +module "archive" { + source = "terraform-google-modules/cloud-storage/google//modules/simple_bucket" + version = "12.4.1" + + project_id = var.project_id + name = "${var.project_id}-archive" + location = var.region + storage_class = "STANDARD" + versioning = true + force_destroy = false + + retention_policy = { + is_locked = var.lock_retention + retention_period = 220752000 + } + + lifecycle_rules = [ + { + action = { + type = "SetStorageClass" + storage_class = "ARCHIVE" + } + condition = { + age = 365 + } + } + ] + + iam_members = [ + { + role = "roles/storage.objectViewer" + member = "serviceAccount:${var.reader_service_account_email}" + } + ] +} +``` diff --git a/skills/google-cloud-iac-modules/references/kms.md b/skills/google-cloud-iac-modules/references/kms.md new file mode 100644 index 0000000..69137ef --- /dev/null +++ b/skills/google-cloud-iac-modules/references/kms.md @@ -0,0 +1,54 @@ +# Cloud KMS key ring and keys + +A key ring, its keys and the grants that let products use them. Replaces a key ring, each key and each grant. + +- The key ring's `location` must match the resource it protects. +- `prevent_destroy` is true unless set otherwise; keys and key rings cannot be deleted from Google Cloud in any case. +- `key_rotation_period` is in seconds with an `s`, such as `"7776000s"` for 90 days. +- `set_encrypters_for` and `set_decrypters_for` name the keys; `encrypters` and `decrypters` give one comma-separated string of members per key, in the same order. +- The member is the product's service agent, not the workload's service account. +- `module.kms.keys` is a map from key name to key id. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +data "google_storage_project_service_account" "this" { + project = var.project_id +} + +module "kms" { + source = "terraform-google-modules/kms/google" + version = "4.2.1" + + project_id = var.project_id + location = var.region + keyring = "workload" + keys = ["data"] + key_rotation_period = "7776000s" + prevent_destroy = true + + set_encrypters_for = ["data"] + set_decrypters_for = ["data"] + encrypters = ["serviceAccount:${data.google_storage_project_service_account.this.email_address}"] + decrypters = ["serviceAccount:${data.google_storage_project_service_account.this.email_address}"] +} + +resource "google_storage_bucket" "encrypted" { + project = var.project_id + name = "${var.project_id}-encrypted" + location = var.region + uniform_bucket_level_access = true + + encryption { + default_kms_key_name = module.kms.keys["data"] + } +} +``` diff --git a/skills/google-cloud-iac-modules/references/network.md b/skills/google-cloud-iac-modules/references/network.md new file mode 100644 index 0000000..983f2fc --- /dev/null +++ b/skills/google-cloud-iac-modules/references/network.md @@ -0,0 +1,68 @@ +# VPC network and Cloud NAT + +A custom-mode VPC with its subnets and firewall rules, and outbound internet through Cloud NAT. Replaces a network, its subnetworks, a router, a NAT and each firewall rule. + +- `subnets` is a list of objects whose values are all strings, including `"true"` for `subnet_private_access`. +- `network_name` is a name. Other resources want `module.network.network_self_link` or `network_id`; `subnets` is an output map keyed `"/"`. +- `ingress_rules` replaces the deprecated `firewall_rules`. +- The NAT module creates its router when `create_router = true`, and then needs `network`. +- Set `name` on the NAT. Left unset it gets a random suffix. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +module "network" { + source = "terraform-google-modules/network/google" + version = "18.3.1" + + project_id = var.project_id + network_name = "workload" + routing_mode = "REGIONAL" + + subnets = [ + { + subnet_name = "workload" + subnet_ip = "10.10.0.0/24" + subnet_region = var.region + subnet_private_access = "true" + subnet_flow_logs = "true" + } + ] + + ingress_rules = [ + { + name = "allow-health-checks" + source_ranges = ["130.211.0.0/22", "35.191.0.0/16"] + allow = [ + { + protocol = "tcp" + ports = ["8080"] + } + ] + } + ] +} + +module "nat" { + source = "terraform-google-modules/cloud-nat/google" + version = "7.1.0" + + project_id = var.project_id + region = var.region + name = "workload-nat" + create_router = true + router = "workload-router" + network = module.network.network_self_link + + log_config_enable = true + log_config_filter = "ERRORS_ONLY" +} +``` diff --git a/skills/google-cloud-iac-patterns/SKILL.md b/skills/google-cloud-iac-patterns/SKILL.md new file mode 100644 index 0000000..dcc6a47 --- /dev/null +++ b/skills/google-cloud-iac-patterns/SKILL.md @@ -0,0 +1,54 @@ +--- +name: google-cloud-iac-patterns +description: >- + Terraform patterns for Google Cloud products that validate against one pinned + version of the hashicorp/google provider: Cloud Run services and jobs, + Pub/Sub, Cloud Storage, IAM, Secret Manager, Cloud KMS, Cloud SQL, + networking, load balancing, Cloud Scheduler, Artifact Registry, Monitoring, + Firestore, BigQuery, Eventarc, GKE and API enablement. Use when writing + Terraform for a Google Cloud product, before writing the resource, to start + from a pattern whose arguments are known to be in the right place. +metadata: + scope: deployment guidance + provider: hashicorp/google 8.6.0 +--- + +# Google Cloud IaC patterns + +Every pattern here passes `terraform validate` against `hashicorp/google` 8.6.0. A test runs that on each of them, so an argument you copy from a pattern is in the right block. + +## How to use them + +1. Write `assets/versions.tf` to your working copy as `terraform/versions.tf`, unchanged. It pins the provider version these patterns and the `terraform_schema` tool describe. Declare the `project_id` and `region` variables it uses in `terraform/variables.tf`. +2. For each Element in the Target architecture, read the reference for its product with `load_skill_resource` and start from its pattern. Read only the references for products the Target architecture uses. +3. Change the pattern to meet the Element's Checks. For a setting the pattern does not show, call `terraform_schema` with `find` set to its name before you write it. + +| Product | Reference | +| --- | --- | +| Enabling APIs | `references/project-services.md` | +| Service accounts and IAM grants | `references/iam.md` | +| Cloud Run service | `references/cloud-run-service.md` | +| Cloud Run job | `references/cloud-run-job.md` | +| Pub/Sub | `references/pubsub.md` | +| Cloud Storage | `references/cloud-storage.md` | +| Secret Manager | `references/secret-manager.md` | +| Cloud KMS | `references/kms.md` | +| Cloud SQL | `references/cloud-sql.md` | +| VPC networking | `references/networking.md` | +| External Application Load Balancer, TLS policy, firewall policy, Identity-Aware Proxy | `references/load-balancer.md` | +| Cloud Scheduler | `references/cloud-scheduler.md` | +| Artifact Registry | `references/artifact-registry.md` | +| Cloud Monitoring and Logging | `references/monitoring.md` | +| Firestore | `references/firestore.md` | +| BigQuery | `references/bigquery.md` | +| Eventarc | `references/eventarc.md` | +| Google Kubernetes Engine | `references/gke.md` | + +A product with no reference has no pattern yet: write it from `terraform_schema` and the product documentation. + +## Rules that hold for every product + +- A Cloud Run service and a Cloud Run job are different resource types with different arguments. A setting of one is not a setting of the other. `references/cloud-run-job.md` lists what a job lacks. +- Grant a role with an `_iam_member` resource. An `_iam_binding` or `_iam_policy` resource removes grants made elsewhere. +- Give a Google-managed service agent its role before the resource that needs it, with `depends_on`. A key, a dead-letter topic and a push subscription all need one. +- Set `deletion_protection` from a variable on the resources that have it, so a test deployment can be removed. diff --git a/skills/google-cloud-iac-patterns/assets/versions.tf b/skills/google-cloud-iac-patterns/assets/versions.tf new file mode 100644 index 0000000..ab27780 --- /dev/null +++ b/skills/google-cloud-iac-patterns/assets/versions.tf @@ -0,0 +1,15 @@ +terraform { + required_version = ">= 1.9" + + required_providers { + google = { + source = "hashicorp/google" + version = "8.6.0" + } + } +} + +provider "google" { + project = var.project_id + region = var.region +} diff --git a/skills/google-cloud-iac-patterns/references/artifact-registry.md b/skills/google-cloud-iac-patterns/references/artifact-registry.md new file mode 100644 index 0000000..ea502d4 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/artifact-registry.md @@ -0,0 +1,65 @@ +# Artifact Registry + +A Docker repository with a cleanup policy, and the grant that lets a runtime identity pull from it. + +- `format = "DOCKER"` for container images. The image path is `REGION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE`. +- Cleanup policies delete nothing while `cleanup_policy_dry_run` is `true`. +- `docker_config.immutable_tags = true` stops a tag being moved to a different image. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +resource "google_service_account" "runtime" { + project = var.project_id + account_id = "image-puller" + display_name = "Pulls workload images" +} + +resource "google_artifact_registry_repository" "images" { + project = var.project_id + location = var.region + repository_id = "workload-images" + format = "DOCKER" + description = "Container images for the workload." + cleanup_policy_dry_run = false + + docker_config { + immutable_tags = true + } + + cleanup_policies { + id = "keep-recent" + action = "KEEP" + + most_recent_versions { + keep_count = 10 + } + } + + cleanup_policies { + id = "delete-old-untagged" + action = "DELETE" + + condition { + tag_state = "UNTAGGED" + older_than = "2592000s" + } + } +} + +resource "google_artifact_registry_repository_iam_member" "runtime_pulls" { + project = var.project_id + location = google_artifact_registry_repository.images.location + repository = google_artifact_registry_repository.images.name + role = "roles/artifactregistry.reader" + member = google_service_account.runtime.member +} +``` diff --git a/skills/google-cloud-iac-patterns/references/bigquery.md b/skills/google-cloud-iac-patterns/references/bigquery.md new file mode 100644 index 0000000..aa5bde3 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/bigquery.md @@ -0,0 +1,92 @@ +# BigQuery + +A dataset, a partitioned and clustered table, and the grants for a writer and a reader. + +- `location` is a region or `EU`/`US`, and cannot be changed. Queries cannot join datasets in different locations. +- `delete_contents_on_destroy = false` makes Terraform refuse to remove a dataset that still has tables. +- A table's `deletion_protection` is true unless set; take it from a variable so a test deployment can be removed. +- `schema` is a JSON string. Changing a column's type or mode replaces the table. +- Partition on a `DATE` or `TIMESTAMP` column with `time_partitioning`, and set `require_partition_filter` so a query cannot scan every partition. `expiration_ms` there removes old partitions. +- Grant on the dataset with `google_bigquery_dataset_iam_member`. A principal that runs queries also needs `roles/bigquery.jobUser` on the project. +- Do not mix `google_bigquery_dataset_iam_member` with `access` blocks on the dataset: each removes what the other sets. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "writer_service_account_email" { + type = string + description = "Service account that loads rows." +} + +variable "reader_service_account_email" { + type = string + description = "Service account that queries the dataset." +} + +variable "deletion_protection" { + type = bool + description = "Whether the table is protected from deletion." + default = true +} + +resource "google_bigquery_dataset" "analytics" { + project = var.project_id + dataset_id = "analytics" + location = var.region + delete_contents_on_destroy = false + + default_table_expiration_ms = null + max_time_travel_hours = 168 +} + +resource "google_bigquery_table" "events" { + project = var.project_id + dataset_id = google_bigquery_dataset.analytics.dataset_id + table_id = "events" + deletion_protection = var.deletion_protection + + require_partition_filter = true + clustering = ["event_type"] + + time_partitioning { + type = "DAY" + field = "event_time" + expiration_ms = 34560000000 + } + + schema = jsonencode([ + { name = "event_id", type = "STRING", mode = "REQUIRED" }, + { name = "event_type", type = "STRING", mode = "REQUIRED" }, + { name = "event_time", type = "TIMESTAMP", mode = "REQUIRED" }, + { name = "payload", type = "JSON", mode = "NULLABLE" } + ]) +} + +resource "google_bigquery_dataset_iam_member" "writer" { + project = var.project_id + dataset_id = google_bigquery_dataset.analytics.dataset_id + role = "roles/bigquery.dataEditor" + member = "serviceAccount:${var.writer_service_account_email}" +} + +resource "google_bigquery_dataset_iam_member" "reader" { + project = var.project_id + dataset_id = google_bigquery_dataset.analytics.dataset_id + role = "roles/bigquery.dataViewer" + member = "serviceAccount:${var.reader_service_account_email}" +} + +resource "google_project_iam_member" "reader_runs_queries" { + project = var.project_id + role = "roles/bigquery.jobUser" + member = "serviceAccount:${var.reader_service_account_email}" +} +``` diff --git a/skills/google-cloud-iac-patterns/references/cloud-run-job.md b/skills/google-cloud-iac-patterns/references/cloud-run-job.md new file mode 100644 index 0000000..a01d9fe --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/cloud-run-job.md @@ -0,0 +1,95 @@ +# Cloud Run job + +`google_cloud_run_v2_job`: a task that runs to completion. It is a different resource type from a service, and its template is nested one level deeper. + +What a job does not have. A Check that asks for one of these on a job cannot be met: + +- `startup_cpu_boost` and `cpu_idle`. A job's `resources` block has `limits` only. +- `ingress`, `traffic`, `scaling`, `min_instance_count`, `max_instance_request_concurrency`. A job answers no requests. +- `liveness_probe`. A job's container has a `startup_probe` only. + +Where a job's settings sit: + +- `task_count` and `parallelism` are in `template`. +- `service_account`, `timeout`, `max_retries`, `execution_environment`, `vpc_access` and `encryption_key` are in `template.template`. +- `image`, `env`, `args`, `command` and `resources` are in `template.template.containers`. +- Whoever starts the job needs `roles/run.invoker` on it; Cloud Scheduler starts it with an HTTP call to the `:run` method. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "image" { + type = string + description = "Container image reference, including the tag or digest." +} + +variable "deletion_protection" { + type = bool + description = "Whether Terraform is prevented from deleting the job." + default = true +} + +resource "google_service_account" "replay" { + project = var.project_id + account_id = "replay-job" + display_name = "Replay job" +} + +resource "google_cloud_run_v2_job" "replay" { + project = var.project_id + name = "replay" + location = var.region + deletion_protection = var.deletion_protection + + template { + task_count = 1 + parallelism = 1 + + template { + service_account = google_service_account.replay.email + timeout = "3600s" + max_retries = 3 + execution_environment = "EXECUTION_ENVIRONMENT_GEN2" + + containers { + image = var.image + args = ["--mode=replay"] + + resources { + limits = { + cpu = "1" + memory = "1Gi" + } + } + + env { + name = "BATCH_SIZE" + value = "100" + } + } + } + } +} + +resource "google_service_account" "operator" { + project = var.project_id + account_id = "replay-operator" + display_name = "Starts the replay job" +} + +resource "google_cloud_run_v2_job_iam_member" "operator_runs_replay" { + project = var.project_id + location = google_cloud_run_v2_job.replay.location + name = google_cloud_run_v2_job.replay.name + role = "roles/run.invoker" + member = google_service_account.operator.member +} +``` diff --git a/skills/google-cloud-iac-patterns/references/cloud-run-service.md b/skills/google-cloud-iac-patterns/references/cloud-run-service.md new file mode 100644 index 0000000..fb08680 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/cloud-run-service.md @@ -0,0 +1,144 @@ +# Cloud Run service + +`google_cloud_run_v2_service`: a long-running service that answers requests. + +Where the settings sit, which is what goes wrong most often: + +- `ingress`, `deletion_protection` and `traffic` are on the resource. +- `service_account`, `scaling`, `timeout`, `max_instance_request_concurrency`, `execution_environment`, `vpc_access` and `encryption_key` are in `template`. +- `image`, `env`, `ports`, `resources` and the probes are in `template.containers`. +- `cpu_idle` and `startup_cpu_boost` are in `template.containers.resources`, beside `limits`. They exist on a service only. +- `min_instance_count` and `max_instance_count` are in `template.scaling`. +- A secret is read through `env.value_source.secret_key_ref`; the service account needs `roles/secretmanager.secretAccessor` on that secret. +- Direct VPC egress is `template.vpc_access.network_interfaces`. A connector is `template.vpc_access.connector`. Use one of them. +- Public access is a grant of `roles/run.invoker` to `allUsers` together with `ingress = "INGRESS_TRAFFIC_ALL"`. A private service has neither. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "image" { + type = string + description = "Container image reference, including the tag or digest." +} + +variable "deletion_protection" { + type = bool + description = "Whether Terraform is prevented from deleting the service." + default = true +} + +resource "google_service_account" "ingest" { + project = var.project_id + account_id = "ingest-service" + display_name = "Ingest service" +} + +resource "google_secret_manager_secret" "signing_key" { + project = var.project_id + secret_id = "webhook-signing-key" + + replication { + auto {} + } +} + +resource "google_secret_manager_secret_iam_member" "ingest_reads_signing_key" { + project = var.project_id + secret_id = google_secret_manager_secret.signing_key.secret_id + role = "roles/secretmanager.secretAccessor" + member = google_service_account.ingest.member +} + +resource "google_cloud_run_v2_service" "ingest" { + project = var.project_id + name = "ingest" + location = var.region + ingress = "INGRESS_TRAFFIC_ALL" + deletion_protection = var.deletion_protection + + template { + service_account = google_service_account.ingest.email + timeout = "30s" + max_instance_request_concurrency = 80 + execution_environment = "EXECUTION_ENVIRONMENT_GEN2" + + scaling { + min_instance_count = 1 + max_instance_count = 10 + } + + containers { + image = var.image + + ports { + container_port = 8080 + } + + resources { + limits = { + cpu = "1" + memory = "512Mi" + } + cpu_idle = true + startup_cpu_boost = true + } + + env { + name = "LOG_LEVEL" + value = "info" + } + + env { + name = "SIGNING_KEY" + value_source { + secret_key_ref { + secret = google_secret_manager_secret.signing_key.secret_id + version = "latest" + } + } + } + + startup_probe { + initial_delay_seconds = 0 + period_seconds = 5 + failure_threshold = 6 + http_get { + path = "/healthz" + } + } + + liveness_probe { + period_seconds = 30 + http_get { + path = "/healthz" + } + } + } + } + + traffic { + type = "TRAFFIC_TARGET_ALLOCATION_TYPE_LATEST" + percent = 100 + } + + depends_on = [google_secret_manager_secret_iam_member.ingest_reads_signing_key] +} + +# Public access. Leave this out, and set ingress to INGRESS_TRAFFIC_INTERNAL_ONLY, +# for a service only other workloads call. +resource "google_cloud_run_v2_service_iam_member" "public" { + project = var.project_id + location = google_cloud_run_v2_service.ingest.location + name = google_cloud_run_v2_service.ingest.name + role = "roles/run.invoker" + member = "allUsers" +} +``` diff --git a/skills/google-cloud-iac-patterns/references/cloud-scheduler.md b/skills/google-cloud-iac-patterns/references/cloud-scheduler.md new file mode 100644 index 0000000..a98e043 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/cloud-scheduler.md @@ -0,0 +1,75 @@ +# Cloud Scheduler + +A schedule that starts a Cloud Run job, and one that calls a private Cloud Run service. + +- A job is started by an HTTP POST to its `:run` method with an OAuth token (`oauth_token`). A service is called with an OIDC token (`oidc_token`). Using the wrong one is refused at run time, not by `terraform validate`. +- The schedule's service account needs `roles/run.invoker` on the job or service it starts. +- `schedule` is unix-cron; `time_zone` is an IANA name. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "job_name" { + type = string + description = "Name of the Cloud Run job to start." +} + +variable "service_url" { + type = string + description = "HTTPS URL of the private Cloud Run service to call." +} + +resource "google_service_account" "scheduler" { + project = var.project_id + account_id = "nightly-scheduler" + display_name = "Identity of the nightly schedules" +} + +resource "google_cloud_scheduler_job" "start_job" { + project = var.project_id + region = var.region + name = "start-nightly-job" + schedule = "0 2 * * *" + time_zone = "Etc/UTC" + attempt_deadline = "180s" + + retry_config { + retry_count = 3 + } + + http_target { + http_method = "POST" + uri = "https://run.googleapis.com/v2/projects/${var.project_id}/locations/${var.region}/jobs/${var.job_name}:run" + + oauth_token { + service_account_email = google_service_account.scheduler.email + } + } +} + +resource "google_cloud_scheduler_job" "call_service" { + project = var.project_id + region = var.region + name = "call-nightly-service" + schedule = "30 2 * * *" + time_zone = "Etc/UTC" + + http_target { + http_method = "POST" + uri = "${var.service_url}/tasks/nightly" + + oidc_token { + service_account_email = google_service_account.scheduler.email + audience = var.service_url + } + } +} +``` diff --git a/skills/google-cloud-iac-patterns/references/cloud-sql.md b/skills/google-cloud-iac-patterns/references/cloud-sql.md new file mode 100644 index 0000000..a80ccc0 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/cloud-sql.md @@ -0,0 +1,124 @@ +# Cloud SQL + +A PostgreSQL instance with a private address, backups and IAM database authentication. + +- A private address needs a reserved range and a service networking connection on the VPC first; the instance must `depends_on` the connection. +- `availability_type = "REGIONAL"` is high availability; `"ZONAL"` is a single zone. +- Backups, point-in-time recovery, flags and the address are all in `settings`. +- `deletion_protection` on the resource guards Terraform; `settings.deletion_protection_enabled` guards the API. +- Take the database password from Secret Manager at run time, or use IAM database authentication as here. Never put a password in the configuration. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "deletion_protection" { + type = bool + description = "Whether Terraform is prevented from deleting the instance." + default = true +} + +resource "google_compute_network" "main" { + project = var.project_id + name = "main" + auto_create_subnetworks = false +} + +resource "google_compute_global_address" "private_services" { + project = var.project_id + name = "private-services" + purpose = "VPC_PEERING" + address_type = "INTERNAL" + prefix_length = 16 + network = google_compute_network.main.id +} + +resource "google_service_networking_connection" "private_services" { + network = google_compute_network.main.id + service = "servicenetworking.googleapis.com" + reserved_peering_ranges = [google_compute_global_address.private_services.name] +} + +resource "google_service_account" "app" { + project = var.project_id + account_id = "orders-app" + display_name = "Orders application" +} + +resource "google_sql_database_instance" "orders" { + project = var.project_id + name = "orders" + region = var.region + database_version = "POSTGRES_16" + deletion_protection = var.deletion_protection + + settings { + tier = "db-custom-2-7680" + edition = "ENTERPRISE" + availability_type = "REGIONAL" + disk_type = "PD_SSD" + disk_autoresize = true + deletion_protection_enabled = var.deletion_protection + + ip_configuration { + ipv4_enabled = false + private_network = google_compute_network.main.id + ssl_mode = "ENCRYPTED_ONLY" + } + + backup_configuration { + enabled = true + point_in_time_recovery_enabled = true + start_time = "02:00" + + backup_retention_settings { + retained_backups = 14 + } + } + + database_flags { + name = "cloudsql.iam_authentication" + value = "on" + } + + maintenance_window { + day = 7 + hour = 3 + } + } + + depends_on = [google_service_networking_connection.private_services] +} + +resource "google_sql_database" "orders" { + project = var.project_id + name = "orders" + instance = google_sql_database_instance.orders.name +} + +resource "google_sql_user" "app" { + project = var.project_id + name = trimsuffix(google_service_account.app.email, ".gserviceaccount.com") + instance = google_sql_database_instance.orders.name + type = "CLOUD_IAM_SERVICE_ACCOUNT" +} + +resource "google_project_iam_member" "app_connects" { + project = var.project_id + role = "roles/cloudsql.client" + member = google_service_account.app.member +} + +resource "google_project_iam_member" "app_logs_in" { + project = var.project_id + role = "roles/cloudsql.instanceUser" + member = google_service_account.app.member +} +``` diff --git a/skills/google-cloud-iac-patterns/references/cloud-storage.md b/skills/google-cloud-iac-patterns/references/cloud-storage.md new file mode 100644 index 0000000..7485408 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/cloud-storage.md @@ -0,0 +1,67 @@ +# Cloud Storage + +A private bucket with a retention period and a lifecycle. + +- Bucket names are global. Build the name from the project id. +- `uniform_bucket_level_access = true` and `public_access_prevention = "enforced"` keep the bucket private. +- `retention_policy.retention_period` is in seconds and stops objects being deleted before then. A lifecycle `Delete` rule with `age` in days removes them after. Retaining for 30 days and then deleting needs both. +- Versioning and a retention policy cannot be used on the same bucket. +- Customer-managed encryption is `encryption.default_kms_key_name`; the Cloud Storage service agent needs `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key first. +- `force_destroy = false` stops Terraform deleting a bucket that holds objects. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +resource "google_service_account" "writer" { + project = var.project_id + account_id = "raw-events-writer" + display_name = "Writes raw events" +} + +resource "google_storage_bucket" "raw_events" { + project = var.project_id + name = "${var.project_id}-raw-events" + location = var.region + storage_class = "STANDARD" + uniform_bucket_level_access = true + public_access_prevention = "enforced" + force_destroy = false + + retention_policy { + retention_period = 2592000 + } + + lifecycle_rule { + condition { + age = 31 + } + action { + type = "Delete" + } + } + + lifecycle_rule { + condition { + age = 7 + } + action { + type = "SetStorageClass" + storage_class = "NEARLINE" + } + } +} + +resource "google_storage_bucket_iam_member" "writer_creates_objects" { + bucket = google_storage_bucket.raw_events.name + role = "roles/storage.objectCreator" + member = google_service_account.writer.member +} +``` diff --git a/skills/google-cloud-iac-patterns/references/eventarc.md b/skills/google-cloud-iac-patterns/references/eventarc.md new file mode 100644 index 0000000..af885b9 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/eventarc.md @@ -0,0 +1,129 @@ +# Eventarc + +A trigger that delivers events to a Cloud Run service: one for messages on a Pub/Sub topic, one for objects finalised in a bucket. + +- A trigger has its own service account. It needs `roles/eventarc.eventReceiver` on the project and `roles/run.invoker` on the service it calls. +- For a Pub/Sub trigger, name an existing topic under `transport.pubsub.topic`; left out, Eventarc creates a topic you do not manage. +- For a Cloud Storage trigger, `location` must be the bucket's location, and the Cloud Storage service agent needs `roles/pubsub.publisher` on the project before the trigger is created. +- `matching_criteria` attributes are exact. `type` is always present; a storage event also needs `bucket`. +- The destination service is named, with its `region`; `path` is optional. +- The service must not allow unauthenticated calls for this to be the only way in: grant `roles/run.invoker` to the trigger's service account only. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "service_name" { + type = string + description = "Name of the Cloud Run service that receives the events." +} + +variable "topic_id" { + type = string + description = "Id of the Pub/Sub topic whose messages are delivered." +} + +variable "bucket_name" { + type = string + description = "Bucket whose new objects are delivered. It must be in var.region." +} + +data "google_storage_project_service_account" "this" { + project = var.project_id +} + +resource "google_service_account" "trigger" { + project = var.project_id + account_id = "eventarc-trigger" + display_name = "Eventarc trigger" +} + +resource "google_project_iam_member" "trigger_receives_events" { + project = var.project_id + role = "roles/eventarc.eventReceiver" + member = "serviceAccount:${google_service_account.trigger.email}" +} + +resource "google_cloud_run_v2_service_iam_member" "trigger_invokes_service" { + project = var.project_id + location = var.region + name = var.service_name + role = "roles/run.invoker" + member = "serviceAccount:${google_service_account.trigger.email}" +} + +resource "google_project_iam_member" "storage_publishes_events" { + project = var.project_id + role = "roles/pubsub.publisher" + member = "serviceAccount:${data.google_storage_project_service_account.this.email_address}" +} + +resource "google_eventarc_trigger" "on_message" { + project = var.project_id + name = "on-message" + location = var.region + service_account = google_service_account.trigger.email + + matching_criteria { + attribute = "type" + value = "google.cloud.pubsub.topic.v1.messagePublished" + } + + transport { + pubsub { + topic = var.topic_id + } + } + + destination { + cloud_run_service { + service = var.service_name + region = var.region + path = "/events/message" + } + } + + depends_on = [ + google_project_iam_member.trigger_receives_events, + google_cloud_run_v2_service_iam_member.trigger_invokes_service, + ] +} + +resource "google_eventarc_trigger" "on_object" { + project = var.project_id + name = "on-object" + location = var.region + service_account = google_service_account.trigger.email + + matching_criteria { + attribute = "type" + value = "google.cloud.storage.object.v1.finalized" + } + + matching_criteria { + attribute = "bucket" + value = var.bucket_name + } + + destination { + cloud_run_service { + service = var.service_name + region = var.region + path = "/events/object" + } + } + + depends_on = [ + google_project_iam_member.trigger_receives_events, + google_project_iam_member.storage_publishes_events, + google_cloud_run_v2_service_iam_member.trigger_invokes_service, + ] +} +``` diff --git a/skills/google-cloud-iac-patterns/references/firestore.md b/skills/google-cloud-iac-patterns/references/firestore.md new file mode 100644 index 0000000..be28acc --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/firestore.md @@ -0,0 +1,74 @@ +# Firestore + +A Firestore database in Native mode, with point-in-time recovery, a scheduled backup, a composite index and the grant a workload needs. + +- A project's first database is named `(default)`. Any other name creates an additional database, which clients must name when they connect. +- `location_id` is a region or a multi-region such as `eur3`, and cannot be changed afterwards. +- `type` is `FIRESTORE_NATIVE` or `DATASTORE_MODE`, and cannot be changed once the database holds data. +- `delete_protection_state` is the guard in the API; `deletion_policy = "DELETE"` is needed before Terraform will remove a database at all. +- `point_in_time_recovery_enablement` keeps seven days of versions. A backup schedule is separate and keeps whole backups for `retention`, in seconds with an `s`. +- A workload reads and writes with `roles/datastore.user`, granted on the project. There is no per-database role; restrict with an IAM condition on the database name. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "app_service_account_email" { + type = string + description = "Service account of the workload that uses the database." +} + +resource "google_firestore_database" "app" { + project = var.project_id + name = "app" + location_id = var.region + type = "FIRESTORE_NATIVE" + + concurrency_mode = "OPTIMISTIC" + point_in_time_recovery_enablement = "POINT_IN_TIME_RECOVERY_ENABLED" + delete_protection_state = "DELETE_PROTECTION_ENABLED" + deletion_policy = "ABANDON" +} + +resource "google_firestore_backup_schedule" "daily" { + project = var.project_id + database = google_firestore_database.app.name + retention = "1209600s" + + daily_recurrence {} +} + +resource "google_firestore_index" "orders_by_customer" { + project = var.project_id + database = google_firestore_database.app.name + collection = "orders" + + fields { + field_path = "customer_id" + order = "ASCENDING" + } + + fields { + field_path = "created_at" + order = "DESCENDING" + } +} + +resource "google_project_iam_member" "app_uses_firestore" { + project = var.project_id + role = "roles/datastore.user" + member = "serviceAccount:${var.app_service_account_email}" + + condition { + title = "only-the-app-database" + expression = "resource.name == \"${google_firestore_database.app.id}\" || resource.name.startsWith(\"${google_firestore_database.app.id}/\")" + } +} +``` diff --git a/skills/google-cloud-iac-patterns/references/gke.md b/skills/google-cloud-iac-patterns/references/gke.md new file mode 100644 index 0000000..41d6004 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/gke.md @@ -0,0 +1,109 @@ +# Google Kubernetes Engine + +A private Autopilot cluster on an existing subnet, with its node service account and Workload Identity for one workload. + +- `enable_autopilot = true` makes Google manage the nodes. Node pools, machine types and node counts are then not yours to set: leave out `node_pool`, `node_config` and `initial_node_count`. +- A regional `location` gives a control plane in three zones. A zone gives one. +- The subnet needs two secondary ranges, for Pods and Services, named in `ip_allocation_policy`. +- `enable_private_nodes = true` gives nodes no public address; they then need Cloud NAT to pull images from outside Google. +- `master_authorized_networks_config` limits who can reach the control plane. With `enable_private_endpoint = true` it has no public address at all. +- Give nodes a dedicated service account with `roles/container.defaultNodeServiceAccount`, not the Compute Engine default account. +- Autopilot has Workload Identity on. A Kubernetes service account acts as a Google service account through `roles/iam.workloadIdentityUser`, with the member `serviceAccount:PROJECT.svc.id.goog[NAMESPACE/KSA]`. +- `deletion_protection` is true unless set; take it from a variable. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "network_id" { + type = string + description = "Id of the VPC the cluster is in." +} + +variable "subnetwork_id" { + type = string + description = "Id of the subnet for nodes. It has secondary ranges named pods and services." +} + +variable "admin_cidr" { + type = string + description = "Range allowed to reach the control plane." +} + +variable "deletion_protection" { + type = bool + description = "Whether the cluster is protected from deletion." + default = true +} + +resource "google_service_account" "nodes" { + project = var.project_id + account_id = "gke-nodes" + display_name = "GKE nodes" +} + +resource "google_project_iam_member" "nodes_default_role" { + project = var.project_id + role = "roles/container.defaultNodeServiceAccount" + member = "serviceAccount:${google_service_account.nodes.email}" +} + +resource "google_container_cluster" "workload" { + project = var.project_id + name = "workload" + location = var.region + enable_autopilot = true + deletion_protection = var.deletion_protection + + network = var.network_id + subnetwork = var.subnetwork_id + + ip_allocation_policy { + cluster_secondary_range_name = "pods" + services_secondary_range_name = "services" + } + + private_cluster_config { + enable_private_nodes = true + enable_private_endpoint = false + } + + master_authorized_networks_config { + cidr_blocks { + cidr_block = var.admin_cidr + display_name = "administrators" + } + } + + cluster_autoscaling { + auto_provisioning_defaults { + service_account = google_service_account.nodes.email + } + } + + release_channel { + channel = "REGULAR" + } + + depends_on = [google_project_iam_member.nodes_default_role] +} + +resource "google_service_account" "app" { + project = var.project_id + account_id = "orders-app" + display_name = "Orders application" +} + +resource "google_service_account_iam_member" "app_workload_identity" { + service_account_id = google_service_account.app.name + role = "roles/iam.workloadIdentityUser" + member = "serviceAccount:${var.project_id}.svc.id.goog[orders/orders-app]" +} +``` diff --git a/skills/google-cloud-iac-patterns/references/iam.md b/skills/google-cloud-iac-patterns/references/iam.md new file mode 100644 index 0000000..e2c093a --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/iam.md @@ -0,0 +1,40 @@ +# Service accounts and IAM grants + +One service account per workload identity, and one `_iam_member` resource per grant. + +- `account_id` is 6 to 30 characters: lower-case letters, digits and hyphens. +- Use the narrowest resource the role can be granted on: the bucket, topic, secret or service, in preference to the project. +- A grant to a service account is `member = "serviceAccount:${...email}"`. The same value is the `member` attribute of the service account resource. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +resource "google_service_account" "worker" { + project = var.project_id + account_id = "event-worker" + display_name = "Event worker" + description = "Identity of the worker service." +} + +# A project-level role, only when no narrower resource can take the grant. +resource "google_project_iam_member" "worker_metrics" { + project = var.project_id + role = "roles/monitoring.metricWriter" + member = google_service_account.worker.member +} + +# Who may act as the service account, for example a deployment pipeline. +resource "google_service_account_iam_member" "deployer_acts_as_worker" { + service_account_id = google_service_account.worker.name + role = "roles/iam.serviceAccountUser" + member = "serviceAccount:deployer@${var.project_id}.iam.gserviceaccount.com" +} +``` diff --git a/skills/google-cloud-iac-patterns/references/kms.md b/skills/google-cloud-iac-patterns/references/kms.md new file mode 100644 index 0000000..530c496 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/kms.md @@ -0,0 +1,79 @@ +# Cloud KMS + +A key ring and a key for customer-managed encryption, and the grant that lets a product use it. + +- The key ring must be in the same location as the resource it protects. +- Key rings and keys cannot be deleted. `prevent_destroy` stops Terraform trying. +- `rotation_period` is in seconds, such as `"7776000s"` for 90 days. +- The product's service agent, not the workload's service account, needs `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key. The resource that uses the key must `depends_on` that grant. +- Service agents: Pub/Sub is `service-NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com`, Cloud Run is `service-NUMBER@serverless-robot-prod.iam.gserviceaccount.com`, Cloud Storage comes from the `google_storage_project_service_account` data source. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +data "google_project" "this" { + project_id = var.project_id +} + +data "google_storage_project_service_account" "this" { + project = var.project_id +} + +resource "google_kms_key_ring" "workload" { + project = var.project_id + name = "workload" + location = var.region +} + +resource "google_kms_crypto_key" "data" { + name = "data" + key_ring = google_kms_key_ring.workload.id + purpose = "ENCRYPT_DECRYPT" + rotation_period = "7776000s" + + lifecycle { + prevent_destroy = true + } +} + +resource "google_kms_crypto_key_iam_member" "pubsub_uses_key" { + crypto_key_id = google_kms_crypto_key.data.id + role = "roles/cloudkms.cryptoKeyEncrypterDecrypter" + member = "serviceAccount:service-${data.google_project.this.number}@gcp-sa-pubsub.iam.gserviceaccount.com" +} + +resource "google_kms_crypto_key_iam_member" "storage_uses_key" { + crypto_key_id = google_kms_crypto_key.data.id + role = "roles/cloudkms.cryptoKeyEncrypterDecrypter" + member = "serviceAccount:${data.google_storage_project_service_account.this.email_address}" +} + +resource "google_pubsub_topic" "encrypted" { + project = var.project_id + name = "encrypted-events" + kms_key_name = google_kms_crypto_key.data.id + + depends_on = [google_kms_crypto_key_iam_member.pubsub_uses_key] +} + +resource "google_storage_bucket" "encrypted" { + project = var.project_id + name = "${var.project_id}-encrypted" + location = var.region + uniform_bucket_level_access = true + + encryption { + default_kms_key_name = google_kms_crypto_key.data.id + } + + depends_on = [google_kms_crypto_key_iam_member.storage_uses_key] +} +``` diff --git a/skills/google-cloud-iac-patterns/references/load-balancer.md b/skills/google-cloud-iac-patterns/references/load-balancer.md new file mode 100644 index 0000000..b8a1eaf --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/load-balancer.md @@ -0,0 +1,184 @@ +# External Application Load Balancer + +A global HTTPS load balancer in front of a Cloud Run service, with a TLS policy, a web application firewall policy and, optionally, Identity-Aware Proxy. + +The chain is: forwarding rule → target HTTPS proxy → URL map → backend service → serverless network endpoint group → Cloud Run service. Each setting lives on one link of it, and putting one on the wrong link is the usual mistake: + +- **The minimum TLS version is on an SSL policy, attached to the target HTTPS proxy** (`ssl_policy`). A backend service has no `ssl_policy` setting. +- **The certificate is on the target HTTPS proxy** (`ssl_certificates`). +- **The firewall policy is attached to the backend service** (`security_policy`). +- **Identity-Aware Proxy is the `iap` block of the backend service.** It decides who reaches the application; what a signed-in user may do inside it is the application's own code and cannot be shown by infrastructure. +- **Request logging is the `log_config` block of the backend service.** +- A backend service for Cloud Run uses a serverless NEG and takes no `health_checks`, no `port_name` and no `timeout_sec`. +- `load_balancing_scheme = "EXTERNAL_MANAGED"` on both the backend service and the forwarding rule. +- Set the Cloud Run service's `ingress` to `INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`, or it stays reachable around the load balancer. +- Redirecting HTTP to HTTPS needs a second URL map, target HTTP proxy and forwarding rule on port 80. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "domain" { + type = string + description = "Domain name the load balancer serves." +} + +resource "google_cloud_run_v2_service" "app" { + project = var.project_id + name = "booking-app" + location = var.region + ingress = "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER" + + template { + containers { + image = "us-docker.pkg.dev/cloudrun/container/hello" + } + } +} + +resource "google_compute_region_network_endpoint_group" "app" { + project = var.project_id + name = "booking-app" + region = var.region + network_endpoint_type = "SERVERLESS" + + cloud_run { + service = google_cloud_run_v2_service.app.name + } +} + +resource "google_compute_security_policy" "edge" { + project = var.project_id + name = "booking-edge" + + rule { + action = "deny(403)" + priority = 1000 + match { + expr { + expression = "evaluatePreconfiguredWaf('sqli-v33-stable', {'sensitivity': 1})" + } + } + description = "Block SQL injection." + } + + rule { + action = "allow" + priority = 2147483647 + match { + versioned_expr = "SRC_IPS_V1" + config { + src_ip_ranges = ["*"] + } + } + description = "Default rule." + } +} + +resource "google_compute_backend_service" "app" { + project = var.project_id + name = "booking-app" + protocol = "HTTPS" + load_balancing_scheme = "EXTERNAL_MANAGED" + security_policy = google_compute_security_policy.edge.id + + backend { + group = google_compute_region_network_endpoint_group.app.id + } + + # Only signed-in identities granted roles/iap.httpsResourceAccessor get through. + iap { + enabled = true + } + + log_config { + enable = true + sample_rate = 1.0 + } +} + +resource "google_compute_url_map" "app" { + project = var.project_id + name = "booking-app" + default_service = google_compute_backend_service.app.id +} + +resource "google_compute_ssl_policy" "modern" { + project = var.project_id + name = "tls-1-2-modern" + profile = "MODERN" + min_tls_version = "TLS_1_2" +} + +resource "google_compute_managed_ssl_certificate" "app" { + project = var.project_id + name = "booking-app" + + managed { + domains = [var.domain] + } +} + +resource "google_compute_target_https_proxy" "app" { + project = var.project_id + name = "booking-app" + url_map = google_compute_url_map.app.id + ssl_certificates = [google_compute_managed_ssl_certificate.app.id] + ssl_policy = google_compute_ssl_policy.modern.id +} + +resource "google_compute_global_address" "app" { + project = var.project_id + name = "booking-app" +} + +resource "google_compute_global_forwarding_rule" "https" { + project = var.project_id + name = "booking-app-https" + load_balancing_scheme = "EXTERNAL_MANAGED" + ip_address = google_compute_global_address.app.id + port_range = "443" + target = google_compute_target_https_proxy.app.id +} + +# HTTP to HTTPS. +resource "google_compute_url_map" "redirect" { + project = var.project_id + name = "booking-app-redirect" + + default_url_redirect { + https_redirect = true + strip_query = false + } +} + +resource "google_compute_target_http_proxy" "redirect" { + project = var.project_id + name = "booking-app-redirect" + url_map = google_compute_url_map.redirect.id +} + +resource "google_compute_global_forwarding_rule" "http" { + project = var.project_id + name = "booking-app-http" + load_balancing_scheme = "EXTERNAL_MANAGED" + ip_address = google_compute_global_address.app.id + port_range = "80" + target = google_compute_target_http_proxy.redirect.id +} + +# Who may pass Identity-Aware Proxy. +resource "google_iap_web_backend_service_iam_member" "staff" { + project = var.project_id + web_backend_service = google_compute_backend_service.app.name + role = "roles/iap.httpsResourceAccessor" + member = "domain:${var.domain}" +} +``` diff --git a/skills/google-cloud-iac-patterns/references/monitoring.md b/skills/google-cloud-iac-patterns/references/monitoring.md new file mode 100644 index 0000000..9573103 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/monitoring.md @@ -0,0 +1,107 @@ +# Cloud Monitoring and Logging + +A notification channel, an alert on a metric, a log-based metric and a log sink. + +- An alert policy needs `combiner` and at least one `conditions` block. A threshold condition's `filter` must name both a `metric.type` and a `resource.type`. +- Every `aggregations` block needs an `alignment_period` of at least `"60s"` and a `per_series_aligner` that fits the metric kind: `ALIGN_RATE` or `ALIGN_DELTA` for a delta or cumulative metric, `ALIGN_MEAN` or `ALIGN_MAX` for a gauge. +- A log-based metric's name is used in an alert filter as `logging.googleapis.com/user/NAME`. +- A sink's writer identity needs a grant on the destination, or nothing arrives. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "alert_email" { + type = string + description = "Address alerts are sent to." +} + +resource "google_monitoring_notification_channel" "email" { + project = var.project_id + display_name = "Operations email" + type = "email" + + labels = { + email_address = var.alert_email + } +} + +resource "google_monitoring_alert_policy" "server_errors" { + project = var.project_id + display_name = "Cloud Run 5xx responses" + combiner = "OR" + + conditions { + display_name = "5xx rate above 1 per second for 5 minutes" + + condition_threshold { + filter = "resource.type = \"cloud_run_revision\" AND metric.type = \"run.googleapis.com/request_count\" AND metric.labels.response_code_class = \"5xx\"" + comparison = "COMPARISON_GT" + threshold_value = 1 + duration = "300s" + + aggregations { + alignment_period = "60s" + per_series_aligner = "ALIGN_RATE" + cross_series_reducer = "REDUCE_SUM" + group_by_fields = ["resource.labels.service_name"] + } + + trigger { + count = 1 + } + } + } + + notification_channels = [google_monitoring_notification_channel.email.name] + + alert_strategy { + auto_close = "1800s" + } + + documentation { + content = "The service is returning server errors. Check the latest revision's logs." + mime_type = "text/markdown" + } +} + +resource "google_logging_metric" "rejected_signatures" { + project = var.project_id + name = "rejected_signatures" + filter = "resource.type = \"cloud_run_revision\" AND jsonPayload.event = \"signature_rejected\"" + + metric_descriptor { + metric_kind = "DELTA" + value_type = "INT64" + unit = "1" + } +} + +resource "google_storage_bucket" "audit_logs" { + project = var.project_id + name = "${var.project_id}-audit-logs" + location = var.region + uniform_bucket_level_access = true +} + +resource "google_logging_project_sink" "audit" { + project = var.project_id + name = "audit-to-storage" + destination = "storage.googleapis.com/${google_storage_bucket.audit_logs.name}" + filter = "logName:\"cloudaudit.googleapis.com\"" + unique_writer_identity = true +} + +resource "google_storage_bucket_iam_member" "sink_writes" { + bucket = google_storage_bucket.audit_logs.name + role = "roles/storage.objectCreator" + member = google_logging_project_sink.audit.writer_identity +} +``` diff --git a/skills/google-cloud-iac-patterns/references/networking.md b/skills/google-cloud-iac-patterns/references/networking.md new file mode 100644 index 0000000..52f36a0 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/networking.md @@ -0,0 +1,102 @@ +# VPC networking + +A custom-mode VPC, a subnet, outbound internet through Cloud NAT, and a firewall rule. + +- `auto_create_subnetworks = false` gives a custom-mode network: only the subnets you declare. +- `private_ip_google_access = true` lets workloads without external addresses reach Google APIs. +- Cloud Run reaches the VPC with Direct VPC egress: `template.vpc_access.network_interfaces` naming this network and subnet. It needs no connector resource. +- Firewall rules match by `target_service_accounts` or `target_tags`. A rule with neither applies to the whole network. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +resource "google_compute_network" "main" { + project = var.project_id + name = "main" + auto_create_subnetworks = false + routing_mode = "REGIONAL" +} + +resource "google_compute_subnetwork" "workloads" { + project = var.project_id + name = "workloads" + region = var.region + network = google_compute_network.main.id + ip_cidr_range = "10.10.0.0/24" + private_ip_google_access = true + + log_config { + aggregation_interval = "INTERVAL_5_SEC" + flow_sampling = 0.5 + metadata = "INCLUDE_ALL_METADATA" + } +} + +resource "google_compute_router" "egress" { + project = var.project_id + name = "egress" + region = var.region + network = google_compute_network.main.id +} + +resource "google_compute_router_nat" "egress" { + project = var.project_id + name = "egress" + region = var.region + router = google_compute_router.egress.name + nat_ip_allocate_option = "AUTO_ONLY" + source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES" + + log_config { + enable = true + filter = "ERRORS_ONLY" + } +} + +resource "google_compute_firewall" "allow_health_checks" { + project = var.project_id + name = "allow-health-checks" + network = google_compute_network.main.id + direction = "INGRESS" + priority = 1000 + + # Google Cloud load balancer health check ranges. + source_ranges = ["130.211.0.0/22", "35.191.0.0/16"] + target_tags = ["web"] + + allow { + protocol = "tcp" + ports = ["8080"] + } +} + +resource "google_cloud_run_v2_service" "internal" { + project = var.project_id + name = "internal" + location = var.region + ingress = "INGRESS_TRAFFIC_INTERNAL_ONLY" + + template { + containers { + image = "us-docker.pkg.dev/cloudrun/container/hello" + } + + vpc_access { + egress = "PRIVATE_RANGES_ONLY" + + network_interfaces { + network = google_compute_network.main.id + subnetwork = google_compute_subnetwork.workloads.id + } + } + } +} +``` diff --git a/skills/google-cloud-iac-patterns/references/project-services.md b/skills/google-cloud-iac-patterns/references/project-services.md new file mode 100644 index 0000000..5fbd6d9 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/project-services.md @@ -0,0 +1,33 @@ +# Enabling APIs + +Enable each API the Elements need, once, and make the first resource of each product depend on it. + +- `disable_on_destroy = false` keeps the API on when the configuration is destroyed; other workloads in the project may use it. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +locals { + services = [ + "run.googleapis.com", + "pubsub.googleapis.com", + "secretmanager.googleapis.com", + ] +} + +resource "google_project_service" "enabled" { + for_each = toset(local.services) + + project = var.project_id + service = each.value + disable_on_destroy = false +} +``` diff --git a/skills/google-cloud-iac-patterns/references/pubsub.md b/skills/google-cloud-iac-patterns/references/pubsub.md new file mode 100644 index 0000000..bed6838 --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/pubsub.md @@ -0,0 +1,111 @@ +# Pub/Sub + +A topic, a push subscription that calls a private Cloud Run service, and a dead-letter topic. + +- A push subscription authenticates with `push_config.oidc_token`; its service account needs `roles/run.invoker` on the service it calls. +- Dead-lettering needs two grants to the Pub/Sub service agent: `roles/pubsub.publisher` on the dead-letter topic and `roles/pubsub.subscriber` on the source subscription. Without them messages are never moved. +- Give the dead-letter topic a subscription of its own, or the messages moved there are lost. +- `max_delivery_attempts` is 5 to 100. `ack_deadline_seconds` is 10 to 600. +- `message_retention_duration` is a duration in seconds, such as `"604800s"`. +- Customer-managed encryption is `kms_key_name` on the topic; the Pub/Sub service agent needs `roles/cloudkms.cryptoKeyEncrypterDecrypter` on the key first. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +variable "worker_url" { + type = string + description = "HTTPS URL of the service the subscription pushes to." +} + +data "google_project" "this" { + project_id = var.project_id +} + +locals { + pubsub_agent = "serviceAccount:service-${data.google_project.this.number}@gcp-sa-pubsub.iam.gserviceaccount.com" +} + +resource "google_service_account" "push" { + project = var.project_id + account_id = "events-push" + display_name = "Identity Pub/Sub pushes with" +} + +resource "google_pubsub_topic" "events" { + project = var.project_id + name = "events" + message_retention_duration = "604800s" + + message_storage_policy { + allowed_persistence_regions = [var.region] + } +} + +resource "google_pubsub_topic" "dead_letter" { + project = var.project_id + name = "events-dead-letter" +} + +resource "google_pubsub_subscription" "dead_letter" { + project = var.project_id + name = "events-dead-letter" + topic = google_pubsub_topic.dead_letter.id + message_retention_duration = "1209600s" + + expiration_policy { + ttl = "" + } +} + +resource "google_pubsub_subscription" "worker" { + project = var.project_id + name = "events-worker" + topic = google_pubsub_topic.events.id + ack_deadline_seconds = 60 + + push_config { + push_endpoint = var.worker_url + + oidc_token { + service_account_email = google_service_account.push.email + audience = var.worker_url + } + } + + retry_policy { + minimum_backoff = "10s" + maximum_backoff = "600s" + } + + dead_letter_policy { + dead_letter_topic = google_pubsub_topic.dead_letter.id + max_delivery_attempts = 5 + } + + expiration_policy { + ttl = "" + } +} + +resource "google_pubsub_topic_iam_member" "agent_publishes_dead_letters" { + project = var.project_id + topic = google_pubsub_topic.dead_letter.name + role = "roles/pubsub.publisher" + member = local.pubsub_agent +} + +resource "google_pubsub_subscription_iam_member" "agent_forwards_from_worker" { + project = var.project_id + subscription = google_pubsub_subscription.worker.name + role = "roles/pubsub.subscriber" + member = local.pubsub_agent +} +``` diff --git a/skills/google-cloud-iac-patterns/references/secret-manager.md b/skills/google-cloud-iac-patterns/references/secret-manager.md new file mode 100644 index 0000000..da3aa8b --- /dev/null +++ b/skills/google-cloud-iac-patterns/references/secret-manager.md @@ -0,0 +1,45 @@ +# Secret Manager + +Terraform creates the secret and who may read it. The value is added outside Terraform, so it never enters the state or the repository. + +- `replication` is required: `auto {}` for Google-managed locations, or `user_managed` with one `replicas` block per location. +- Grant `roles/secretmanager.secretAccessor` on the secret, to the one identity that reads it. +- Never write a `google_secret_manager_secret_version` with the value in the configuration. + +```hcl +variable "project_id" { + type = string + description = "Project to deploy into." +} + +variable "region" { + type = string + description = "Region for regional resources." +} + +resource "google_service_account" "reader" { + project = var.project_id + account_id = "api-key-reader" + display_name = "Reads the API key" +} + +resource "google_secret_manager_secret" "api_key" { + project = var.project_id + secret_id = "partner-api-key" + + replication { + user_managed { + replicas { + location = var.region + } + } + } +} + +resource "google_secret_manager_secret_iam_member" "reader_reads_api_key" { + project = var.project_id + secret_id = google_secret_manager_secret.api_key.secret_id + role = "roles/secretmanager.secretAccessor" + member = google_service_account.reader.member +} +``` diff --git a/skills/google-cloud-lessons/SKILL.md b/skills/google-cloud-lessons/SKILL.md new file mode 100644 index 0000000..4ba5415 --- /dev/null +++ b/skills/google-cloud-lessons/SKILL.md @@ -0,0 +1,24 @@ +--- +name: google-cloud-lessons +description: >- + Rules learned from earlier solution-architecture work on Google Cloud, one set + per Deliverable. Each was proposed from problems that recurred across + Executions, approved by a person, and kept only while evaluation shows it + helps. Use before drafting a Deliverable, to read the lessons for that + Deliverable and follow them. +metadata: + scope: every Deliverable +--- + +# Lessons + +Each reference below holds the lessons for one Deliverable. Read the one for the Deliverable you are producing, with `load_skill_resource`, before you draft, and follow every rule in it that applies. A rule here takes precedence over a general habit; your role's instructions and the contract `submit_deliverable` checks take precedence over a rule here. + + +| Deliverable | Reference | Lessons | +| --- | --- | --- | +| deployment guidance | `references/deployment_guidance.md` | 1 | +| target architecture | `references/target_architecture.md` | 8 | + + +This Skill is written by the lessons loop (`app/learning/`), from proposals a person approved. Do not edit it by hand: change the proposal and publish again. diff --git a/skills/google-cloud-lessons/references/deployment_guidance.md b/skills/google-cloud-lessons/references/deployment_guidance.md new file mode 100644 index 0000000..486827a --- /dev/null +++ b/skills/google-cloud-lessons/references/deployment_guidance.md @@ -0,0 +1,11 @@ +# Lessons: deployment guidance + +Rules learned from earlier work. Follow every one that applies. + +## L-05: Include Required Arguments in Alert Policies + +**Rule.** Always verify and include all required arguments (such as time window definitions) when configuring nested blocks in monitoring alert policies. + +**Why.** Missing required arguments in nested blocks will cause Terraform validation to fail, preventing submission. + +Published 2026-10-10, from lesson proposal 05. diff --git a/skills/google-cloud-lessons/references/target_architecture.md b/skills/google-cloud-lessons/references/target_architecture.md new file mode 100644 index 0000000..00044b6 --- /dev/null +++ b/skills/google-cloud-lessons/references/target_architecture.md @@ -0,0 +1,67 @@ +# Lessons: target architecture + +Rules learned from earlier work. Follow every one that applies. + +## L-01: Create Specific Checks for All Constraints + +**Rule.** Create specific Checks for every explicit constraint, metric, or capability mentioned in a requirement, rather than relying on a single broad Check. + +**Why.** If detailed constraints are missed, the validation phase will reject the design for incomplete coverage, forcing a revision. + +Published 2026-10-10, from lesson proposal 01. + +## L-02: Assign Checks to Every Element + +**Rule.** Give every Element at least one Check before you submit. + +**Why.** The submission tool will reject the architecture if any Element lacks a Check, wasting an attempt. + +Published 2026-10-10, from lesson proposal 02. + +## L-03: Verify Resource Arguments for Checks + +**Rule.** Verify that the specific resource type used for an Element actually supports the configuration argument you specify in a Check. Remember that access policies and certain configurations often require entirely separate resources. + +**Why.** If a Check specifies an argument that does not exist on the resource, it cannot be implemented, forcing an architectural revision. + +Published 2026-10-10, from lesson proposal 03. + +## L-06: Do Not Mark Requirements as Not Applicable + +**Rule.** Do not list Requirements in the not applicable field, as this field is strictly for Design Recommendations. Ensure every Requirement has at least one Check. + +**Why.** The submission tool will reject the deliverable if a Requirement lacks a Check or is incorrectly marked as not applicable. + +Published 2026-10-10, from lesson proposal 06. + +## L-07: Verify location constraints + +**Rule.** When a requirement specifies where resources must be provisioned, such as a designated region or multi-zone placement, create a Check for the `region` or `location` argument on every applicable Element, naming the region the design uses. Do not write a Check about a property of the region that code cannot show, such as its carbon rating. + +**Why.** Validation frequently catches missing location constraints. Without this Check, resources may be provisioned in default regions, violating location requirements. A Check about a region's carbon rating cannot be verified from code and sends the design back. + +Published 2026-10-10, from lesson proposal 07. + +## L-08: Cloud SQL backup encryption + +**Rule.** When writing a Check for CMEK encryption on a `google_sql_database_instance`, do not require an `encryption_key_name` argument for backup storage, as the instance-level `encryption_key_name` automatically encrypts backups as well. + +**Why.** The database instance resource does not have a separate encryption key argument for backups. Asking for one causes validation to reject the Check as un-implementable. + +Published 2026-10-10, from lesson proposal 08. + +## L-09: Backend Service capabilities + +**Rule.** When writing Checks for a `google_compute_backend_service`, do not verify IAM roles inside the backend service or require health checks when it is configured with a Serverless NEG. + +**Why.** Roles are verified via IAM bindings outside the backend service, and Serverless NEGs do not support health checks. Invalid Checks cause the design to be rejected during validation. + +Published 2026-10-10, from lesson proposal 09. + +## L-10: Pub/Sub persistence regions + +**Rule.** When a requirement dictates that a messaging queue or topic must replicate across zones or stay within a specific region, create a Check for the `message_storage_policy.allowed_persistence_regions` argument on the topic Element. + +**Why.** Without this Check, topics might use default storage policies that violate geographical or high-availability requirements. + +Published 2026-10-10, from lesson proposal 10. diff --git a/skills/google-cloud-lessons/upstream.json b/skills/google-cloud-lessons/upstream.json new file mode 100644 index 0000000..dc6112f --- /dev/null +++ b/skills/google-cloud-lessons/upstream.json @@ -0,0 +1,9 @@ +{ + "google-cloud-solution-architecture": "f5b8cdac4060", + "google-cloud-waf-cost-optimization": "b3febbf52e5c", + "google-cloud-waf-operational-excellence": "bdc6a9f415f6", + "google-cloud-waf-performance-optimization": "89a4947438cf", + "google-cloud-waf-reliability": "9baf33bd5b75", + "google-cloud-waf-security": "e791a44cda99", + "google-cloud-waf-sustainability": "7d0a6921cb59" +} diff --git a/skills/iac-validation/SKILL.md b/skills/iac-validation/SKILL.md new file mode 100644 index 0000000..fcc968c --- /dev/null +++ b/skills/iac-validation/SKILL.md @@ -0,0 +1,52 @@ +--- +name: iac-validation +description: >- + Checks Terraform infrastructure-as-code without provisioning anything, using + the local terraform_fmt, terraform_validate, terraform_plan and + terraform_schema tools. Use when writing deployment guidance or validating it + before deployment. +metadata: + scope: deployment-guidance validation +--- + +# IaC validation + +Every check runs on a scratch copy of your Terraform files. Nothing is applied, and no state is written. + +The files are your working copy: the files you wrote with `write_file`, or, when you are validating, the files that were submitted. Pass the tools no files. + +## Tools + +- `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_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, resource_types)`: what a resource type accepts, from the provider's own schema. With `resource_types`, a list, it outlines every argument and block of each in one call; use that when you need several. 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. + +- `terraform_module(source, version, find)`, only when the Execution opted into published modules: what a published module accepts, from the registry: its inputs with their types, its outputs and its submodules. It says when a module cannot be used with the pinned provider. `find` narrows the inputs to those matching the words given. Only modules from the namespaces the Cloud provider allows can be looked up or used. + +## When writing deployment guidance + +1. Run `terraform_fmt`, then `terraform_validate`. +2. Fix each error with `edit_file`, changing only the lines concerned, and run `terraform_validate` again until it passes. +3. A refusal about a module means one of two things. The Execution writes plain resources, so write them directly. Or the module is not from an approved namespace or not pinned to one exact version, so use an approved module at an exact version or write the resources directly. +4. On "An argument named X is not expected here" or "Unsupported block type", call `terraform_schema` with `find` set to the name. It is either in a different block, which the reply names, or it does not exist on that resource type. Never move it around by trial. + +## When validating deployment guidance + +1. Run `terraform_validate`, and report its verdict and output. +2. When permission to read the live environment is granted, run `terraform_plan` with the variable values from the requirements, or clearly marked placeholders. Summarise the resources to add, change and destroy, and flag any destroy or replace. +3. When a check can't run (a missing CLI, a refused permission or a provider download failure), give the user the exact commands to run themselves: + + ```bash + terraform init -backend=false + terraform validate + terraform plan -lock=false -var-file= + ``` + +## Reporting verdicts + +Give a verdict on every Check in the Target architecture. Record them with `verdict_put`, a few Checks per call; they are attached as `verdicts.json`, in the format the requirements-chain Skill gives, when you submit. The dry-run's result goes in its `dry_run` entry: `pass` when `terraform_validate` passes, `fail` with the error when it does not, and `not_run` when the tool could not run. + +A Check fails when the code could meet it and does not. When `terraform_schema` shows the resource type has no such setting, no code could meet it: the verdict is `not_verifiable`, with the schema's answer as evidence. + +Never suggest `terraform apply` as part of validation. diff --git a/skills/overlays/example-organisation-standards/SKILL.md b/skills/overlays/example-organisation-standards/SKILL.md new file mode 100644 index 0000000..31ebf1d --- /dev/null +++ b/skills/overlays/example-organisation-standards/SKILL.md @@ -0,0 +1,51 @@ +--- +name: example-organisation-standards +description: >- + An example of an organisation's cloud standards as an overlay Skill: naming, + mandatory labels, approved regions and a short list of things never to do. + Use on any Deliverable of an Execution that names this overlay, to apply the + organisation's standards on top of the Cloud provider's guidance. +metadata: + scope: every Deliverable + overlay: organisation standards (example) +--- + +# Organisation standards (example) + +This is an example. Copy it, replace every rule with your organisation's own, and name the copy when you start an Execution. Nothing here is a real organisation's policy. + +An overlay adds to the Cloud provider's guidance. Where the two disagree, this Skill wins; where a requirement the user stated disagrees with this Skill, say so in your Deliverable and follow the user's requirement. + +## Naming + +- Every resource is named `--`, lower case, with hyphens: `orders-prod-ingest`. +- `` is one of `dev`, `test`, `prod`, and comes from a variable. + +## Labels + +Every resource that accepts labels carries all four: + +| Label | Value | +| --- | --- | +| `workload` | the workload's short name | +| `environment` | `dev`, `test` or `prod` | +| `owner` | the owning team's short name | +| `cost-centre` | the cost centre code, from a variable | + +## Regions + +- Deploy only to `europe-west1` or `europe-west4`. +- Data at rest stays in the European Union. + +## Never + +- No public IP address on a database. +- No service account key files; workloads use attached identities. +- No resource without deletion protection in `prod`, where the resource type has it. + +## What each Specialist does with this + +- **Requirements:** record each standard above that applies as a non-functional requirement, with this Skill as its source, so it is traced like any other. +- **Design recommendations and Target architecture:** a standard that applies becomes a Check on every Element it constrains. +- **Infrastructure code:** follow the naming and label rules exactly. +- **Validation:** the standards are verified through the Checks that came from them. diff --git a/skills/requirements-chain/SKILL.md b/skills/requirements-chain/SKILL.md new file mode 100644 index 0000000..40625f7 --- /dev/null +++ b/skills/requirements-chain/SKILL.md @@ -0,0 +1,157 @@ +--- +name: requirements-chain +description: >- + Defines the data files that carry requirements through to code and validation: + requirements, components, products, recommendations, the Target architecture + graph, the implementation map and the verdicts. Use when producing or checking + any Deliverable of a solution-architecture Execution, to write its data file + in the right format and keep every id traceable. +metadata: + scope: every Deliverable +--- + +# Requirements chain + +Every requirement must be traceable, by id, to the components that serve it, to the Elements and Checks that realise it, to the code that implements them, and to a validation verdict. Each Deliverable attaches one data file that carries its part of that chain. A submission is refused when a link is missing, and the refusal names it. + +Ids are short and stable: reuse an id exactly as the earlier Deliverable wrote it, and never renumber. + +## The files + +### `requirements.json` (requirements) + +A list. Number functional requirements `FR-1`, `FR-2` and non-functional ones `NFR-1`, `NFR-2`. + +```json +[ + {"id": "FR-1", "kind": "functional", "text": "Accept signed webhooks over HTTPS."}, + {"id": "NFR-1", "kind": "non_functional", "text": "Raw events are encrypted at rest and retained for 30 days.", + "conditions": ["Raw events are encrypted at rest.", "Raw events are kept for 30 days and then deleted."]}, + {"id": "NFR-2", "kind": "non_functional", "text": "The service is available 99.9% of each month, across two zones.", + "conditions": ["The service runs in at least two zones."], + "outside_code": ["Measured availability is at least 99.9% a month."]} +] +``` + +Every non-functional requirement lists its `conditions`: one entry for each separate thing that must be true for it to be met and that infrastructure configuration can show. What it asks for that configuration cannot show goes under `outside_code`: an outcome measured in operation, behaviour of the application's own code, a process people follow, or a property of a region or product that only its provider publishes, such as a region's carbon rating or a product's service level. For those, the condition is the choice that configuration can show: "every resource is in the one agreed region" is a condition, and "that region has a high carbon-free energy score" is `outside_code`. A requirement has at least one entry between the two; one that is entirely outside code has `"conditions": []`. Write each so it can be checked on its own, and so that together they say everything the text says. The Target architecture needs a Check for each one. + +`kind` is `functional` or `non_functional`. Write one requirement per entry, so each can be checked on its own. + +When the customer's scope is in your context, a requirement says what it comes from in `from`: the ids of the customer's own requirements, and the scope fields it carries. + +```json +{"id": "NFR-4", "kind": "non_functional", + "text": "The network is a hub with spokes, joined to on-premises over a private 10Gbps connection.", + "conditions": ["A hub network is connected to every spoke network.", "A dedicated 10Gbps connection joins the hub to on-premises."], + "from": ["REQ-03", "networking.topology", "networking.hybrid_connectivity.type", "networking.hybrid_connectivity.bandwidth_gbps"]} +``` + +- Every requirement the customer wrote (`scope.stated.intent.requirements`) is named in the `from` of the requirement that covers it. +- Every field under `scope.binding` is a choice the customer stated that the design must honour. Each is named in the `from` of a non-functional requirement with at least one condition that shows it was honoured. Write the condition about what must exist or be set, in terms a Check can verify: "a hub network is connected to every spoke network", not "the topology is hub and spoke". +- One requirement may carry several fields that belong together. A submission is refused while any is carried by none. + +### `components.json` (technical decomposition) + +A list of components and the requirement ids each serves. Every functional requirement must be served by at least one component. + +```json +[{"id": "C-1", "name": "Ingest endpoint", "requirements": ["FR-1"]}] +``` + +### `products.json` (product selection) + +One entry per component, naming the product selected for it. + +```json +[{"component": "C-1", "product": "Cloud Run"}] +``` + +### `recommendations.json` (design recommendations) + +A list. Each recommendation names its pillar and the components it applies to; use an empty list for one that applies to the whole workload. + +```json +[{"id": "DR-1", "pillar": "security", "text": "Encrypt the topic with a customer-managed key.", "components": ["C-2"], + "conditions": ["The topic is encrypted with a customer-managed key.", "The messaging service's own identity may use that key."]}] +``` + +Every recommendation lists its `conditions`, and `outside_code` where it applies, as a non-functional requirement does. When it applies to several components, give a condition for each. + +Write one configurable decision per recommendation. "Harden the service" cannot become a Check; "disable public ingress on the worker service" can. + +### `target-architecture.json` (Target architecture) + +```json +{ + "elements": [ + {"id": "E-1", "name": "Ingest service", "component": "C-1", "product": "Cloud Run", "resource_type": "google_cloud_run_v2_service"}, + {"id": "E-2", "name": "Ingest identity", "product": "IAM", "resource_type": "google_service_account"} + ], + "relationships": [ + {"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"} + ], + "checks": [ + {"id": "K-1", "applies_to": "E-1", "statement": "ingress is INGRESS_TRAFFIC_ALL and roles/run.invoker is granted to allUsers", "source": "FR-1"}, + {"id": "K-2", "applies_to": "E-2", "statement": "the account is attached to E-1 only", "source": "DR-3"} + ], + "not_applicable": [ + {"recommendation": "DR-9", "reason": "Single region by requirement NFR-2."} + ] +} +``` + +- **Elements.** One per resource to be created. `component` is the component it realises; leave it out for a supporting Element such as an identity, a key or a network. `product` for a component's Element is exactly the product selected for that component. +- **Relationships.** `from` and `to` are Element ids. `kind` says what the connection is: calls, publishes to, reads from, runs as, is granted access to. +- **Checks.** `applies_to` is an Element or Relationship id. `source` is the requirement or recommendation id the Check comes from. Every Element has at least one Check. +- **Coverage.** Every entry in the `conditions` of a non-functional requirement or a recommendation needs a Check that verifies it, with that requirement or recommendation as its `source`. An entry under `outside_code` gets no Check, and a requirement or recommendation with nothing but `outside_code` needs none. A condition that applies to several Elements needs a Check on each: "processing scales to zero when idle" applies to every processing Element, not one of them. +- **Completeness.** Every component has an Element. Every non-functional requirement and every recommendation is the `source` of at least one Check, unless the recommendation is listed under `not_applicable` with a reason. Every selected product appears on its component's Element. + +#### Writing a Check + +A Check is a statement that is true or false of the infrastructure code. Name the argument and the value. + +- Verifiable: "`kms_key_name` is set on the topic", "`min_instance_count` is at least 2", "the subscription has a `dead_letter_policy` pointing at E-6". +- Not verifiable: "the service is secure", "follows least privilege", "scales well". + +Split a broad recommendation into several Checks, one per setting. A Check that the validator cannot verify from the code is sent back to you. + +A Check must name a setting its Element's resource type really has. Two similar resource types often differ: a setting of a long-running service may not exist on a batch job. A Check on a setting the resource type lacks is sent back to you. + +The tables of Elements, Relationships and Checks, and the diagram, are written from this file when you submit. Write the graph once, here. + +### `implementation.json` (deployment guidance) + +One entry per Check in the Target architecture, saying where the code satisfies it. `file` is an attached file; `address` is the resource address and argument. + +```json +[ + {"check": "K-1", "file": "terraform/main.tf", "address": "google_cloud_run_v2_service.ingest.ingress"}, + {"check": "K-7", "unimplementable": "google_cloud_run_v2_job has no startup_cpu_boost argument; it exists only on a service."} +] +``` + +When a module creates the resource, `address` is the module and the input that sets what the Check asks for, such as `module.database.ip_configuration.ipv4_enabled`. + +When a Check names a setting its resource type does not have, give it an `unimplementable` entry in place of `file` and `address`, saying what the resource type lacks. Write no code for it. The Target architecture is revised before anything is validated. + +Implement every Element, Relationship and Check, and nothing the Target architecture does not ask for. When you believe the Target architecture is wrong or incomplete, say so with `needs_input`; do not quietly build something else. + +### `verdicts.json` (validation results) + +```json +{ + "dry_run": {"verdict": "pass", "evidence": "terraform validate: Success! The configuration is valid."}, + "checks": [ + {"check": "K-1", "verdict": "pass", "evidence": "main.tf: ingress = \"INGRESS_TRAFFIC_ALL\"; google_cloud_run_v2_service_iam_member.public"}, + {"check": "K-2", "verdict": "fail", "evidence": "google_service_account.ingest is also attached to the worker service"} + ], + "proposed_additions": [ + {"statement": "the bucket has a retention_policy of 30 days", "applies_to": "E-5", "reason": "NFR-1 has no Check on retention"} + ] +} +``` + +- Give every Check exactly one verdict: `pass`, `fail` or `not_verifiable`, with the evidence you read in the code. +- `dry_run.verdict` is `pass`, `fail`, or `not_run` when the tool could not run. +- Find every gap in one pass: go through each requirement and recommendation in turn and compare its `conditions` with the Checks that name it as `source`. Propose nothing for its `outside_code`. +- Judge the code against the Checks and nothing else. Something the Target architecture lacks is a `proposed_additions` entry, with the requirement or recommendation id it serves in `reason`. It is never a failed Check. diff --git a/skills/scoping/SKILL.md b/skills/scoping/SKILL.md new file mode 100644 index 0000000..f3b5b78 --- /dev/null +++ b/skills/scoping/SKILL.md @@ -0,0 +1,37 @@ +--- +name: scoping +description: >- + The scope spec: the structured statement of what a customer wants and the + facts a solution architecture depends on, with the catalogue of its fields. + Use when reading a scope spec in your context, to know what a field means, + whether the customer stated it or left it to you, and what binds your + Deliverable. +metadata: + scope: every Deliverable +--- + +# Scoping + +A scope spec is a YAML file the customer's architect supplies, complete or partly filled. It sits beside the Intent, which stays in the customer's words. `assets/catalogue.yaml` lists every field it may hold: its type, when it must be settled, the question to ask for it, and guidance for a default. + +## What a field says + +| In the spec | Meaning | +| --- | --- | +| a value | The customer states this. It is theirs: use it as given. | +| `ask`, or left out | Not known yet. | +| `decide` | The customer leaves the choice to you. Choose, and record it as an assumption with what it affects. | +| `not_applicable` | It does not apply. Ask nothing and assume nothing. | + +## Rules for every Specialist + +- **A stated value binds you.** A region, a topology, a product, a setting or a number the spec states is the customer's decision. Honour it. If you believe it is wrong, say so with `needs_input`; do not quietly replace it. +- **A stated choice is not yours to generalise.** The rule that requirements name no products is about what you introduce. What the customer wrote stays as they wrote it. +- **Build nothing the customer excluded.** `intent.exclusions` is out of scope for every Deliverable. +- **The customer's own requirements carry their ids.** Each entry in `intent.requirements` must be met. When your work serves one, name its id. +- **An assumption is not the customer's decision.** A field under `assumed` was chosen for them, with the reason given. Work from it, and say so where your Deliverable depends on it: it may change when they answer. +- **Do not fill a gap silently.** A field under `to_ask` is still unknown. When your Deliverable needs it, assume a default and say that you did. + +## The kinds of engagement + +`engagement.kind` is `workload` (an application), `platform_foundation` (a landing zone or shared platform that workloads will later run on) or `migration`. A platform foundation has no users or response times of its own: its subject is the organisation's structure, shared networking, identity, environments and guardrails. diff --git a/skills/scoping/assets/catalogue.yaml b/skills/scoping/assets/catalogue.yaml new file mode 100644 index 0000000..c90d0ac --- /dev/null +++ b/skills/scoping/assets/catalogue.yaml @@ -0,0 +1,345 @@ +# The scope spec's catalogue: every field a scope spec may hold. +# +# A field is a dotted path. `type` is one of: string, text, integer, number, boolean, +# date, list, enum, records. `tier` says when it must be settled: essential (always, +# before any work), important (asked when someone is present) or optional. A tier +# may differ by the kind of engagement. `question` is what to ask the customer for +# it. `default` guides the choice when the customer says "decide". `affects` says +# what a wrong assumption would change. `binds: true` marks a choice a design must +# honour: stated by the customer, it has to reach a requirement and its Checks. +# +# This catalogue names no Cloud provider. A provider's bundle adds allowed values +# for the fields marked `provider_values`. +schema_version: 1 +kinds: [workload, platform_foundation, migration] + +fields: + metadata.customer_case: + type: string + tier: essential + aliases: [metadata.engagement_id] + question: What short reference identifies this engagement? + metadata.engagement_reference: + type: string + metadata.client_name: + type: string + metadata.author: + type: string + metadata.revision: + type: string + + engagement.kind: + type: enum + values: [workload, platform_foundation, migration] + tier: essential + question: >- + Is this an application workload, a platform foundation such as a landing zone, + or a migration of existing systems? + + intent.statement: + type: text + tier: essential + question: In the customer's own words, what do they want? + intent.requirements: + type: records + keys: [id, statement] + optional_keys: [category] + question: Which requirements has the customer stated outright? + intent.exclusions: + type: list + tier: important + question: What has the customer said is out of scope? + default: Nothing is excluded beyond what the statement implies. + affects: what is designed and planned + intent.success_criteria: + type: list + question: How will the customer judge this a success? + default: The stated requirements are met. + + estate.cloud_provider: + type: enum + provider_values: true + tier: essential + question: Which Cloud provider is this for? + estate.mode: + type: enum + values: [greenfield, brownfield_expansion, migration] + tier: essential + question: Is this a new estate, an extension of an existing one, or a migration? + estate.regions.primary: + binds: true + type: string + tier: essential + question: Which region should it run in? + estate.regions.secondary: + binds: true + type: string + question: Is there a second region, and which? + default: None, unless availability or recovery targets need one. + affects: resilience design and cost + estate.regions.resiliency_tier: + binds: true + type: enum + values: [single_region, warm_standby, active_active] + tier: important + question: How should it survive the loss of a region? + default: single_region + affects: resilience design and cost + estate.data_residency: + binds: true + type: string + tier: essential + question: Where must data stay? + estate.existing_systems: + type: text + tier: {migration: essential, platform_foundation: important, workload: important} + question: What exists today that this replaces, extends or must connect to? + default: Nothing exists today. + affects: connectivity, migration work and the plan + + workload.users.who: + type: enum + values: [employees, customers, partners, public, systems] + tier: {workload: essential, migration: essential} + question: Who uses it? + workload.users.count: + type: integer + tier: {workload: essential, migration: essential} + question: How many users? + workload.users.peak_concurrent: + type: integer + tier: {workload: important, migration: important} + question: How many use it at once at peak? + default: A tenth of the user count. + affects: scaling limits and cost + workload.availability.target: + binds: true + type: string + tier: {workload: essential, migration: essential, platform_foundation: important} + question: What availability is required, as a percentage? + default: "99.9%" + affects: resilience design and cost + workload.availability.hours: + type: enum + values: [business_hours, extended, always] + tier: important + question: During which hours must it be available? + default: always + affects: scaling to zero and support + workload.availability.recovery_time: + binds: true + type: string + tier: important + question: How quickly must it recover from a failure? + default: 4 hours + affects: backup and standby design + workload.availability.recovery_point: + binds: true + type: string + tier: important + question: How much recent data may be lost in a failure? + default: 1 hour + affects: backup frequency + + compliance.industry: + type: string + question: "Which industry is the customer in?" + compliance.frameworks: + binds: true + type: list + tier: essential + question: Which regulations or standards apply? An empty list if none. + compliance.data_classification: + binds: true + type: enum + values: [public, internal, confidential, restricted] + tier: essential + question: How sensitive is the data? + compliance.encryption.type: + binds: true + type: enum + values: [provider_managed, customer_managed] + provider_values: true + tier: important + question: Must the customer control the encryption keys? + default: provider_managed + affects: key management design + compliance.encryption.key_rotation_days: + binds: true + type: integer + question: How often must keys rotate, in days? + default: 90 + compliance.audit_logging.retention_days: + binds: true + type: integer + tier: important + question: How long must audit logs be kept, in days? + default: 365 + affects: storage cost and log design + compliance.audit_logging.immutable_retention_policy: + binds: true + type: boolean + question: Must audit logs be undeletable for that time? + default: false + + networking.exposure: + binds: true + type: enum + values: [internal_only, internet_facing] + tier: important + question: Is it reached from the internet or only from inside? + default: internal_only + affects: perimeter design + networking.topology: + binds: true + type: enum + provider_values: true + tier: {platform_foundation: important} + question: Is a network topology already decided? + default: The simplest topology that meets the requirements. + affects: the whole network design + networking.hybrid_connectivity.enabled: + binds: true + type: boolean + tier: {platform_foundation: important, migration: important} + question: Must it connect privately to on-premises or another cloud? + default: false + affects: network design and lead time + networking.hybrid_connectivity.type: + binds: true + type: enum + provider_values: true + question: By what kind of connection? + networking.hybrid_connectivity.bandwidth_gbps: + binds: true + type: number + question: At what bandwidth, in Gbps? + networking.egress_control.model: + binds: true + type: enum + values: [direct, provider_managed, centralized_appliance] + question: How must traffic to the internet be controlled? + default: provider_managed + affects: network design and cost + networking.egress_control.appliance_vendor: + binds: true + type: string + question: Which inspection appliance, if one is mandated? + networking.cidr_allocations: + binds: true + type: text + tier: {platform_foundation: important} + question: Which IP ranges are allocated, and how large per environment? + default: Private ranges that do not overlap, sized for growth. + affects: every network resource + + governance.identity_source_of_truth: + binds: true + type: string + tier: important + question: Which identity provider do people sign in with? + default: The Cloud provider's own identities. + affects: access design + governance.pipeline_authentication: + binds: true + type: string + question: How do delivery pipelines authenticate? + default: Short-lived federated credentials, no stored keys. + governance.environment_tiers: + binds: true + type: records + keys: [name] + optional_keys: [archetype] + tier: important + question: Which environments are needed? + default: development, test and production. + affects: the number of environments built and planned + + operations.operating_model: + type: string + question: "Who runs the platform day to day?" + operations.support_hours: + type: enum + values: [business_hours, extended, always] + question: During which hours is it supported? + default: business_hours + operations.monitoring: + type: text + question: What monitoring and alerting is expected? + default: The Cloud provider's own monitoring, with alerts on availability and errors. + operations.change_process: + type: text + question: "How are changes approved and released?" + + integrations: + type: records + keys: [name] + optional_keys: [direction, criticality] + question: Which other systems must it exchange data with? + default: None. + + delivery.target_start_date: + type: date + question: "When should work start?" + delivery.window_weeks: + type: integer + tier: important + question: Is there a deadline, in weeks from the start? + default: No deadline; the plan gives the time the work needs. + affects: the plan and whether the scope fits + delivery.commercial_model: + type: enum + values: [time_and_materials, fixed_price_milestone, managed_service] + question: How is the work contracted? + delivery.iac_tooling: + type: string + question: "Which infrastructure-as-code tool?" + default: terraform + delivery.ci_cd: + type: string + question: "Which delivery pipeline tool?" + delivery.team_size: + type: integer + tier: important + question: How many engineers will build it? + default: 2 + affects: the timeline + delivery.working_days_per_week: + type: integer + default: 5 + + cost.monthly_budget: + type: number + tier: {workload: essential, migration: essential, platform_foundation: important} + question: What is the monthly running budget? + default: No ceiling; cost is optimised within the requirements. + affects: product tiers and resilience choices + cost.currency: + type: string + default: "USD" + + constraints.products_required: + binds: true + type: list + question: Which products has the customer mandated? + default: None. + constraints.products_forbidden: + binds: true + type: list + question: Which products are ruled out? + default: None. + constraints.other: + type: list + + run.pre_approved: + type: boolean + default: false + run.allow_cloud_read: + type: boolean + default: false + run.overlay_skills: + type: list + default: [] + run.terraform_modules: + type: boolean + default: false diff --git a/skills/vendor/google/LICENSE b/skills/vendor/google/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/skills/vendor/google/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/skills/vendor/google/SHA256SUMS b/skills/vendor/google/SHA256SUMS new file mode 100644 index 0000000..0ffc972 --- /dev/null +++ b/skills/vendor/google/SHA256SUMS @@ -0,0 +1,12 @@ +cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30 LICENSE +758242af40565fed981ccf3011824b728ddeb46c96b98f1363826686fe3e0482 google-cloud-solution-architecture/SKILL.md +1e860e851c27001a1354a2c384bdd0c01a7102ed8d878861bd4952e3265a6eff google-cloud-solution-architecture/assets/output-template.md +d1b69d4daf1f43eeff587247fb604123b79ab825b412719df2d19904919dc1f6 google-cloud-solution-architecture/references/architecture-guides.md +ef71c1f0d6929f0cd53c40bcd1afe090febfca28f32c6379670c26e042aa0121 google-cloud-solution-architecture/references/best-practices-guides.md +9dbd6f0046a84f9f3e58d12315a420a840eaa15f3824808f654200d3e8af971e google-cloud-solution-architecture/references/decision-making-guides.md +3ff42b6532c35829a3a6ab9465a6258e334f1d20b244c2e07228ccf95b55d27a google-cloud-waf-cost-optimization/SKILL.md +519aaf57bfacf495f594c46c50726361422c4483bf84adce6e647137e95657d7 google-cloud-waf-operational-excellence/SKILL.md +03e6b3e523712cad48dc62e09804250c241fc34e88c18aa81a7d5b2aada7759a google-cloud-waf-performance-optimization/SKILL.md +a8ebafc1aa138a5d13544e352abe9454bb48859fcc41520d57547a0796cbdc8b google-cloud-waf-reliability/SKILL.md +e5dc59635a2e6a3d720495f81ea89beeb3c05e76acb6479928a675dfa8466ded google-cloud-waf-security/SKILL.md +f270005fb37adb04b3579d1f2c262506a77831e9e8977a050f2eeb755e08d1e9 google-cloud-waf-sustainability/SKILL.md diff --git a/skills/vendor/google/VENDOR.md b/skills/vendor/google/VENDOR.md new file mode 100644 index 0000000..f412df9 --- /dev/null +++ b/skills/vendor/google/VENDOR.md @@ -0,0 +1,20 @@ +# Vendored Agent Skills: google/skills + +Unmodified copies of upstream Agent Skills. Do not edit these files; re-run +`scripts/sync-vendored-skills.sh ` and review the diff instead (ADR-0002). + +- Source: https://github.com/google/skills +- Commit: `81a31a6e4300425598a69fd96c8e843c947ae308` +- Synced: 2026-09-15 +- Licence: Apache License 2.0, see `LICENSE` +- Integrity: `SHA256SUMS` lists every vendored file; `tests/test_vendored_skills.py` verifies it. + +## Skills + +- `google-cloud-solution-architecture` (upstream `skills/cloud/google-cloud-solution-architecture`) +- `google-cloud-waf-security` (upstream `skills/cloud/google-cloud-waf-security`) +- `google-cloud-waf-reliability` (upstream `skills/cloud/google-cloud-waf-reliability`) +- `google-cloud-waf-cost-optimization` (upstream `skills/cloud/google-cloud-waf-cost-optimization`) +- `google-cloud-waf-operational-excellence` (upstream `skills/cloud/google-cloud-waf-operational-excellence`) +- `google-cloud-waf-performance-optimization` (upstream `skills/cloud/google-cloud-waf-performance-optimization`) +- `google-cloud-waf-sustainability` (upstream `skills/cloud/google-cloud-waf-sustainability`) diff --git a/skills/vendor/google/google-cloud-solution-architecture/SKILL.md b/skills/vendor/google/google-cloud-solution-architecture/SKILL.md new file mode 100644 index 0000000..d7f8408 --- /dev/null +++ b/skills/vendor/google/google-cloud-solution-architecture/SKILL.md @@ -0,0 +1,273 @@ +--- +name: google-cloud-solution-architecture +metadata: + category: MultiProductSolutions +description: >- + Interactively discovers requirements and designs holistic, multi-product + system architectures, solution blueprints, and deployment recommendations for + complex workloads on Google Cloud. Use when designing end-to-end cloud + solutions, selecting and integrating Google Cloud services, generating + architecture diagrams, or conducting requirements discovery for new cloud + workloads or migrations. Don't use for single-product tasks (use + product-specific skills), initial onboarding or authentication (use + google-cloud-recipe-*), Well-Architected Framework reviews or audits (use + google-cloud-waf-*), or workloads covered by specialized solution skills. +--- + +# Google Cloud solution-architecture workflow + +## Overview of the workflow + +The workflow consists of the following phases: + +* **Phase 1: Requirements discovery**. Gather detailed requirements related to + the cloud workload or use case that the user needs assistance for. +* **Phase 2: Solution architecture**. Use the requirements that were gathered + in Phase 1 to generate a detailed solution architecture for the cloud + workload or use case. +* **Phase 3: Solution validation**. Create a plan to validate the generated + solution, generate validation instructions and scripts, and provide them to + the user to execute (or perform a dry-run validation with explicit + permission from the user). +* **Phase 4: Solution packing and presentation**. Consolidate the generated + content and present the solution. + +**Important notes about the workflow**: + +* **Strict phase separation**: During Phase 1 (Requirements discovery), when + you ask the user clarifying questions, don't recommend, propose, or outline + any architectural designs, technical decompositions, cloud services, or + component mappings. Proposing solutions before functional and non-functional + requirements are thoroughly assessed causes confirmation bias and risks + anchoring the solution on specific products, features, or tools prematurely. + +* **Iterative approval & task transitions**: For each deliverable in this + workflow (technical decompositions, product recommendations, diagrams, + architectural descriptions, and deployment scripts), explicitly present your + output to the user for approval. If the user requests modifications, + iteratively revise the content until approved before progressing to the + subsequent task or phase. + +* **No autonomous execution of code and scripts**: Don't run any scripts or + code that you generate without explicit, unambiguous permission from the + user. Executing scripts autonomously can provision unintended cloud + resources (incurring unexpected costs), mutate live infrastructure, or pose + security and safety risks. Always offer the option for the user to execute + the commands manually. + +* **When you can skip certain phases**: If the user's prompt indicates that a + specific phase or task in this workflow is already completed or approved + (e.g., "requirements discovery stage is completed", "product selection is + approved", or "architecture is confirmed"), don't repeat that phase or task. + Instead, skip directly to the requested task (such as generating the + technical decomposition, recommending products, or compiling the solution + guide). + +## Phase 1: Requirements discovery + +1. Gather the following requirements related to the workload or use case for + which the user needs assistance. + + **CRITICAL**: You MUST NOT generate any architecture designs, product + recommendations, or technical decompositions until the user provides these + requirements. + + * **Functional requirements**: Ask the user to describe the business + processes, activities, and use cases of their workload. + * **Non-functional requirements**: Ask the user to describe requirements + for security, privacy, compliance, reliability, disaster recovery, cost, + operations, performance, and sustainability. + * **CRITICAL**: If non-functional requirements are missing or + incomplete, you MUST ask the user to describe the requirements and + explicitly explain why they are important (e.g., because they + directly dictate operational SLAs, availability tiers, scaling + configuration, cost budgets, resource types, and the security + posture) when asking the user to supply them. + * **Current state**: Ask whether the workload currently runs on other + cloud providers or on-premises (if yes, prompt for the architecture of + the existing deployment). + * **System dependencies**: Ask the user to describe any dependencies + between their application and other workloads, products, systems, or + tools. + +2. Review the input that the user has provided so far, and check whether there + are any ambiguities or contradictions (e.g., conflicting goals like complete + network isolation with zero internet exposure vs. real-time ingestion from + public APIs). + + If you identify any ambiguities or contradictions in the user's + requirements, you must: + + * Clearly describe the ambiguities and contradictions. + * Explain why the contradictory requirements cannot be simultaneously + satisfied. + * Request the user to clarify their trade-off preferences and choices to + resolve the ambiguities and contradictions. + * If the user delegates the choice to you (e.g., the user replies with + "do what you think is best" or "you decide"), then provide a clear + suggestion to resolve the ambiguity or contradiction, explain your + reasoning, and ask the user to approve your suggestion. + + **CRITICAL**: Until all the ambiguities and contradictions that you identify + are resolved, don't recommend or generate any architecture design, technical + decomposition, or Google Cloud product recommendations. Ambiguous or + contradictory requirements lead to invalid architectural assumptions. + +3. Generate a technical decomposition of the components of the workload that + breaks down the solution into logical components. Present it to the user and + obtain approval before proceeding to Phase 2. + + **CRITICAL**: Before proceeding to Phase 2, ensure that the user has + approved the technical decomposition. Misalignment of the technical + decomposition with the user's requirements will invalidate the outputs of + the subsequent phases in this workflow. + +## Phase 2: Solution architecture + +Use the approved requirements from Phase 1 to generate a comprehensive solution +architecture. + +### Ground all generated content + +For each task in this phase, to ensure that the generated content aligns with +the latest and official Google Cloud guidance, you must ground the generated +content by using the following resources: + +* Google Developer Knowledge MCP server + * Server: https://developerknowledge.googleapis.com/mcp + * Tools: + * `developerknowledge:search_documents` + * `developerknowledge:get_documents` + * `developerknowledge:answer_query` +* Relevant skills from https://github.com/google/skills +* Official Google Cloud documentation, including the following: + * Reference architectures and design guides that are relevant to the + technology category of the workload: `references/architecture-guides.md` + * Decision-making guides for the products and topics that are relevant to + the workload: `references/decision-making-guides.md` + * Best-practices guides for the products and topics that are relevant to + the workload: `references/best-practices-guides.md` + +For each item in the generated guidance, you must include citations to the +relevant official Google Cloud documentation pages. + +### Task 2.1: Identify Google Cloud products and features required for the workload. + +1. Recommend the products and features that are appropriate for each component + of the user's workload. + + **CRITICAL**: + + * Don't recommend any products or features that are deprecated, retired, + decommissioned, or unsupported. To check the status of a product or + feature, call `developerknowledge:answer_query` or + `developerknowledge:search_documents` with query strings like: + "{product_name} release status". + * If multiple products or features can be used for a component of the + workload, then do the following: + * Recommend the most appropriate product or feature. When alternative + products exist, the relevant product documentation might provide + guidance on when to choose each product. Follow that guidance. + * Mention the available alternative products or features. + * Explain the pros and cons of each alternative product or feature. + +2. Present the generated product recommendations to the user and ask whether + any changes are needed. + + **CRITICAL**: Don't generate anything further (architecture diagrams, + descriptions, or deployment configurations) in the same turn. Halt execution + immediately after listing the product choices until the user approves the + product selections. + +3. After the user approves the product selections, proceed to Task 2.2. + +### Task 2.2: Generate an architecture diagram. + +1. Generate an architecture diagram in Mermaid format: + https://github.com/mermaid-js/mermaid. +2. Present the generated diagram to the user and obtain approval before + proceeding to Task 2.3. + +### Task 2.3: Generate an architecture description. + +1. Generate a description that explains the purpose of each component, the + relationships between the components, and the task flow or data flow. +2. Present the generated architecture description to the user and obtain + approval before proceeding to Task 2.4. + +### Task 2.4: Generate design recommendations. + +1. Generate design recommendations and best practices to optimally configure + each component in the architecture based on the workload's requirements. + **Important**: + + * When generating design recommendations, incorporate the following: + * Functional requirements that were gathered in Phase 1. + * Non-functional requirements that were gathered in Phase 1. + * To generate guidance for non-functional requirements, use the following + skills, as appropriate: + - `google-cloud-waf-security` + - `google-cloud-waf-reliability` + - `google-cloud-waf-cost-optimization` + - `google-cloud-waf-operational-excellence` + - `google-cloud-waf-performance-optimization` + - `google-cloud-waf-sustainability` + + If any of the specialized `google-cloud-waf-*` skills are not available in + your current workspace, derive design guidance directly from the + documentation references in `references/best-practices-guides.md`. + +2. Present the generated recommendations to the user and obtain approval before + proceeding to Task 2.5. + +### Task 2.5: Generate deployment guidance. + +1. Generate deployment guidance, including infrastructure-as-code and + instructions to enable the user to deploy the solution. +2. Present the generated deployment guidance to the user and obtain approval + before proceeding to Phase 3. + +## Phase 3: Solution validation + +### Task 3.1: Pre-deployment validation + +1. Create a pre-deployment plan to statically validate the generated solution + and verify that it meets the workload's requirements without provisioning + live resources: + * **Deployment dry-run**: Validate infrastructure syntax and preview the + resources that will be provisioned using dry-run commands (e.g., + `terraform plan` or (where supported) `gcloud ... --dry-run`). + * **Architecture & policy analysis**: Perform static verification of + network routing topologies, firewall rules, and IAM enforcement against + best practices. +2. Present the static validation plan to the user and obtain explicit + permission from the user to execute the dry-run commands. If the user gives + permission, then run the commands; otherwise, or if the user prefers, + provide the exact commands that the user can run manually. +3. Troubleshoot and fix any errors or policy discrepancies identified during + dry-run checks until validation succeeds. +4. Proceed to Task 3.2 + +### Task 3.2: Runtime validation (Post-deployment) + +1. Ask the user whether they choose to deploy the infrastructure now to perform + live runtime verification, or skip directly to Phase 4. +2. **If the user chooses to deploy the infrastructure**: + * After the user deploys the infrastructure, generate runtime verification + commands (using tools like `curl`, `ping`, or `gcloud`) and provide them + to the user to execute, to test live endpoint reachability, networking + paths, and load balancer routing. + * Troubleshoot any deployment or runtime routing issues until checks pass. +3. Proceed to Phase 4. + +## Phase 4: Solution packaging and presentation + +Package all the generated text and code artifacts for final presentation. + +1. Consolidate the text artifacts that were generated in Phase 2 and Phase 3 + into a single Markdown file named `solution-architecture-guide.md`, based on + the template in `assets/output-template.md`. +2. Request the user's permission to write the code files in the user's + workspace. +3. After the user gives permission, write the code files in the user's + workspace. diff --git a/skills/vendor/google/google-cloud-solution-architecture/assets/output-template.md b/skills/vendor/google/google-cloud-solution-architecture/assets/output-template.md new file mode 100644 index 0000000..686c34e --- /dev/null +++ b/skills/vendor/google/google-cloud-solution-architecture/assets/output-template.md @@ -0,0 +1,124 @@ + + +# Google Cloud solution architecture: [Workload Name] + +## 1. Executive summary and workload overview +[A brief description of the workload, its business goals, and the high-level +solution architecture proposed.] + +## 2. Requirements and current state + +### 2.1. Functional requirements +* **Business processes**: [Details of the business processes supported] +* **Activities and use cases**: [Details of the key activities and use cases] + +### 2.2. Non-functional requirements +* **Security**: [Details of the security requirements including compliance, + encryption, access control requirements] +* **Reliability**: [Details of the reliability requirements including SLA, + RTO/RPO, backup, redundancy requirements] +* **Cost**: [Details of the cost constraints and pricing models] +* **Operations**: [Details of the operational requirements including + monitoring, logging, deployment, maintenance requirements] +* **Performance**: [Details of the performance requirements including latency, + throughput, scaling requirements] +* **Sustainability**: [Details of the sustainability requirements including + carbon footprint, resource optimization requirements] + +### 2.3. Current state +[If applicable, describe the current on-premises or other-cloud architecture.] +* **Current infrastructure**: [Details of existing setup] +* **Pain points and drivers for migration/redesign**: [Details of the drivers + for migration/redesign] + +### 2.4. Dependencies +* **Internal dependencies**: [Details of internal dependencies including other + workloads and internal services] +* **External dependencies**: [Details of external dependencies including + third-party products and on-premises tools] + +## 3. Technical decomposition of the workload +[Technical decomposition of the workload components, breaking down the +application into logical services or layers.] + +## 4. Proposed solution architecture + +### 4.1. Google Cloud products and features mapping +[Identify Google Cloud products and features mapped to the technical +components. For each component, justify the selection, note alternatives +considered, and describe the pros and cons of the recommended product/feature +and alternatives.] + +| Component | Recommended Google Cloud product/feature | Justification and citations | Alternatives considered | Pros and cons of alternatives | +| :--- | :--- | :--- | :--- | :--- | +| **[Component Name]** | **[Product Name]** | [Why this product is chosen, citing official docs] | [Alternative product] | **Pros**: ...
**Cons**: ... | + +### 4.2. Architecture diagram +[Architecture diagram in Mermaid format showing the relationships and flows +between the components of the architecture.] + +```mermaid +%% Example structure +graph TD + User([User]) --> Web[Load Balancer] + Web --> App[Application Layer] + App --> DB[(Database)] +``` + +### 4.3. Architecture description +[Detailed description of the architecture. Describe the task flow and data +flow between the components of the architecture.] +* **Data flow**: [Describe the flow of data.] +* **Tasks/control flow**: [Describe the flow of tasks/control.] + +## 5. Design and configuration recommendations +[Best practices and configuration recommendations for each pillar of the +Google Cloud Architecture Framework.] + +### 5.1. Security, privacy, and compliance +* **Access control**: [E.g., IAM roles, least privilege policy] +* **Data protection**: [E.g., Encryption at rest/in transit, Cloud KMS] +* **Network Security**: [E.g., VPC, Firewalls, Cloud Armor, Private Service Connect] + +### 5.2. Reliability +* **Redundant deployment**: [E.g., Multi-region/regional deployment, load +balancing] +* **Backup and DR**: [E.g., Backups, failover procedures, RTO/RPO strategies] + +### 5.3. Operational excellence +* **Monitoring and logging**: [E.g., Cloud Logging, Cloud Monitoring, Dashboards] +* **Infrastructure as Code (IaC)**: [E.g., Terraform, Deployment Manager] + +### 5.4. Cost optimization +* **Sizing and scaling**: [E.g., Autoscaling configuration, right-sizing resources] +* **Pricing models**: [E.g., Commitment discounts, Spot VMs, flat-rate pricing] + +### 5.5. Performance efficiency +* **Caching and CDN**: [E.g., Cloud CDN, Memorystore] +* **Database and query optimization**: [E.g., Partitioning, indexing, caching] + +### 5.6. Sustainability +* [E.g., Serverless adoption, resource utilization, carbon footprint] + +## 6. Deployment guidance +[Instructions and code for deploying the architecture.] + +### 6.1. Deployment prerequisites +* [Prerequisite 1: E.g., Enabling APIs] +* [Prerequisite 2: E.g., Installing SDK/tools] +* ...and so on + +### 6.2. Step-by-step deployment instructions +1. [Step 1: E.g., Authenticate with Google Cloud] +2. [Step 2: E.g., Initialize Terraform] +3. [Step 3: E.g., Apply Terraform configuration] + +## 7. Validation plan +[Details of the steps to verify that the generated solution meets the workload's + requirements. Also include references to any validation scripts that were + generated.] + +## 8. References +* [E.g., Horizontal scalability](https://docs.cloud.google.com/architecture/framework/reliability/horizontal-scalability) +* [E.g., Regional managed instance groups](https://docs.cloud.google.com/compute/docs/instance-groups/regional-migs) \ No newline at end of file diff --git a/skills/vendor/google/google-cloud-solution-architecture/references/architecture-guides.md b/skills/vendor/google/google-cloud-solution-architecture/references/architecture-guides.md new file mode 100644 index 0000000..ab09f00 --- /dev/null +++ b/skills/vendor/google/google-cloud-solution-architecture/references/architecture-guides.md @@ -0,0 +1,362 @@ +# Architecture guides + +| Technology category | Brief description | Line hints | +|---------------------|-------------------|------------| +| [Fundamentals](#fundamentals) | Design guides, reference architectures, and best practices for foundational cloud architectures, landing zones, and deployment archetypes. | Lines 19-46 | +| [AI and ML](#ai-ml) | Design guides, reference architectures, and best practices for AI, MLOps, generative AI, and agentic workflows. | Lines 47-98 | +| [Application development](#application-development) | Design guides, reference architectures, and best practices for building, deploying, and running applications in the cloud. | Lines 99-132 | +| [Security, privacy, and compliance](#security-privacy-and-compliance) | Design guides, reference architectures, and best practices for security, privacy, and compliance. | Lines 133-207 | +| [Reliability and disaster recovery](#reliability-and-disaster-recovery) | Design guides, reference architectures, and best practices for reliability and disaster recovery. | Lines 208-230 | +| [Data and analytics](#data-and-analytics) | Design guides, reference architectures, and best practices for data warehousing, data mesh, data analytics, and data streaming. | Lines 231-248 | +| [Databases](#databases) | Design guides, reference architectures, and best practices for planning and implementing databases for cloud workloads. | Lines 249-268 | +| [Migration](#migration) | Methodologies, assessment frameworks, and guides for migrating VMs, databases, and applications to Google Cloud. | Lines 269-295 | +| [Networking](#networking) | Design guides, reference architectures, and best practices for planning and implementing networking for cloud workloads. | Lines 296-315 | +| [Hybrid, multi-cloud, and distributed cloud](#hybrid-multi-cloud-and-distributed-cloud) | Design guides, reference architectures, and best practices for hybrid, multi-cloud, and distributed cloud environments. | Lines 316-337 | +| [Financial services](#financial-services) | Design guides, reference architectures, and best practices for financial services workloads. | Lines 338-341 | +| [Monitoring and logging](#monitoring-and-logging) | Best practices and operational patterns for observability, log streaming, and infrastructure monitoring. | Lines 342-354 | +| [Storage](#storage) | Design guides, reference architectures, and best practices to help you plan and implement storage for cloud workloads. | Lines 355-361 | + +## Fundamentals + +- [Authentication and authorization](https://docs.cloud.google.com/architecture/blueprints/security-foundations/authentication-authorization.md.txt): Introduces how to use Cloud Identity to manage identities for accessing Google Cloud services. +- [Comparative analysis of Google Cloud deployment archetypes](https://docs.cloud.google.com/architecture/deployment-archetypes/comparison.md.txt): Compares the cloud deployment archetypes in terms of the availability they provide, resilience to zone and region outages, cost, and operational complexity. +- [Decide a resource hierarchy for your Google Cloud landing zone](https://docs.cloud.google.com/architecture/landing-zones/decide-resource-hierarchy.md.txt): Provides guidance to help you decide the resource hierarchy for your Google Cloud landing zone. +- [Decide how to onboard identities to Google Cloud](https://docs.cloud.google.com/architecture/landing-zones/decide-how-to-onboard-identities.md.txt): Describes identity provisioning options for Google Cloud and the decisions that you must make when you onboard your users to Cloud Identity or Google Workspace. +- [Decide the network design for your Google Cloud landing zone](https://docs.cloud.google.com/architecture/landing-zones/decide-network-design.md.txt): Describes common network designs for landing zones, and helps you choose the option that best meets your requirements. +- [Decide the security for your Google Cloud landing zone](https://docs.cloud.google.com/architecture/landing-zones/decide-security.md.txt): Provides guidance to help you decide the security design for your Google Cloud landing zone. +- [Deploy the blueprint](https://docs.cloud.google.com/architecture/blueprints/security-foundations/summary.md.txt): Describes the process to deploy an enterprise foundation using a blueprint. +- [Deployment methodology](https://docs.cloud.google.com/architecture/blueprints/security-foundations/deployment-methodology.md.txt): Provides guidance to use declarative infrastructure to deploy an enterprise foundations blueprint. +- [Detective controls](https://docs.cloud.google.com/architecture/blueprints/security-foundations/detective-controls.md.txt): Describes the threat detection and monitoring controls that are incorporated into an enterprise foundations blueprint. +- [Enterprise foundations blueprint](https://docs.cloud.google.com/architecture/blueprints/security-foundations.md.txt): Describes a blueprint to deploy foundational resources, configurations, and capabilities to help ensure consistent governance, security, scaling, and observability for your workloads in Google Cloud. +- [Google Cloud deployment archetypes](https://docs.cloud.google.com/architecture/deployment-archetypes.md.txt): Describes the deployment archetypes that you can use for cloud applications, the use cases for each deployment archetype and the design considerations. +- [Google Cloud global deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/global.md.txt): Describes the global deployment archetype, and its use cases and design considerations. +- [Google Cloud hybrid deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/hybrid.md.txt): Describes the hybrid deployment archetype, and its use cases and design considerations. +- [Google Cloud multi-regional deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/multiregional.md.txt): Describes the multi-regional deployment archetype, and its use cases and design considerations. +- [Google Cloud multicloud deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/multicloud.md.txt): Describes the multicloud deployment archetype, and its use cases and design considerations. +- [Google Cloud regional deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/regional.md.txt): Describes the regional deployment archetype, and its use cases and design considerations. +- [Google Cloud zonal deployment archetype](https://docs.cloud.google.com/architecture/deployment-archetypes/zonal.md.txt): Describes the zonal deployment archetype, and its use cases and design considerations. +- [Implement your Google Cloud landing zone network design](https://docs.cloud.google.com/architecture/landing-zones/implement-network-design.md.txt): Provides steps and guidance to implement your chosen network design for your landing zone. +- [Landing zone design in Google Cloud](https://docs.cloud.google.com/architecture/landing-zones.md.txt): This series shows how to design and build a landing zone in Google Cloud, guiding you through high-level decisions about identity onboarding, resource hierarchy, network design, and security. +- [Operations best practices](https://docs.cloud.google.com/architecture/blueprints/security-foundations/operation-best-practices.md.txt): Provides best practices for deploying and operating workloads in a Google Cloud environment that's based on an enterprise foundations blueprint. +- [Organization structure](https://docs.cloud.google.com/architecture/blueprints/security-foundations/organization-structure.md.txt): Describes how the resources in an enterprise foundations blueprint are organized. +- [Preventative controls for acceptable resource configurations](https://docs.cloud.google.com/architecture/blueprints/security-foundations/preventative-controls.md.txt): Describes preventative controls that you can incorporate into an enterprise foundations blueprint. +- [Well-Architected Framework: Cost optimization pillar](https://docs.cloud.google.com/architecture/framework/cost-optimization/printable.md.txt): Provides principles and recommendations to help you optimize the cost of your workloads in Google Cloud. +- [Well-Architected Framework: Performance optimization pillar](https://docs.cloud.google.com/architecture/framework/performance-optimization/printable.md.txt): Provides principles and recommendations to help you optimize the performance of your workloads in Google Cloud. +- [Well-Architected Framework: Sustainability pillar](https://docs.cloud.google.com/architecture/framework/sustainability/printable.md.txt): Provides principles and recommendations to help you design, build, and manage workloads in Google Cloud that are energy-efficient and carbon-aware. + +## AI and ML + +- [Agentic AI use case: Administer interactive learning](https://docs.cloud.google.com/architecture/agentic-ai-interactive-learning.md.txt): Design a single-agent AI system that assesses a user's knowledge on a specific topic and generates a personalized learning experience. +- [Agentic AI use case: Automate data science workflows](https://docs.cloud.google.com/architecture/agentic-ai-data-science.md.txt): Design a multi-agent AI system that automates complex data analytics and machine learning tasks. +- [Agentic AI use case: Build a multicloud open data lakehouse](https://docs.cloud.google.com/architecture/agentic-ai-build-multicloud-open-data-lakehouse.md.txt): A high-level architecture to build a multicloud open data lakehouse that establishes a highly governed, secure pipeline from raw multicloud silos to AI and agentic driven actions. +- [Agentic AI use case: Classify multimodal data](https://docs.cloud.google.com/architecture/agentic-ai-classify-multimodal-data.md.txt): A high-level architecture to design a multi-agent AI system that analyzes disparate multimodal data and produces a high-confidence classification. +- [Agentic AI use case: Enable live bidirectional multimodal streaming](https://docs.cloud.google.com/architecture/agentic-ai-bidirectional-multimodal-streaming.md.txt): A high-level architecture to build and deploy a multi-agent AI system that provides technical guidance and automated safety monitoring through a continuous, bidirectional stream of multimodal data. +- [Agentic AI use case: Multimodal GraphRAG resource orchestration](https://docs.cloud.google.com/architecture/agentic-ai-multimodal-graph-rag-resource-orchestration.md.txt): A high-level architecture to build and deploy a multi-agent AI system that consolidates fragmented multimodal data into a searchable knowledge graph. +- [Agentic AI use case: Orchestrate access to disparate enterprise systems](https://docs.cloud.google.com/architecture/agenticai-orchestrate-access-disparate-systems.md.txt): Use agentic AI to orchestrate access to disparate enterprise systems. +- [Agentic AI use case: Orchestrate security operations workflows](https://docs.cloud.google.com/architecture/agentic-ai-orchestrate-security-ops-workflows.md.txt): A high-level architecture to build a multi-agent AI system that orchestrates complex investigation and triage processes in a security operations center (SOC). +- [Architecture for MLOps using TensorFlow Extended, Agent Platform Pipelines, and Cloud Build](https://docs.cloud.google.com/architecture/architecture-for-mlops-using-tfx-kubeflow-pipelines-and-cloud-build.md.txt): Describes the architecture of a machine learning (ML) system using TensorFlow Extended (TFX) libraries. +- [Automate utilization-review of health insurance claims using generative AI](https://docs.cloud.google.com/architecture/use-generative-ai-utilization-management.md.txt): A reference architecture for health insurance companies to automate prior authorization (PA) request processing and improve their utilization review (UR) processes. +- [Best practices for implementing machine learning on Google Cloud](https://docs.cloud.google.com/architecture/ml-on-gcp-best-practices.md.txt): Introduces best practices for implementing machine learning (ML) on Google Cloud, with a focus on custom-trained models based on your data and code. +- [Build an ML vision analytics solution with Dataflow and Cloud Vision API](https://docs.cloud.google.com/architecture/building-a-vision-analytics-solution.md.txt): How to deploy a Dataflow pipeline to process large-scale image files with Cloud Vision. Dataflow stores the results in BigQuery so that you can use them to train BigQuery ML pre-built models. +- [Build and deploy generative AI and machine learning models in an enterprise](https://docs.cloud.google.com/architecture/blueprints/genai-mlops-blueprint.md.txt): Describes the generative AI and machine learning (ML) blueprint, which deploys a pipeline for creating AI models. +- [Build trusted AI agents with Google Maps Platform](https://docs.cloud.google.com/architecture/agentic-ai-system-with-grounding-using-maps.md.txt): A high-level architecture to build trusted and effective AI agents by grounding them in real-world contextual data from Google Maps Platform and Google Calendar. +- [C3 AI architecture on Google Cloud](https://docs.cloud.google.com/architecture/partners/c3-ai-architecture.md.txt): Develop applications using C3 AI and Google Cloud. +- [Choose a design pattern for your agentic AI system](https://docs.cloud.google.com/architecture/choose-design-pattern-agentic-ai-system.md.txt): Learn how to select an agent design pattern to build your agentic system. +- [Choose your agentic AI architecture components](https://docs.cloud.google.com/architecture/choose-agentic-ai-architecture-components.md.txt): Learn how to select architecture components to build your agentic AI system. +- [Confidential computing for data analytics, AI, and federated learning](https://docs.cloud.google.com/architecture/security/confidential-computing-analytics-ai.md.txt): "Learn about how you can use confidential computing in Google Cloud to encrypt data in use for confidential data analytics, AI machine learning, and federated learning." +- [Cross-silo and cross-device federated learning on Google Cloud](https://docs.cloud.google.com/architecture/cross-silo-cross-device-federated-learning-google-cloud.md.txt): Provides guidance to help you create a federated learning platform that supports either a cross-silo or cross-device architecture. +- [Delete the Generative AI document summarization](https://docs.cloud.google.com/architecture/ai-ml/generative-ai-document-summarization.md.txt): Delete the Generative AI document summarization Jump Start Solution. +- [Delete the Generative AI Knowledge Base](https://docs.cloud.google.com/architecture/ai-ml/generative-ai-knowledge-base.md.txt): Delete the Generative AI Knowledge Base Jump Start Solution. +- [Delete the Generative AI RAG with Cloud SQL](https://docs.cloud.google.com/architecture/ai-ml/generative-ai-rag.md.txt): Delete the Generative AI RAG with Cloud SQL Jump Start Solution. +- [Deploy an ML vision analytics solution with Dataflow and Cloud Vision API](https://docs.cloud.google.com/architecture/building-a-vision-analytics-solution/deployment.md.txt): Describes how to deploy a Dataflow pipeline that processes image files at scale with Cloud Vision API and then stores the processed output in BigQuery for analytics and model training. +- [Deploy and operate generative AI applications](https://docs.cloud.google.com/architecture/deploy-operate-generative-ai-applications.md.txt): Discusses techniques for building and operating generative AI applications using MLOps and DevOps principles. +- [Generative AI use case: Generate content for personalized marketing campaigns](https://docs.cloud.google.com/architecture/genai-marketing-campaigns.md.txt): Use AI to generate personalized content for targeted marketing campaigns. +- [Generative AI use case: Generate personalized product recommendations](https://docs.cloud.google.com/architecture/genai-product-recommendations.md.txt): Use AI to generate personalized product recommendations for a retail application. +- [Generative AI use case: Generate podcasts from audio files](https://docs.cloud.google.com/architecture/genai-podcasts-from-commentary.md.txt): Use AI to generate podcasts based on audio input. +- [Generative AI use case: Generate solutions for customer-support questions](https://docs.cloud.google.com/architecture/genai-customer-support.md.txt): Use AI to generate responses to support questions from customers. +- [Generative AI with RAG](https://docs.cloud.google.com/architecture/rag-reference-architectures.md.txt): Provides a list of reference architectures to deploy generative AI applications with retrieval-augmented generation (RAG) in Google Cloud. +- [GraphRAG infrastructure for generative AI using Agent Platform and Spanner Graph](https://docs.cloud.google.com/architecture/gen-ai-graphrag-spanner.md.txt): Design infrastructure for a generative AI application with GraphRAG using Spanner Graph. +- [Guidelines for developing high-quality, predictive ML solutions](https://docs.cloud.google.com/architecture/guidelines-for-developing-high-quality-ml-solutions.md.txt): Collates some guidelines to help you assess, ensure, and control quality in machine learning (ML) solutions. +- [Harness CI/CD pipeline for RAG applications](https://docs.cloud.google.com/architecture/partners/harness-cicd-pipeline-for-rag-app.md.txt): Shows you how to implement a Harness CI/CD pipeline for a RAG-capable application in Google Cloud. +- [Implement agentic analytics workflows for distributed data](https://docs.cloud.google.com/architecture/agentic-ai-cross-cloud-analytics.md.txt): A high-level architecture for implementing cross-cloud analytics workflows that use AI agents. +- [Implement two-tower retrieval for large-scale candidate generation](https://docs.cloud.google.com/architecture/implement-two-tower-retrieval-large-scale-candidate-generation.md.txt): Learn how to implement an end-to-end two-tower candidate generation workflow with Vertex AI. +- [MLOps: Continuous delivery and automation pipelines in machine learning](https://docs.cloud.google.com/architecture/mlops-continuous-delivery-and-automation-pipelines-in-machine-learning.md.txt): Discusses techniques for implementing and automating continuous integration (CI), continuous delivery (CD), and continuous training (CT) for machine learning (ML) systems. +- [Model development and data labeling with Google Cloud and Labelbox](https://docs.cloud.google.com/architecture/partners/model-development-data-labeling-labelbox-google-cloud.md.txt): Provides guidance for building a standardized pipeline to help accelerate the development of ML models. +- [Multi-agent AI system in Google Cloud](https://docs.cloud.google.com/architecture/multiagent-ai-system.md.txt): Design robust multi-agent AI systems in Google Cloud. +- [Multi-tenant agentic AI system](https://docs.cloud.google.com/architecture/multi-tenant-agentic-ai-system.md.txt): Design a multi-tenant agentic AI system on Google Cloud. +- [Networking for AI inference model serving on all backends](https://docs.cloud.google.com/architecture/networking-for-ai-inference.md.txt): Guidance to help you create a unified frontend for multiple AI models that are hosted on-premises or by any provider, including third-party and Google Cloud. +- [Networking for AI inference model serving on GKE](https://docs.cloud.google.com/architecture/networking-for-ai-inference-gke.md.txt): Guidance to help you create a multiple-model inference service using GKE. +- [Optimize AI and ML workloads with Cloud Storage FUSE](https://docs.cloud.google.com/architecture/optimize-ai-ml-workloads-cloud-storage-fuse.md.txt): Use Cloud Storage FUSE to optimize the performance of AI and ML workloads. +- [Optimize AI and ML workloads with Google Cloud Managed Lustre](https://docs.cloud.google.com/architecture/optimize-ai-ml-workloads-managed-lustre.md.txt): Shows how to use Managed Lustre to optimize the performance of AI and ML workloads. +- [Private connectivity for RAG-capable generative AI applications](https://docs.cloud.google.com/architecture/private-connectivity-rag-capable-gen-ai.md.txt): Implement network infrastructure to help improve security for your RAG-capable applications. +- [RAG infrastructure for generative AI using Agent Platform and AlloyDB for PostgreSQL](https://docs.cloud.google.com/architecture/rag-capable-gen-ai-app-using-vertex-ai.md.txt): Design infrastructure to run a generative AI application with retrieval-augmented generation using AlloyDB as the vector store. +- [RAG infrastructure for generative AI using Agent Platform and Vector Search](https://docs.cloud.google.com/architecture/gen-ai-rag-vertex-ai-vector-search.md.txt): Design infrastructure for a generative AI application with retrieval-augmented generation (RAG) using the vector search capabilities of Gemini Enterprise Agent Platform. +- [RAG infrastructure for generative AI using Gemini Enterprise and Agent Platform](https://docs.cloud.google.com/architecture/rag-genai-gemini-enterprise-vertexai.md.txt): Design infrastructure for a generative AI application with retrieval-augmented generation (RAG) using Gemini Enterprise and Gemini Enterprise Agent Platform. +- [RAG infrastructure for generative AI using GKE and Cloud SQL](https://docs.cloud.google.com/architecture/rag-capable-gen-ai-app-using-gke.md.txt): Shows you how to design the infrastructure for a generative AI application with RAG using GKE. +- [Single-agent AI system using ADK and Cloud Run](https://docs.cloud.google.com/architecture/single-agent-ai-system-adk-cloud-run.md.txt): Shows you how to build a single-agent AI system by using ADK and Cloud Run with Gemini and MCP. +- [Well-Architected Framework: AI and ML perspective](https://docs.cloud.google.com/architecture/framework/perspectives/ai-ml/printable.md.txt): Provides principles and recommendations to help you design, build, and manage AI and ML workloads in Google Cloud that meet your operational, security, reliability, cost, and performance goals. + +## Application development + +- [Architecture decision records overview](https://docs.cloud.google.com/architecture/architecture-decision-records.md.txt): Explains when and how to use architecture decision records (ADRs) to document and explain design choices for applications on Google Cloud. +- [Best practices for automatically provisioning and configuring edge and bare metal systems and servers](https://docs.cloud.google.com/architecture/connected-devices/best-practices-provisioning-configuring-bare-metal.md.txt): Describes best practices for automatically provisioning and configuring edge devices and bare metal systems and servers. +- [Best practices for running cost-optimized Kubernetes applications on GKE](https://docs.cloud.google.com/architecture/best-practices-for-running-cost-effective-kubernetes-applications-on-gke.md.txt): Discusses best practices for running cost-optimized applications on Google Kubernetes Engine (GKE). +- [CI/CD pipeline for developing and delivering containerized apps](https://docs.cloud.google.com/architecture/app-development-and-delivery-with-cloud-code-gcb-cd-and-gke.md.txt): Describes how to set up and use a development, continuous integration (CI), and continuous delivery (CD) system using an integrated set of Google Cloud tools. +- [Configure Active Directory for VMs to automatically join a domain](https://docs.cloud.google.com/architecture/configuring-active-directory-for-vms-to-automatically-join-the-domain.md.txt): Shows you how to configure Active Directory and Compute Engine so that Windows virtual machine (VM) instances can automatically join an Active Directory domain. +- [Connected device architectures on Google Cloud](https://docs.cloud.google.com/architecture/connected-devices.md.txt): An overview on a series of approaches for connected device IoT architectures on Google Cloud. +- [Cymbal Bank application architecture](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/cymbal-bank.md.txt): Describes a sample containerized application that incorporates best practices from a blueprint for an enterprise developer platform. +- [Delete the Cloud SDK Client Library](https://docs.cloud.google.com/architecture/application-development/cloud-client-api.md.txt): Delete the Cloud SDK Client Library Jump Start Solution. +- [Delete the Dynamic web application with Python and JavaScript](https://docs.cloud.google.com/architecture/application-development/dynamic-app-python.md.txt): Delete the Dynamic web application with Python and JavaScript Jump Start Solution. +- [Delete the Ecommerce platform with serverless computing](https://docs.cloud.google.com/architecture/application-development/ecommerce-serverless.md.txt): Delete the Ecommerce platform with serverless computing Jump Start Solution. +- [Delete the Three-tier web app](https://docs.cloud.google.com/architecture/application-development/three-tier-web-app.md.txt): Delete the three-tier web app. +- [Deploy an Active Directory forest on Compute Engine](https://docs.cloud.google.com/architecture/deploy-an-active-directory-forest-on-compute-engine.md.txt): Shows you how to deploy an Active Directory forest on Compute Engine in a way that follows the best practices. +- [Deploy an enterprise developer platform on Google Cloud](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint.md.txt): Describes the enterprise application blueprint, which deploys an internal developer platform that provides managed software development and delivery. +- [Deploy the blueprint](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/deploy-blueprint.md.txt): Describes the steps to deploy a blueprint for an enterprise developer platform. +- [Deployment methodology](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/deployment-methodology.md.txt): Describes the automated systems and pipelines that are used to deploy a blueprint for an enterprise developer platform. +- [Develop and deploy containerized apps using a CI/CD pipeline](https://docs.cloud.google.com/architecture/app-development-and-delivery-with-cloud-code-gcb-cd-and-gke/deployment.md.txt): Describes how to design and deploy a system for continuous integration (CI) and continuous delivery (CD) by using an integrated set of Google Cloud services and tools. +- [DevOps capabilities](https://docs.cloud.google.com/architecture/devops.md.txt) +- [From edge to multi-cluster mesh: Deploy globally distributed applications through GKE Gateway and Cloud Service Mesh](https://docs.cloud.google.com/architecture/build-apps-using-gateway-and-cloud-service/deployment.md.txt): Shows how to deploy globally distributed applications that are exposed through Google Kubernetes Engine (GKE) Gateway and Cloud Service Mesh. +- [From edge to multi-cluster mesh: Globally distributed applications exposed through GKE Gateway and Cloud Service Mesh](https://docs.cloud.google.com/architecture/build-apps-using-gateway-and-cloud-service.md.txt): Describes exposing applications externally through Google Kubernetes Engine (GKE) Gateways running on multiple GKE clusters within a service mesh. +- [IoT platform product architecture on Google Cloud](https://docs.cloud.google.com/architecture/connected-devices/iot-platform-product-architecture.md.txt): Describes basic architectural considerations and recommendations for deploying an IoT platform product architecture on Google Cloud. +- [Manage costs and attributions for the developer platform](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/manage-costs-attributions.md.txt): Provide guidance to manage costs when using a blueprint for an enterprise developer platform. +- [Multi-regional deployment on Compute Engine](https://docs.cloud.google.com/architecture/multiregional-vms.md.txt): Provides a reference architecture for a multi-tier application that runs on Compute Engine VMs in multiple regions and describes the design factors to consider when you build a multi-regional architecture. +- [Reference architecture: Resource management with ServiceNow](https://docs.cloud.google.com/architecture/resource-management-with-servicenow.md.txt): Provides architectural recommendations to integrate Google Cloud assets into ServiceNow discovery tools. +- [Regional deployment on Compute Engine](https://docs.cloud.google.com/architecture/regional-deployment-compute-engine.md.txt): Learn how to architect a multi-tier application that runs on Compute Engine VMs in multiple zones within a Google Cloud region. +- [Select a managed container runtime environment](https://docs.cloud.google.com/architecture/select-managed-container-runtime-environment.md.txt): Learn about managed runtime environments and assess your requirements to choose between Cloud Run and GKE Autopilot. +- [Service architecture](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/service-architecture.md.txt): Describes the service architecture of a blueprint for an enterprise developer platform. +- [Set up Chrome Remote Desktop for Linux on Compute Engine](https://docs.cloud.google.com/architecture/chrome-desktop-remote-on-compute-engine.md.txt): Shows you how to set up the Chrome Remote Desktop service on a Debian Linux virtual machine (VM) instance on Compute Engine. Chrome Remote Desktop allows you to remotely access applications with a graphical user interface. +- [Set up Chrome Remote Desktop for Windows on Compute Engine](https://docs.cloud.google.com/architecture/chrome-desktop-remote-windows-compute-engine.md.txt): Shows you how to set up the Chrome Remote Desktop service on a Microsoft Windows virtual machine (VM) instance on Compute Engine. Chrome Remote Desktop allows you to remotely access applications with a graphical user interface. +- [Single-zone deployment on Compute Engine](https://docs.cloud.google.com/architecture/single-zone-deployment-compute-engine.md.txt): Provides a reference architecture for a multi-tier application that runs on Compute Engine VMs in a single-zone region and describes the design factors to consider when you build a single-zone architecture. +- [Standalone MQTT broker architecture on Google Cloud](https://docs.cloud.google.com/architecture/connected-devices/mqtt-broker-architecture.md.txt): Describes an architecture for deploying an MQTT broker (the core application in an MQTT deployment) on Google Cloud. +- [Website hosting](https://docs.cloud.google.com/architecture/web-serving-overview.md.txt): How to host a website on Google Cloud. Google Cloud provides a robust, flexible, reliable, and scalable platform for serving websites. + +## Security, privacy, and compliance + +- [Active Directory single sign-on](https://docs.cloud.google.com/architecture/identity/federating-gcp-with-active-directory-configuring-single-sign-on.md.txt): Shows how to set up single sign-on (SSO) between your Active Directory environment and your Cloud Identity or Google Workspace account by using Microsoft Active Directory Federation Services (AD FS) and SAML Federation. +- [Active Directory user account provisioning](https://docs.cloud.google.com/architecture/identity/federating-gcp-with-active-directory-synchronizing-user-accounts.md.txt): Shows how to set up user and group provisioning between Active Directory and your Cloud Identity or Google Workspace account by using Google Cloud Directory Sync (GCDS). +- [Architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/architecture-patterns.md.txt): Discusses patterns that are designed based on the required communication models between applications residing in Google Cloud and in other environments. +- [Assess existing user accounts](https://docs.cloud.google.com/architecture/identity/assessing-existing-user-accounts.md.txt): Describes how to assess different types of existing user accounts when you're planning to manage identities across an organization. +- [Assess onboarding plans](https://docs.cloud.google.com/architecture/identity/assessing-onboarding-plans.md.txt): Provides guidance to onboard existing identities and new identities to Cloud Identity or Google Workspace. +- [Assess the impact of user account consolidation on federation](https://docs.cloud.google.com/architecture/identity/assessing-consolidation-impact-on-federation.md.txt): Describes how to assess the impact of user account consolidation on identity federation. +- [Automate malware scanning for files uploaded to Cloud Storage](https://docs.cloud.google.com/architecture/automate-malware-scanning-for-documents-uploaded-to-cloud-storage.md.txt): This document shows you how to build an event-driven pipeline that can help you automate the evaluation of files for malicious code. +- [Best practices for continuous access to Google Cloud](https://docs.cloud.google.com/architecture/security/best-practices-continuous-access-to-google-cloud.md.txt): Describes best practices for emergency access and IdP failover to ensure continuous access to Google Cloud. +- [Best practices for federating Google Cloud with an external identity provider](https://docs.cloud.google.com/architecture/identity/best-practices-for-federating.md.txt): Describes best practices for federating Google Cloud with an external identity provider. +- [Best practices for mitigating compromised OAuth tokens for Google Cloud CLI](https://docs.cloud.google.com/architecture/bps-for-mitigating-gcloud-oauth-tokens.md.txt): Describes how to mitigate the impact of an attacker compromising the OAuth tokens that are used by the gcloud CLI. +- [Best practices for planning accounts and organizations](https://docs.cloud.google.com/architecture/identity/best-practices-for-planning.md.txt): Provides guidance to determine the number of Cloud Identity or Google Workspace accounts, Google Cloud organizations, and billing accounts you need based on your security and organizational requirements. +- [Best practices for protecting against cryptocurrency mining attacks](https://docs.cloud.google.com/architecture/security/bps-for-protecting-against-crytocurrency-attacks.md.txt): Describes best practices for protecting against cryptocurrency mining attacks. +- [Best practices for running an IoT backend on Google Cloud](https://docs.cloud.google.com/architecture/connected-devices/bps-running-iot-backend-securely.md.txt): Describes best practices for running an IoT backend on Google Cloud. +- [Best practices for securing apps and resources by using context-aware access](https://docs.cloud.google.com/architecture/secure-apps-resources-using-context-aware-access/best-practices.md.txt): Describes best practices for using context-aware access to secure apps and resources. +- [Best practices for securing your applications and APIs using Apigee](https://docs.cloud.google.com/architecture/best-practices-securing-applications-and-apis-using-apigee.md.txt): Describes best practices that can help you to secure your applications and APIs using Apigee API management, Google Cloud Armor, reCAPTCHA Enterprise, and Cloud CDN. +- [Configure networks for FedRAMP and DoD in Google Cloud](https://docs.cloud.google.com/architecture/configure-networks-fedramp-dod-google-cloud.md.txt): Provides configuration guidance to help you to comply with design requirements for FedRAMP High and DoD IL2, IL4, and IL5 when you deploy Google Cloud networking policies. +- [De-identification and re-identification of PII in large-scale datasets using Sensitive Data Protection](https://docs.cloud.google.com/architecture/de-identification-re-identification-pii-using-cloud-dlp.md.txt): Discusses how to use Sensitive Data Protection to create an automated data transformation pipeline to de-identify sensitive data like personally identifiable information (PII). +- [Deploy a secured serverless architecture using Cloud Run functions](https://docs.cloud.google.com/architecture/blueprints/serverless-functions-blueprint.md.txt): Provides guidance on how to help protect serverless applications that use Cloud Functions (2nd gen) by layering additional controls onto your existing foundation. +- [Deploy a secured serverless architecture using Cloud Run](https://docs.cloud.google.com/architecture/blueprints/serverless-blueprint.md.txt): Provides guidance on how to help protect serverless applications that use Cloud Run by layering additional controls onto your existing foundation. +- [Deploy automated malware scanning for files uploaded to Cloud Storage](https://docs.cloud.google.com/architecture/automate-malware-scanning-for-documents-uploaded-to-cloud-storage/deployment.md.txt): Describes how to deploy an architecture for automated malware scanning of data in Cloud Storage. +- [Design considerations](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/design-considerations.md.txt): Discusses some of the most common design considerations to analyze and take into account as part of your hybrid and multicloud networking design. +- [Design secure deployment pipelines](https://docs.cloud.google.com/architecture/design-secure-deployment-pipelines-bp.md.txt): Describes best practices for designing secure deployment pipelines based on your confidentiality, integrity, and availability requirements. +- [Evict consumer accounts](https://docs.cloud.google.com/architecture/identity/evicting-consumer-accounts.md.txt): Describes how to mitigate social engineering risks by removing (evicting) corporate email addresses from consumer accounts. +- [Example announcement](https://docs.cloud.google.com/architecture/identity/example-announcement.md.txt): Provides an example of an email to announce the migration of consumer accounts to managed accounts. +- [Federate Google Cloud with Active Directory](https://docs.cloud.google.com/architecture/identity/federating-gcp-with-active-directory-introduction.md.txt): Describes how you can configure Cloud Identity or Google Workspace to use Active Directory as IdP and authoritative source. +- [Federate Google Cloud with Microsoft Entra ID (formerly Azure AD)](https://docs.cloud.google.com/architecture/identity/federating-gcp-with-azure-active-directory.md.txt): Describes how to configure Cloud Identity or Google Workspace to use Microsoft Entra ID as the IdP and source for identities. +- [FortiGate architecture in Google Cloud](https://docs.cloud.google.com/architecture/partners/fortigate-architecture-in-cloud.md.txt): Describes the overall concepts around deploying a FortiGate Next Generation Firewall (NGFW) in Google Cloud. +- [Gated egress and gated ingress](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/gated-egress-ingress.md.txt): Discusses scenarios that demand bidirectional usage of selected APIs between workloads that run in various environments. +- [Gated egress](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/gated-egress.md.txt): Discusses how the gated egress pattern is based on exposing select APIs from various environments to workloads that are deployed in Google Cloud. +- [Gated ingress](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/gated-ingress.md.txt): Discusses exposing select APIs of workloads running in Google Cloud to the private computing environment without exposing them to the public internet. +- [Gated patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/gated-patterns.md.txt): Discusses how gated patterns can be adapted to various applications with diverse requirements. +- [General best practices](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/general-best-practices.md.txt): Discusses several common best practices that you can use for hybrid and multicloud architectures. +- [Handover patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/handover-pattern.md.txt): Discusses how to connect a private computing environment to projects in Google Cloud. +- [Hybrid and multicloud secure networking architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns.md.txt): Discusses several common secure network architecture patterns that you can use for hybrid and multicloud architectures. +- [Hybrid and multicloud secure networking architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/one-page-view.md.txt): Describes common hybrid and multicloud architecture patterns, the scenarios that these patterns are best suited for, and best practices for using the paterns. +- [Identify and prioritize security risks with Wiz Security Graph and Google Cloud](https://docs.cloud.google.com/architecture/partners/id-prioritize-security-risks-with-wiz.md.txt): Describes how to identify and prioritize security risks in your cloud workloads with Wiz Security Graph and Google Cloud. +- [Import data into a secured BigQuery data warehouse](https://docs.cloud.google.com/architecture/blueprints/confidential-data-warehouse-blueprint.md.txt): Describes an architecture that you can use to help secure a data warehouse in a production environment, and provides best practices for data governance of a data warehouse in Google Cloud. +- [Keycloak single sign-on](https://docs.cloud.google.com/architecture/identity/keycloak-single-sign-on.md.txt): Shows how to set up single sign-on (SSO) between Keycloak and your Cloud Identity or Google Workspace account by using SAML federation. +- [Limiting scope of compliance for PCI environments in Google Cloud](https://docs.cloud.google.com/architecture/limiting-compliance-scope-pci-environments-google-cloud.md.txt): Describes best practices for architecting your cloud environment for Payment Card Industry (PCI) Security Standards Council compliance. +- [Mapping BeyondProd security principles to the blueprint](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/mapping-beyondprod-security-principles.md.txt): Provides the mapping between BeyondProd security principles and a blueprint for an enterprise developer platform. +- [Meshed pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/meshed-pattern.md.txt): Discusses a meshed pattern architecture that's based on establishing a hybrid network architecture that spans multiple computing environments. +- [Microsoft Entra ID (formerly Azure AD) B2B user provisioning and single sign-on](https://docs.cloud.google.com/architecture/identity/azure-ad-b2b-user-provisioning-and-sso.md.txt): Shows how to extend Microsoft Entra ID user provisioning and single sign-on to enable single sign-on (SSO) for Microsoft Entra ID B2B collaboration users. +- [Microsoft Entra ID (formerly Azure AD) user provisioning and single sign-on](https://docs.cloud.google.com/architecture/identity/federating-gcp-with-azure-ad-configuring-provisioning-and-single-sign-on.md.txt): Shows how to set up user provisioning and single sign-on (SSO) between a Microsoft Entra ID tenant and your Cloud Identity or Google Workspace account. +- [Microsoft My Apps portal integration](https://docs.cloud.google.com/architecture/identity/integrating-google-services-and-apps-with-azure-ad-portal.md.txt): Shows how to add Google services and Identity-Aware Proxy (IAP) web-secured web applications to the Microsoft My Apps portal and how to enable automatic sign-on for these applications. +- [Migrate consumer accounts](https://docs.cloud.google.com/architecture/identity/migrating-consumer-accounts.md.txt): Describes how to migrate consumer accounts to managed user accounts that are controlled by Cloud Identity or by Google Workspace. +- [Mirrored pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-secure-networking-patterns/mirrored-pattern.md.txt): Discusses replicating the design of a certain existing environment or environments to a new environment or environments. +- [Mitigate ransomware attacks using Google Cloud](https://docs.cloud.google.com/architecture/security/mitigating-ransomware-attacks.md.txt): Describes the ransomware attack sequence and how Google Cloud can help your organization mitigate the effects of ransomware attacks. +- [Network security for distributed applications in Cross-Cloud Network](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/security.md.txt): Describes how to design Cross-Cloud Network security for distributed applications. +- [Networking for secure intra-cloud access: Reference architectures](https://docs.cloud.google.com/architecture/network-secure-intra-cloud-access.md.txt): Describes security and network connectivity architectures for intra-cloud access. +- [Okta user provisioning and single sign-on](https://docs.cloud.google.com/architecture/identity/okta-provisioning-and-single-sign-on.md.txt): Shows how to set up user provisioning and single sign-on (SSO) between an Okta organization and your Cloud Identity or Google Workspace account. +- [Overview of consolidating accounts](https://docs.cloud.google.com/architecture/identity/overview-consolidating-accounts.md.txt): Describes how to consolidate existing consumer accounts so that you can manage and control user accounts. +- [Overview of Google identity management](https://docs.cloud.google.com/architecture/identity/overview-google-authentication.md.txt): Explains the domain model that Google services rely on for authentication and identity management. +- [Overview of identity and access management](https://docs.cloud.google.com/architecture/identity.md.txt): Explores the general practice of identity and access management (generally referred to as IAM) and the individuals who are subject to it, including corporate identities, customer identities, and service identities. +- [OWASP Top 10 2021 mitigation options on Google Cloud](https://docs.cloud.google.com/architecture/security/owasp-top-ten-mitigation.md.txt): Helps you identify Google Cloud products and mitigation strategies that can help you defend against common application-level attacks that are outlined in OWASP Top 10. +- [Patterns and practices for identity and access governance on Google Cloud](https://docs.cloud.google.com/architecture/patterns-practices-identity-access-governance-google-cloud.md.txt): Describes patterns and practices for identity and access governance on Google Cloud. +- [PCI Data Security Standard compliance](https://docs.cloud.google.com/architecture/pci-dss-compliance-in-gcp.md.txt): Shows how to implement the Payment Card Industry Data Security Standard (PCI DSS) for your business on Google Cloud. +- [PCI DSS compliance on GKE](https://docs.cloud.google.com/architecture/pci-dss-and-gke-guide.md.txt): Provides guidance to address the requirements of the Payment Card Industry Data Security Standard (PCI DSS) for Google Kubernetes Engine (GKE) applications. +- [Plan the onboarding process for your corporate identities](https://docs.cloud.google.com/architecture/identity/overview-assess-and-plan.md.txt): Provides guidance to assess requirements and develop a plan for onboarding corporate identities to Cloud Identity or Google Workspace. +- [Prepare your Google Workspace or Cloud Identity account](https://docs.cloud.google.com/architecture/identity/preparing-your-g-suite-or-cloud-identity-account.md.txt): Describes how to create a Cloud Identity or Google Workspace account and how to prepare the account for a production deployment. +- [Reconcile orphaned managed user accounts](https://docs.cloud.google.com/architecture/identity/reconciling-orphaned-managed-user-accounts.md.txt): Describes how to identify and reconcile orphaned user accounts. +- [Reference architectures](https://docs.cloud.google.com/architecture/identity/reference-architectures.md.txt): Provides architectures that you can use as references for managing corporate identities. +- [Remove Gmail from consumer accounts](https://docs.cloud.google.com/architecture/identity/removing-gmail-from-consumer-accounts.md.txt): Describes how to remove Gmail from an existing consumer account to enable the user account to be migrated to Cloud Identity or Google Workspace. +- [Sanitize Gmail accounts](https://docs.cloud.google.com/architecture/identity/sanitizing-gmail-accounts.md.txt): Describes how to sanitize existing Gmail accounts by deliberately removing any corporate email addresses from them. +- [Secure apps and resources by using context-aware access](https://docs.cloud.google.com/architecture/secure-apps-resources-using-context-aware-access.md.txt): Describes how you can enforce context-aware access for different types of apps and resources. +- [Secure data environments in Google Cloud](https://docs.cloud.google.com/architecture/secure-data-environments.md.txt): A high-level architecture to secure sensitive datasets against accidental exposure and malicious exfiltration. +- [Secure virtual private cloud networks with the Palo Alto VM-Series NGFW](https://docs.cloud.google.com/architecture/partners/palo-alto-networks-ngfw.md.txt): Describes the networking concepts that you need to understand to deploy Palo Alto Networks VM-Series next generation firewall (NGFW) in Google Cloud. +- [Security blueprint: PCI on GKE](https://docs.cloud.google.com/architecture/gke-pci-dss-blueprint.md.txt): Provides a Terraform-based blueprint for a Google Kubernetes Engine (GKE) environment that aligns with the Payment Card Industry Data Security Standard (PCI DSS). +- [Security log analytics in Google Cloud](https://docs.cloud.google.com/architecture/security-log-analytics.md.txt): Shows how to collect, export, and analyze logs from Google Cloud to help you audit usage and detect threats to your data and workloads. Use the included threat detection queries for BigQuery or Chronicle, or bring your own SIEM. +- [Single sign-on](https://docs.cloud.google.com/architecture/identity/single-sign-on.md.txt): Describes how to configure your Cloud Identity or Google Workspace account to use single sign-on (SSO). +- [Tokenizing sensitive cardholder data for PCI DSS](https://docs.cloud.google.com/architecture/tokenizing-sensitive-cardholder-data-for-pci-dss.md.txt): Shows how to set up an access-controlled credit and debit card tokenization service on Cloud Functions. +- [VMware Engine network security using centralized appliances](https://docs.cloud.google.com/architecture/gcve-advanced-network-security.md.txt): Provides guidance to design advanced network security for VMware Engine workloads to provide network protection features like DDoS mitigation, SSL offloading, NGFW, IPS/IDS, and DPI. +- [Well-Architected Framework: Security, privacy, and compliance pillar](https://docs.cloud.google.com/architecture/framework/security/printable.md.txt): Provides principles and recommendations to help you design, deploy, and operate Google Cloud workloads that meet your requirements for security, privacy, and compliance. + +## Reliability and disaster recovery + +- [Architecting disaster recovery for cloud infrastructure outages](https://docs.cloud.google.com/architecture/disaster-recovery.md.txt): Describes how Google Cloud is designed for resilience, discusses the process for architecting resilient workloads on Google Cloud, and provides product-specific disaster recovery (DR) guidance for zonal and regional outages. +- [Architecting disaster recovery for locality-restricted workloads](https://docs.cloud.google.com/architecture/architecting-disaster-recovery-for-locality-restricted-workloads.md.txt): Discusses how to architect disaster recovery (DR) for locality-restricted workloads. +- [Architectures for high availability of PostgreSQL clusters on Compute Engine](https://docs.cloud.google.com/architecture/architectures-high-availability-postgresql-clusters-compute-engine.md.txt): Several architectures that provide high availability (HA) for PostgreSQL deployments on Google Cloud. +- [Assess the reliability requirements for your cloud workloads](https://docs.cloud.google.com/architecture/infra-reliability-guide/requirements.md.txt): Provides guidelines to help you assess the reliability requirements of your cloud workloads. +- [Building blocks of reliability in Google Cloud](https://docs.cloud.google.com/architecture/infra-reliability-guide/building-blocks.md.txt): Introduces the building blocks of reliability in Google Cloud. +- [Business continuity hybrid and multicloud patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/business-continuity-patterns.md.txt): Discusses how the business continuity pattern relies on a redundant deployment of applications across multiple computing environments. +- [Business continuity with CI/CD on Google Cloud](https://docs.cloud.google.com/architecture/business-continuity-with-cicd-on-google-cloud.md.txt): "Learn about developing a business continuity plan (BCP) for the CI/CD process." +- [Delete the Load balanced managed VMs](https://docs.cloud.google.com/architecture/reliability/load-balanced-vms.md.txt): Delete Load balanced managed VMs Jump Start Solution. +- [Design reliable infrastructure for your workloads in Google Cloud](https://docs.cloud.google.com/architecture/infra-reliability-guide/design.md.txt): Provides architectural recommendations to design reliable infrastructure for your cloud workloads. +- [Disaster recovery building blocks](https://docs.cloud.google.com/architecture/dr-scenarios-building-blocks.md.txt): Discusses Google Cloud services and products that you can use as building blocks for your disaster recovery (DR) plan. +- [Disaster recovery planning guide](https://docs.cloud.google.com/architecture/dr-scenarios-planning-guide.md.txt): The first part of a series that discusses disaster recovery (DR) in Google Cloud. This part provides an overview of the DR planning process: what you need to know in order to design and implement a DR plan. +- [Disaster recovery scenarios for applications](https://docs.cloud.google.com/architecture/dr-scenarios-for-applications.md.txt): Explores common disaster recovery (DR) scenarios for applications. +- [Disaster recovery scenarios for data](https://docs.cloud.google.com/architecture/dr-scenarios-for-data.md.txt): Discusses disaster recovery (DR) scenarios for backing up and recovering data. +- [Disaster recovery use cases: locality-restricted data analytics applications](https://docs.cloud.google.com/architecture/dr-scenarios-locality-restricted-data-analytics.md.txt): Describes disaster recovery (DR) use cases for locality-restricted data analytics applications. +- [Google Cloud infrastructure reliability guide](https://docs.cloud.google.com/architecture/infra-reliability-guide.md.txt): Introduces the building blocks of reliability in Google Cloud, and provides architectural recommendations to design reliable infrastructure for your cloud workloads. +- [Manage and monitor your Google Cloud infrastructure](https://docs.cloud.google.com/architecture/infra-reliability-guide/manage-and-monitor.md.txt): Summarizes guidelines to manage and monitor your infrastructure resources for reliability. +- [Manage traffic and load for your workloads in Google Cloud](https://docs.cloud.google.com/architecture/infra-reliability-guide/traffic-load.md.txt): Describes traffic-management and load-management techniques that you can use to improve the reliability of your cloud workloads. +- [Migrate across Google Cloud regions: Design resilient single-region environments on Google Cloud](https://docs.cloud.google.com/architecture/migrate-across-regions/design-resilient-single-region-environments.md.txt): Design resilient, single-region environments on Google Cloud. +- [Patterns for scalable and resilient apps](https://docs.cloud.google.com/architecture/scalable-and-resilient-apps.md.txt): Introduces some patterns and practices for creating apps that are resilient and scalable, two essential goals of many modern architecture exercises. +- [Well-Architected Framework: Reliability pillar](https://docs.cloud.google.com/architecture/framework/reliability/printable.md.txt): Provides principles and recommendations to help you design, deploy, and manage reliable workloads in Google Cloud. + +## Data and analytics + +- [Analytics hybrid and multicloud pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/analytics-hybrid-multicloud-pattern.md.txt): Discusses that the objective of the analytics hybrid and multicloud pattern is to capitalize on the split between transactional and analytics workloads. +- [Architecture and functions in a data mesh](https://docs.cloud.google.com/architecture/data-mesh.md.txt): Describes the architecture and components of a data mesh that's deployed in Google Cloud. +- [Build data products in a data mesh](https://docs.cloud.google.com/architecture/build-data-products-data-mesh.md.txt): Describes design considerations for building data products in a data mesh. +- [Continuous data replication to BigQuery using Striim](https://docs.cloud.google.com/architecture/partners/continuous-data-replication-bigquery-striim.md.txt): Demonstrates how to migrate a MySQL database to BigQuery using Striim. Striim is a comprehensive streaming extract, transform, and load (ETL) platform. +- [Continuous data replication to Spanner using Striim](https://docs.cloud.google.com/architecture/partners/continuous-data-replication-cloud-spanner-striim.md.txt): How to migrate a MySQL database to Cloud Spanner using Striim. +- [Data management with Cohesity Helios and Google Cloud](https://docs.cloud.google.com/architecture/partners/using-cohesity-with-cloud-storage-for-enterprise-hybrid-data-protection.md.txt): How Cohesity works with Google Cloud Storage. Cohesity is a hyperconverged secondary storage system for consolidating backup, test/dev, file services, and analytic datasets onto a scalable data platform. +- [Delete the Analytics lakehouse](https://docs.cloud.google.com/architecture/big-data-analytics/analytics-lakehouse.md.txt): Delete Analytics lakehouse Jump Start Solution. +- [Delete the Data warehouse with BigQuery](https://docs.cloud.google.com/architecture/big-data-analytics/data-warehouse.md.txt): Delete Data warehouse with BigQuery Jump Start Solution. +- [Deploy an enterprise data management and analytics platform](https://docs.cloud.google.com/architecture/blueprints/deploy_enterprise_data_mesh.md.txt): Describes an enterprise-ready data mesh architecture that you can deploy to protect confidential data. +- [Deploy scalable BigQuery backup automation](https://docs.cloud.google.com/architecture/scalable-bigquery-backup-automation/deployment.md.txt): Build a solution to automate recurrent BigQuery backup operations at scale, with two backup methods: BigQuery snapshots and exports to Cloud Storage. +- [Design a self-service data platform for a data mesh](https://docs.cloud.google.com/architecture/design-self-service-data-platform-data-mesh.md.txt): Describes how to design a self-service data-mesh platform that domain teams can use to create and consume data products. +- [Device on Pub/Sub connection to Google Cloud](https://docs.cloud.google.com/architecture/connected-devices/device-pubsub-architecture.md.txt): Describes architectural considerations when you directly connect an IoT aggregation device or gateway to Pub/Sub. +- [Discover and consume data products in a data mesh](https://docs.cloud.google.com/architecture/discover-consume-data-products-data-mesh.md.txt): Discusses how domain teams can discover and consume data products in a data mesh. +- [Migrate to Google Cloud: Transfer your large datasets](https://docs.cloud.google.com/architecture/migration-to-google-cloud-transferring-your-large-datasets.md.txt): Provides guidance for transferring large datasets efficiently for workloads that you migrate to Google Cloud. +- [Scalable BigQuery backup automation](https://docs.cloud.google.com/architecture/scalable-bigquery-backup-automation.md.txt): Build a solution to automate recurrent BigQuery backup operations at scale, with two backup methods: BigQuery snapshots and exports to Cloud Storage. + +## Databases + +- [Apache Guacamole on GKE and Cloud SQL](https://docs.cloud.google.com/architecture/deploy-guacamole-gke.md.txt): Describes an architecture for hosting Apache Guacamole on Google Kubernetes Engine (GKE) and Cloud SQL. Apache Guacamole offers a fully browser-based way to access remote desktops through Remote Desktop Protocol (RDP). +- [Database migration: Concepts and principles (Part 1)](https://docs.cloud.google.com/architecture/database-migration-concepts-principles-part-1.md.txt): Introduces concepts, principles, terminology, and architecture of near-zero downtime database migration from on-premises or other cloud environments. +- [Database migration: Concepts and principles (Part 2)](https://docs.cloud.google.com/architecture/database-migration-concepts-principles-part-2.md.txt): Discusses how to set up and execute the database migration process, including failure scenarios. +- [Define the scope of your migration to Redis Enterprise Cloud](https://docs.cloud.google.com/architecture/partners/riot-live-migration-redis-enterprise-cloud/assessment.md.txt): Describes how to define the scope of a migration that uses RIOT Live Migration to migrate to fully managed Redis Enterprise Cloud in Google Cloud. +- [Deploy Apache Guacamole on GKE and Cloud SQL](https://docs.cloud.google.com/architecture/deploy-guacamole-gke/deployment.md.txt): Describes how to deploy Apache Guacamole on Google Kubernetes Engine (GKE) and Cloud SQL. +- [Deploy RIOT Live Migration to migrate to Redis Enterprise Cloud](https://docs.cloud.google.com/architecture/partners/riot-live-migration-redis-enterprise-cloud/deployment.md.txt): Describes how to deploy an architecture to migrate from Redis-compatible sources to fully managed Redis Enterprise Cloud in Google Cloud using RIOT Live Migration service. +- [Enterprise application on Compute Engine with Oracle Exadata](https://docs.cloud.google.com/architecture/enterprise-app-oracle-exadata-database-compute-engine.md.txt): Provides a reference architecture for an application that's hosted on Compute Engine VMs with connectivity to Oracle Cloud Infrastructure (OCI) Exadata databases in Google Cloud. +- [Enterprise application with Oracle Database on Compute Engine](https://docs.cloud.google.com/architecture/enterprise-app-oracle-database-compute-engine.md.txt): Provides a reference architecture to host an application that uses an Oracle database, deployed on Compute Engine VMs. +- [Global deployment with Compute Engine and Spanner](https://docs.cloud.google.com/architecture/global-deployment-compute-engine-spanner.md.txt): Learn how to architect a multi-tier application that runs on Compute Engine VMs and Spanner in a global topology on Google Cloud. +- [Microsoft SQL Server Always On availability group in Google Cloud](https://docs.cloud.google.com/architecture/sql-server-alwayson-availability-group-compute-engine.md.txt): Provides a reference architecture for deploying high-availability +(HA) Microsoft SQL Server databases in Google Cloud by using an Always On availability group. +- [Migrate from AWS to Google Cloud: Migrate from Amazon RDS and Amazon Aurora for MySQL to Cloud SQL for MySQL](https://docs.cloud.google.com/architecture/migrate-aws-rds-to-sql-mysql.md.txt): Describes how to design, implement, and validate a plan to migrate from Amazon Relational Database Service (RDS) or Aurora to Cloud SQL for MySQL. +- [Migrate from AWS to Google Cloud: Migrate from Amazon RDS and Amazon Aurora for PostgreSQL to Cloud SQL and AlloyDB for PostgreSQL](https://docs.cloud.google.com/architecture/migrate-aws-rds-aurora-to-postgresql.md.txt): Describes how to design, implement, and validate a plan to migrate from Amazon Relational Database Service (RDS) or Aurora to Cloud SQL for PostgreSQL or AlloyDB for PostgreSQL. +- [Migrate from AWS to Google Cloud: Migrate from Amazon RDS for SQL Server to Cloud SQL for SQL Server](https://docs.cloud.google.com/architecture/migrate-aws-rds-to-cloudsql-for-sqlserver.md.txt): Describes how to design, implement, and validate a plan to migrate from Amazon Relational Database Service (RDS) to Cloud SQL for SQL Server. +- [Multicloud database management: Architectures, use cases, and best practices](https://docs.cloud.google.com/architecture/multi-cloud-database-management.md.txt): Describes architectures, use cases, and best practices for multicloud database management. +- [Oracle E-Business Suite on Compute Engine with Oracle Exadata](https://docs.cloud.google.com/architecture/oracle-ebs-with-oci-exadata.md.txt): Shows how to build the infrastructure to run Oracle E-Business Suite applications with Oracle Cloud Infrastructure Exadata in Google Cloud. +- [Oracle E-Business Suite with Oracle Database on Compute Engine](https://docs.cloud.google.com/architecture/oracle-ebs-on-compute-engine-vm.md.txt): Shows how to build the infrastructure to run Oracle E-Business Suite applications with Oracle Database on Compute Engine VMs in Google Cloud. +- [Oracle PeopleSoft on Compute Engine with Oracle Exadata](https://docs.cloud.google.com/architecture/oracle-peoplesoft-with-oci-exadata.md.txt): Shows how to build the infrastructure to run Oracle PeopleSoft applications with Oracle Cloud Infrastructure Exadata in Google Cloud. +- [Use RIOT Live Migration to migrate to Redis Enterprise Cloud](https://docs.cloud.google.com/architecture/partners/riot-live-migration-redis-enterprise-cloud.md.txt): Describes an architecture to migrate from Redis-compatible sources to fully managed Redis Enterprise Cloud in Google Cloud using RIOT Live Migration service. + +## Migration + +- [Architect your workloads](https://docs.cloud.google.com/architecture/migrate-across-regions/architect-workloads.md.txt): Design resilient, single-region environments on Google Cloud. +- [Designing networks for migrating enterprise workloads: Architectural approaches](https://docs.cloud.google.com/architecture/network-architecture.md.txt): Provides an overview of networking and security architectures for enterprises that are migrating workloads to Google Cloud. +- [Log and monitor on-premises resources with BindPlane](https://docs.cloud.google.com/architecture/logging-and-monitoring-on-premises-resources-with-bindplane.md.txt): Describes considerations and design patterns for using Cloud Logging, Cloud Monitoring, and BindPlane to provide logging and monitoring services for on-premises resources. +- [Log on-premises resources with BindPlane](https://docs.cloud.google.com/architecture/logging-on-premises-resources-with-bindplane.md.txt): Describes how to use Cloud Logging and BindPlane to log on-premises resources. +- [Migrate across Google Cloud regions: Get started](https://docs.cloud.google.com/architecture/migrate-across-regions.md.txt): Start preparing your workloads and data for migration across Google Cloud regions. +- [Migrate across Google Cloud regions: Prepare data and batch workloads for migration across regions](https://docs.cloud.google.com/architecture/migrate-across-regions/prepare-data-and-batch-workloads.md.txt): Prepare data and batch workloads for migration across regions. +- [Migrate containers to Google Cloud: Migrate from Kubernetes to GKE](https://docs.cloud.google.com/architecture/migrating-containers-kubernetes-gke.md.txt): Describes how to design, implement, and validate a plan to migrate from Kubernetes to Google Kubernetes Engine (GKE). +- [Migrate from AWS to Google Cloud: Get started](https://docs.cloud.google.com/architecture/migration-from-aws-get-started.md.txt): Describes how to design, implement, and validate a plan to migrate from AWS to Google Cloud. +- [Migrate from AWS to Google Cloud: Migrate from Amazon EC2 to Compute Engine](https://docs.cloud.google.com/architecture/migrate-amazon-ec2-to-compute-engine.md.txt): Describes how to design, implement, and validate a plan to migrate from Amazon EC2 to Compute Engine. +- [Migrate from AWS to Google Cloud: Migrate from Amazon EKS to GKE](https://docs.cloud.google.com/architecture/migrate-amazon-eks-to-gke.md.txt): Design, implement, and validate a plan to migrate from Amazon EKS to Google Kubernetes Engine. +- [Migrate from AWS to Google Cloud: Migrate from Amazon S3 to Cloud Storage](https://docs.cloud.google.com/architecture/migrate-amazon-s3-to-cloud-storage.md.txt): Describes how to design, implement, and validate a plan to migrate from Amazon S3 to Cloud Storage. +- [Migrate from AWS to Google Cloud: Migrate from AWS Lambda to Cloud Run](https://docs.cloud.google.com/architecture/migrate-aws-lambda-to-cloudrun.md.txt): Describes how to design, implement, and validate a plan to migrate from AWS Lambda to Cloud Run. +- [Migrate from Azure to Google Cloud: Get started](https://docs.cloud.google.com/architecture/migration-from-azure-get-started.md.txt): Describes how to design, implement, and validate a plan to migrate from Azure to Google Cloud. +- [Migrate on-premises VMs to Google Cloud](https://docs.cloud.google.com/architecture/migrate-on-premises-vms.md.txt): Provides links to guides for migrating on-premises VM workloads to Google Cloud. +- [Migrate to a Google Cloud VMware Engine platform](https://docs.cloud.google.com/architecture/blueprints/vmware-engine-blueprint.md.txt): Describes the VMware Engine blueprint, which deploys a platform for VM workloads. +- [Migrate to Google Cloud: Assess and discover your workloads](https://docs.cloud.google.com/architecture/migration-to-gcp-assessing-and-discovering-your-workloads.md.txt): Describes the activities in the assessment phase of the process to migrate to Google Cloud. +- [Migrate to Google Cloud: Best practices for validating a migration plan](https://docs.cloud.google.com/architecture/migration-to-google-cloud-best-practices.md.txt): Describes how to design, implement, and validate a plan to migrate to Google Cloud. +- [Migrate to Google Cloud: Deploy your workloads](https://docs.cloud.google.com/architecture/migration-to-gcp-deploying-your-workloads.md.txt): Describes the activities in the deployment phase of the process to migrate to Google Cloud. +- [Migrate to Google Cloud: Get started](https://docs.cloud.google.com/architecture/migration-to-gcp-getting-started.md.txt): Helps you plan, design, and implement the process of migrating your application and infrastructure workloads to Google Cloud, including computing, database, and storage workloads. +- [Migrate to Google Cloud: Migrate from manual deployments to automated, containerized deployments](https://docs.cloud.google.com/architecture/migration-to-google-cloud-automated-containerized-deployments.md.txt): Describes how to plan and design a migration path from manual deployments to automated, containerized deployments in Google Cloud. +- [Migrate to Google Cloud: Minimize costs](https://docs.cloud.google.com/architecture/migration-to-google-cloud-minimize-costs.md.txt): Provide guidance to help you optimize the costs of workloads that you migrate to single-region and multi-region environments in Google Cloud. +- [Migrate to Google Cloud: Optimize your environment](https://docs.cloud.google.com/architecture/migration-to-google-cloud-optimizing-your-environment.md.txt): Provides guidance to help you continuously optimize the environment for a workload that you've migrated to Google Cloud. +- [Migrate to Google Cloud: Plan and build your foundation](https://docs.cloud.google.com/architecture/migration-to-google-cloud-building-your-foundation.md.txt): Describes how to plan and build a foundation on Google Cloud. +- [Monitor on-premises resources with BindPlane](https://docs.cloud.google.com/architecture/monitoring-on-premises-resources-with-bindplane.md.txt): Describes how to use Cloud Monitoring and BindPlane to monitor on-premises resources. + +## Networking + +- [Best practices and reference architectures for VPC design](https://docs.cloud.google.com/architecture/best-practices-vpc-design.md.txt): This guide introduces best practices and typical enterprise architectures for the design of virtual private clouds (VPCs) with Google Cloud. +- [Cross-Cloud Network for distributed applications](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design.md.txt): Describes how to design Cross-Cloud Network for distributed applications. +- [Cross-Cloud Network inter-VPC connectivity using Network Connectivity Center](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/ccn-ncc-vpn-ra.md.txt): Describes how to design the network segmentation structure and connectivity of Cross-Cloud Network with Network Connectivity Center. +- [Cross-Cloud Network inter-VPC connectivity using VPC Network Peering](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/ccn-vnp-vpn-ra.md.txt): Describes how to design the network segmentation structure and connectivity of Cross-Cloud Network for distributed applications. +- [Deploy Windows applications on managed Kubernetes](https://docs.cloud.google.com/architecture/manage-and-scale-windows-networking/deployment.md.txt): Describes how to deploy a reference architecture to manage and scale networking for Windows applications that run on managed Kubernetes. +- [From edge to mesh: Deploy service mesh applications through GKE Gateway](https://docs.cloud.google.com/architecture/exposing-service-mesh-apps-through-gke-ingress/deployment.md.txt): Shows how to combine Cloud Service Mesh with Cloud Load Balancing to expose applications in a service mesh to internet clients. +- [From edge to mesh: Expose service mesh applications through GKE Gateway](https://docs.cloud.google.com/architecture/exposing-service-mesh-apps-through-gke-ingress.md.txt): Combines Cloud Service Mesh with Cloud Load Balancing to expose applications in a service mesh to internet clients. +- [Hub-and-spoke network architecture](https://docs.cloud.google.com/architecture/deploy-hub-spoke-vpc-network-topology.md.txt): Discusses the architectural options for designing hub-and-spoke network topologies in Google Cloud. +- [Manage and scale networking for Windows applications that run on managed Kubernetes](https://docs.cloud.google.com/architecture/manage-and-scale-windows-networking.md.txt): Discusses how to manage networking for Windows applications that run on Google Kubernetes Engine using Cloud Service Mesh and Envoy gateways. +- [Multi-agent private networking patterns in Google Cloud](https://docs.cloud.google.com/architecture/multi-agent-private-networking-patterns.md.txt): Guidance to help you design private networking infrastructure that supports a publicly accessible, multi-agent, Gemini Enterprise app with private connections between agents, subagents, and tools. +- [Network segmentation and connectivity for distributed applications in Cross-Cloud Network](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/connectivity.md.txt): Describe how to design the network segmentation structure and connectivity of Cross-Cloud Network for distributed applications. +- [Networking for hybrid and multi-cloud workloads: Reference architectures](https://docs.cloud.google.com/architecture/network-hybrid-multicloud.md.txt): Discusses networking for a scenario where workloads run in more than one place, such as on-premises and the cloud, or in multiple cloud environments. +- [Networking for internet-facing application delivery: Reference architectures](https://docs.cloud.google.com/architecture/network-application-delivery.md.txt): Describes reference architectures to help you design networking and security for internet-facing application delivery. +- [Patterns for using floating IP addresses in Compute Engine](https://docs.cloud.google.com/architecture/patterns-for-floating-ip-addresses-in-compute-engine.md.txt): How to use floating IP address patterns when migrating applications to Compute Engine from an on-premises network. +- [Service networking for distributed applications in Cross-Cloud Network](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/service-networking.md.txt): Describes how to design Cross-Cloud Network service networking for distributed applications. +- [Use Google Cloud Armor, load balancing, and Cloud CDN to deploy programmable global front ends](https://docs.cloud.google.com/architecture/deploy-programmable-gfe-cloud-armor-lb-cdn.md.txt): Provides an architecture that uses a global front end which incorporates Google Cloud best practices to help scale, secure, and accelerate the delivery of your internet-facing applications. +- [VPC Network Peering Cross-Cloud Network with NVAs and regional affinity](https://docs.cloud.google.com/architecture/ccn-distributed-apps-design/ccn-nva-ra.md.txt): Describes how to include NVAs into a regional affinity CCN deployment. + +## Hybrid, multi-cloud, and distributed cloud + +- [Architectural approaches to adopt a hybrid or multicloud architecture](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns/adopt.md.txt): Provides guidance on common proven approaches and considerations to migrate your workload to the cloud. +- [Authenticate workforce users in a hybrid environment](https://docs.cloud.google.com/architecture/authenticating-corporate-users-in-a-hybrid-environment.md.txt): How to extend your identity management solution to Google Cloud to enable your workforce to authenticate and consume services in a hybrid computing environment. +- [Build a hybrid render farm](https://docs.cloud.google.com/architecture/building-a-hybrid-render-farm.md.txt): Provides guidance on extending your existing, on-premises render farm to use compute resources on Google Cloud (Google Cloud). +- [Build hybrid and multicloud architectures using Google Cloud](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns.md.txt): Provides practical guidance on planning and architecting your hybrid and multi-cloud environments using Google Cloud. +- [Cloud bursting pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/cloud-bursting-pattern.md.txt): Discusses how to manage bursty workloads with the cloud bursting architecture pattern. +- [Distributed architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/distributed-patterns.md.txt): Discusses how to avoid or overcome design constraints and how to take advantage of each computing environment in a distributed architecture. +- [Drivers, considerations, strategy, and approaches](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns/drivers.md.txt): Defines and discusses business objectives, drivers, and requirements, and how these factors can influence your design decisions. +- [Edge hybrid pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/edge-hybrid-pattern.md.txt): Discusses how the edge hybrid pattern addresses connectivity challenges by running time- and business-critical workloads locally, at the edge of the network. +- [Environment hybrid pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/environment-hybrid-pattern.md.txt): Discusses how to keep the production environment of a workload in the existing data center but use the public cloud for other, non-production environments. +- [Hybrid and multicloud architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices.md.txt): Discusses common hybrid and multicloud architecture patterns, and describes the scenarios that these patterns are best suited for. +- [Hybrid and multicloud architecture patterns](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/one-page-view.md.txt): Discusses common hybrid and multicloud architecture patterns. It also describes the scenarios that these patterns are best suited for. +- [Hybrid and multicloud monitoring and logging patterns](https://docs.cloud.google.com/architecture/hybrid-and-multi-cloud-monitoring-and-logging-patterns.md.txt): Discusses monitoring and logging architectures for hybrid and multicloud deployments, and provides best practices for implementing them by using Google Cloud. +- [Other considerations](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns/other-considerations.md.txt): Highlights essential core design considerations that play a pivotal role in shaping your overall hybrid and multicloud architecture. +- [Partitioned multicloud pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/partitioned-multicloud-pattern.md.txt): Discusses how the pattern combines multiple public cloud environments that are operated by different CSPs and the flexibility it offers. +- [Patterns for authenticating workforce users in a hybrid environment](https://docs.cloud.google.com/architecture/patterns-for-authenticating-corporate-users-in-a-hybrid-environment.md.txt): Discusses patterns for authenticating workforce users in a hybrid cloud environment. +- [Patterns for connecting other cloud service providers with Google Cloud](https://docs.cloud.google.com/architecture/patterns-for-connecting-other-csps-with-gcp.md.txt): Helps cloud architects and operations professionals decide how to connect Google Cloud with other cloud service providers (CSP) such as Amazon Web Services (AWS) and Microsoft Azure. +- [Patterns for using Active Directory in a hybrid environment](https://docs.cloud.google.com/architecture/patterns-for-using-active-directory-in-a-hybrid-environment.md.txt): Requirements to consider when you deploy Active Directory to Google Cloud and helps you choose the right architecture. +- [Plan a hybrid and multicloud strategy](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns/strategy.md.txt): Discusses how to plan your hybrid and multi-cloud strategy. +- [Tiered hybrid pattern](https://docs.cloud.google.com/architecture/hybrid-multicloud-patterns-and-practices/tiered-hybrid-pattern.md.txt): Discusses the opportunties and challenges that a tiered hybrid architecture pattern offers. + +## Financial services + +- [Well-Architected Framework: Financial services (FS) perspective](https://docs.cloud.google.com/architecture/framework/perspectives/fsi/printable.md.txt): Provides principles and recommendations to help you design, build, and manage financial services (FS) applications in Google Cloud that meet your operational, security, reliability, cost, and performance goals. + +## Monitoring and logging + +- [Cloud Monitoring metric export](https://docs.cloud.google.com/architecture/monitoring-metric-export.md.txt): Describes a way to export Cloud Monitoring metrics for long-term analysis. +- [Deploy a job to import logs from Cloud Storage to Cloud Logging](https://docs.cloud.google.com/architecture/import-logs-from-storage-to-logging/deployment.md.txt): Learn how to import logs that were previously exported to Cloud Storage back to Cloud Logging. +- [Deploy log streaming from Google Cloud to Datadog](https://docs.cloud.google.com/architecture/partners/stream-cloud-logs-to-datadog/deployment.md.txt): Learn how to deploy a solution that sends log files to a Cloud Logging sink and then to Datadog. +- [Developer platform controls](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/developer-platform-controls.md.txt): Describes the security, networking, and reliability controls that are used in the blueprint for an enterprise developer platform. +- [Import logs from Cloud Storage to Cloud Logging](https://docs.cloud.google.com/architecture/import-logs-from-storage-to-logging.md.txt): Learn how to import logs that were previously exported to Cloud Storage back to Cloud Logging. +- [Logging and monitoring](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/logging-monitoring.md.txt): Describes how logging and monitoring work in a blueprint for an enterprise developer platform. +- [Operations for both the developer platform and applications](https://docs.cloud.google.com/architecture/blueprints/enterprise-application-blueprint/ops-developer-platform-applications.md.txt): Provides guidance to efficiently operate an enterprise developer platform and the deployed applications. +- [Stream logs from Google Cloud to Datadog](https://docs.cloud.google.com/architecture/partners/stream-cloud-logs-to-datadog.md.txt): Provides an architecture to send log event data from across your Google Cloud ecosystem to Datadog Log Management. +- [Stream logs from Google Cloud to Splunk](https://docs.cloud.google.com/architecture/stream-logs-from-google-cloud-to-splunk.md.txt): Create a production-ready, scalable, fault-tolerant, log export mechanism that streams logs and events from your resources in Google Cloud into Splunk. +- [Well-Architected Framework: Operational excellence pillar](https://docs.cloud.google.com/architecture/framework/operational-excellence/printable.md.txt): Provides principles and recommendations to help you manage and operate workloads efficiently in Google Cloud. + +## Storage + +- [Configuring SaaS data protection for Google Workspace data with Spin.AI](https://docs.cloud.google.com/architecture/partners/backing-up-workspace-data-with-spinone.md.txt): How to configure SpinOne - All-in-One SaaS Data Protection with Cloud Storage. +- [Design an optimal storage strategy for your cloud workload](https://docs.cloud.google.com/architecture/storage-advisor.md.txt): Provides guidance to help you design a storage strategy that's aligned with the requirements of your cloud workload. +- [Google Workspace Backup with Afi.ai](https://docs.cloud.google.com/architecture/partners/google-workspace-backup-with-afi-ai.md.txt): Describes how to set up an automated Google Workspace backup using Afi.ai. +- [Parallel file systems for HPC workloads](https://docs.cloud.google.com/architecture/parallel-file-systems-for-hpc.md.txt): Describes the storage options in Google Cloud for high performance computing (HPC) workloads, and provides guidance for when you should use parallel file systems like Managed Lustre for HPC workloads. diff --git a/skills/vendor/google/google-cloud-solution-architecture/references/best-practices-guides.md b/skills/vendor/google/google-cloud-solution-architecture/references/best-practices-guides.md new file mode 100644 index 0000000..37285b9 --- /dev/null +++ b/skills/vendor/google/google-cloud-solution-architecture/references/best-practices-guides.md @@ -0,0 +1,231 @@ +# Product-specific best practices guides + +| Product | Line hints | +|---------|------------| +| [Best practices covering multiple products](#multiple-products) | Lines 31-34 | +| [AI Hypercomputer](#ai-hypercomputer) | Lines 35-38 | +| [AlloyDB](#alloydb) | Lines 39-45 | +| [Backup and Disaster Recovery (DR) Service](#backup-and-disaster-recovery-dr-service) | Lines 46-53 | +| [BigQuery](#bigquery) | Lines 54-68 | +| [Cloud Armor](#cloud-armor) | Lines 69-72 | +| [Cloud Load Balancing](#cloud-load-balancing) | Lines 73-76 | +| [Cloud Run](#cloud-run) | Lines 77-84 | +| [Cloud Service Mesh](#cloud-service-mesh) | Lines 85-94 | +| [Cloud SQL](#cloud-sql) | Lines 95-102 | +| [Cloud Storage](#cloud-storage) | Lines 103-108 | +| [Compute Engine](#compute-engine) | Lines 109-125 | +| [Gemini Enterprise Agent Platform](#gemini-enterprise-agent-platform) | Lines 126-132 | +| [Google Kubernetes Engine (GKE)](#google-kubernetes-engine-gke) | Lines 133-152 | +| [Identity and Access Management (IAM)](#identity-and-access-management-iam) | Lines 153-162 | +| [Managed Service for Apache Spark](#managed-service-for-apache-spark) | Lines 163-167 | +| [Memorystore](#memorystore) | Lines 168-176 | +| [Migration](#migration) | Lines 177-181 | +| [Network Connectivity](#network-connectivity) | Lines 182-187 | +| [Observability in Google Cloud](#observability-in-google-cloud) | Lines 188-196 | +| [Pub/Sub](#pub-sub) | Lines 197-202 | +| [Security Command Center](#security-command-center) | Lines 203-206 | +| [Security](#security) | Lines 207-216 | +| [Spanner](#spanner) | Lines 217-228 | +| [Vertex AI](#vertex-ai) | Lines 229-232 | + +## Best practices covering multiple products + +- https://docs.cloud.google.com/workload-manager/docs/reference/best-practices-general.md.txt + +## AI Hypercomputer + +- https://docs.cloud.google.com/ai-hypercomputer/docs/networking-best-practices.md.txt + +## AlloyDB + +- https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann.md.txt +- https://docs.cloud.google.com/alloydb/docs/auth-proxy/best-practices.md.txt +- https://docs.cloud.google.com/alloydb/docs/import-export-best-practices.md.txt +- https://docs.cloud.google.com/alloydb/docs/security-best-practices.md.txt + +## Backup and Disaster Recovery (DR) Service + +- https://docs.cloud.google.com/backup-disaster-recovery/docs/concepts/backup-plan-policy-best-practices.md.txt +- https://docs.cloud.google.com/backup-disaster-recovery/docs/concepts/best-practices-cyber-resilience.md.txt +- https://docs.cloud.google.com/backup-disaster-recovery/docs/concepts/best-practices-ransomware.md.txt +- https://docs.cloud.google.com/backup-disaster-recovery/docs/concepts/policy-specific-best-practices.md.txt +- https://docs.cloud.google.com/backup-disaster-recovery/docs/create-plan/schedule-best-practices-at-a-glance.md.txt + +## BigQuery + +- https://docs.cloud.google.com/bigquery/docs/best-practices-costs.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-for-multi-tenant-workloads-on-bigquery.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-performance-compute.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-performance-functions.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-performance-nested.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-performance-overview.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-policy-tags.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-row-level-security.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-spatial-analysis.md.txt +- https://docs.cloud.google.com/bigquery/docs/best-practices-storage.md.txt +- https://docs.cloud.google.com/bigquery/docs/graph-query-best-practices.md.txt +- https://docs.cloud.google.com/bigquery/docs/write-api-best-practices.md.txt + +## Cloud Armor + +- https://docs.cloud.google.com/armor/docs/best-practices.md.txt + +## Cloud Load Balancing + +- https://docs.cloud.google.com/load-balancing/docs/https/http-load-balancing-best-practices.md.txt + +## Cloud Run + +- https://docs.cloud.google.com/run/docs/configuring/jobs/gpu-best-practices.md.txt +- https://docs.cloud.google.com/run/docs/configuring/networking-best-practices.md.txt +- https://docs.cloud.google.com/run/docs/configuring/services/gpu-best-practices.md.txt +- https://docs.cloud.google.com/run/docs/configuring/workerpools/gpu-best-practices.md.txt +- https://docs.cloud.google.com/run/docs/tips/functions-best-practices.md.txt + +## Cloud Service Mesh + +- https://docs.cloud.google.com/service-mesh/docs/canonical-service-best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/istio-apis/security/best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/istio-apis/security/egress-gateways-best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/operate-and-maintain/scalability-best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/security/anthos-service-mesh-security-best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/security/best-practices.md.txt +- https://docs.cloud.google.com/service-mesh/docs/security/egress-gateways-best-practices.md.txt + +## Cloud SQL + +- https://docs.cloud.google.com/sql/docs/best-practices.md.txt +- https://docs.cloud.google.com/sql/docs/mysql/best-practices.md.txt +- https://docs.cloud.google.com/sql/docs/postgres/best-practices.md.txt +- https://docs.cloud.google.com/sql/docs/postgres/manage-memory-usage-best-practices.md.txt +- https://docs.cloud.google.com/sql/docs/sqlserver/best-practices.md.txt + +## Cloud Storage + +- https://docs.cloud.google.com/storage/docs/best-practices-media-workload.md.txt +- https://docs.cloud.google.com/storage/docs/best-practices.md.txt +- https://docs.cloud.google.com/storage/docs/hns-buckets-best-practices.md.txt + +## Compute Engine + +- https://docs.cloud.google.com/compute/docs/api/best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/connect/ssh-best-practices/auditing.md.txt +- https://docs.cloud.google.com/compute/docs/connect/ssh-best-practices/credentials.md.txt +- https://docs.cloud.google.com/compute/docs/connect/ssh-best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/connect/ssh-best-practices/login-access.md.txt +- https://docs.cloud.google.com/compute/docs/connect/ssh-best-practices/network-access.md.txt +- https://docs.cloud.google.com/compute/docs/disks/snapshot-best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/images/image-families-best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/images/image-management-best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/instances/best-practices-shared-reservations.md.txt +- https://docs.cloud.google.com/compute/docs/instances/sql-server/best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/instances/windows/best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/instances/windows/windows-best-practices.md.txt +- https://docs.cloud.google.com/compute/docs/nodes/sole-tenant-best-practices.md.txt + +## Gemini Enterprise Agent Platform + +- https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/best-practices.md.txt +- https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/gemini-image-generation-best-practices.md.txt +- https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/live-api/best-practices.md.txt +- https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/video/best-practice.md.txt + +## Google Kubernetes Engine (GKE) + +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/batch-platform-on-gke.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/enterprise-multitenancy.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/machine-learning/inference/autoscaling-tpu.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/machine-learning/inference/autoscaling.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/machine-learning/inference/batch-inference.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/machine-learning/inference.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/machine-learning/inference/llm-optimization.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/networking.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/optimize-ai-utilization.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/rbac.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/run-hpc.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/scalability.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/best-practices/upgrading-clusters.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/concepts/best-practices-continuous-integration-delivery-kubernetes.md.txt +- https://docs.cloud.google.com/kubernetes-engine/security/ai-security-best-practices.md.txt +- https://docs.cloud.google.com/kubernetes-engine/docs/how-to/hardening-your-cluster.md.txt + +## Identity and Access Management (IAM) + +- https://docs.cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys.md.txt +- https://docs.cloud.google.com/iam/docs/best-practices-for-using-service-accounts-in-deployment-pipelines.md.txt +- https://docs.cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation.md.txt +- https://docs.cloud.google.com/iam/docs/best-practices-service-accounts.md.txt +- https://docs.cloud.google.com/iam/docs/best-practices-workforce-identity-federation.md.txt +- https://docs.cloud.google.com/iam/docs/groups-best-practices.md.txt +- https://docs.cloud.google.com/iam/docs/pam-best-practices.md.txt + +## Managed Service for Apache Spark + +- https://docs.cloud.google.com/managed-spark/docs/concepts/security-best-practices.md.txt +- https://docs.cloud.google.com/managed-spark/docs/guides/best-practices.md.txt + +## Memorystore + +- https://docs.cloud.google.com/memorystore/docs/cluster/general-best-practices.md.txt +- https://docs.cloud.google.com/memorystore/docs/memcached/best-practices.md.txt +- https://docs.cloud.google.com/memorystore/docs/memcached/memory-management-best-practices.md.txt +- https://docs.cloud.google.com/memorystore/docs/redis/general-best-practices.md.txt +- https://docs.cloud.google.com/memorystore/docs/redis/memory-management-best-practices.md.txt +- https://docs.cloud.google.com/memorystore/docs/valkey/general-best-practices.md.txt + +## Migration + +- https://docs.cloud.google.com/migrate/containers/docs/planning-best-practices.md.txt +- https://docs.cloud.google.com/migrate/virtual-machines/docs/5.0/discover/migrating-vms-migrate-for-compute-engine-best-practices.md.txt + +## Network Connectivity + +- https://docs.cloud.google.com/network-connectivity/docs/interconnect/concepts/best-practices.md.txt +- https://docs.cloud.google.com/network-connectivity/docs/router/concepts/best-practices.md.txt +- https://docs.cloud.google.com/network-connectivity/docs/vpn/concepts/best-practices.md.txt + +## Observability in Google Cloud + +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/config.md.txt +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/ingest-and-query.md.txt +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/multi-tenant.md.txt +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/rule-alert-mgd.md.txt +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/rule-alert-self.md.txt +- https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/best-practices/unusual-configs.md.txt + +## Pub/Sub + +- https://docs.cloud.google.com/pubsub/docs/metrics-autoscaling-best-practices.md.txt +- https://docs.cloud.google.com/pubsub/docs/publish-best-practices.md.txt +- https://docs.cloud.google.com/pubsub/docs/subscribe-best-practices.md.txt + +## Security Command Center + +- https://docs.cloud.google.com/security-command-center/docs/cryptomining-detection-best-practices.md.txt + +## Security + +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/agents-applications.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/data-management.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/infrastructure.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/recommended-iam-groups.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/secure-enterprise-foundations.md.txt +- https://docs.cloud.google.com/docs/security/security-best-practices-catalog/tools-inference.md.txt + +## Spanner + +- https://docs.cloud.google.com/spanner/docs/best-practices-gaming-database.md.txt +- https://docs.cloud.google.com/spanner/docs/dml-best-practices.md.txt +- https://docs.cloud.google.com/spanner/docs/graph/algorithm-best-practices.md.txt +- https://docs.cloud.google.com/spanner/docs/graph/best-practices-designing-schema.md.txt +- https://docs.cloud.google.com/spanner/docs/graph/best-practices-tuning-queries.md.txt +- https://docs.cloud.google.com/spanner/docs/schema-updates-best-practices.md.txt +- https://docs.cloud.google.com/spanner/docs/sql-best-practices.md.txt +- https://docs.cloud.google.com/spanner/docs/vector-index-best-practices.md.txt +- https://docs.cloud.google.com/spanner/docs/vector-search-best-practices.md.txt + +## Vertex AI + +- https://docs.cloud.google.com/vertex-ai/docs/featurestore/best-practices.md.txt diff --git a/skills/vendor/google/google-cloud-solution-architecture/references/decision-making-guides.md b/skills/vendor/google/google-cloud-solution-architecture/references/decision-making-guides.md new file mode 100644 index 0000000..e13bbfb --- /dev/null +++ b/skills/vendor/google/google-cloud-solution-architecture/references/decision-making-guides.md @@ -0,0 +1,62 @@ +# Decision-making guides + +| Topic | Document | Description | +| :---- | :---- | :---- | +| Agentic AI: Architecture | https://docs.cloud.google.com/architecture/choose-agentic-ai-architecture-components.md.txt | Provides architectural guidance for selecting the optimal building blocks and services on Google Cloud to power your agentic AI applications. | +| Agentic AI: Design pattern | https://docs.cloud.google.com/architecture/choose-design-pattern-agentic-ai-system.md.txt | Helps you analyze your workload and select the best design pattern (single-agent, multi-agent, etc.) for constructing your generative AI system. | +| AlloyDB Omni: Deployment environment | https://docs.cloud.google.com/alloydb/omni/docs/choose-deployment.md.txt | Provides guidance on choosing the best target environment (single container, Kubernetes, or serverless) for deploying AlloyDB Omni. | +| AlloyDB: Connectivity | https://docs.cloud.google.com/alloydb/docs/choose-alloydb-connectivity.md.txt | Compares AlloyDB connectivity methods, including AlloyDB Auth Proxy, Private Service Connect (PSC), and direct VPC peering, to help you select the appropriate method. | +| AlloyDB: Machine types | https://docs.cloud.google.com/alloydb/docs/choose-machine-type.md.txt | Explains how to select the appropriate machine type for your AlloyDB primary and read instances based on vCPUs, memory, and performance. | +| AlloyDB: Vector index | https://docs.cloud.google.com/alloydb/docs/ai/choose-index-strategy.md.txt | Compares Approximate Nearest Neighbors (ANN) and K-Nearest Neighbors (KNN) indexing strategies to help you choose the appropriate model for vector search. | +| App Engine: Environment | https://docs.cloud.google.com/appengine/docs/the-appengine-environments.md.txt | Compares the App Engine Standard and Flexible environments, helping you select the appropriate environment based on language support, scaling speed, and customization requirements. | +| App Hub: Setup model | https://docs.cloud.google.com/app-hub/docs/set-up-app-hub.md.txt | Helps you select the best approach (single-project, multi-project, or organization-level) for setting up and configuring App Hub. | +| Application hosting | https://cloud.google.com/hosting-options | Compares application hosting (compute) options: Compute Engine, GKE, Cloud Run, App Engine | +| BigQuery: ETL vs. ELT | https://docs.cloud.google.com/bigquery/docs/load-transform-export-intro.md.txt | Describes the data integration approaches to load and transform data in BigQuery using the extract, load, and transform (ELT) or the extract, transform, load (ETL) processes. | +| BigQuery: Natural language processing function | https://docs.cloud.google.com/bigquery/docs/choose-ml-text-function.md.txt | Compares the capabilities of BigQuery ML text functions, such as AI.GENERATE\_TEXT, ML.TRANSLATE, and ML.UNDERSTAND\_TEXT, to help you choose between them. | +| BigQuery: Text generation function | https://docs.cloud.google.com/bigquery/docs/choose-text-generation-function.md.txt | Compares the different text generation options in BigQuery ML (such as using Gemini models vs. other LLMs) to select the appropriate fit. | +| Bigtable: SSD vs HDD | https://docs.cloud.google.com/bigtable/docs/choosing-ssd-hdd.md.txt | Compares the performance, cost, and use cases of SSD versus HDD storage to help you select the best disk layout for your Cloud Bigtable instances. | +| CDN products: Cloud CDN vs. Media CDN | https://docs.cloud.google.com/cdn/docs/choose-cdn-product.md.txt | Helps you select the best CDN product (Cloud CDN vs. Media CDN) based on your content delivery requirements and architecture. | +| Cloud Run: When to use | https://docs.cloud.google.com/run/docs/fit-for-run.md.txt | Provides a checklist and technical assessment guide to determine if your containerized application is well-suited for deployment on Cloud Run. | +| Cloud SQL for MySQL: Editions | https://docs.cloud.google.com/sql/docs/mysql/choose-edition.md.txt | Provides guidance on choosing between Enterprise and Enterprise Plus editions for Cloud SQL for MySQL. | +| Cloud SQL for MySQL: Machine series | https://docs.cloud.google.com/sql/docs/mysql/machine-series-overview.md.txt | Guides you in choosing the optimal machine family and series (general-purpose, memory-optimized, etc.) for your Cloud SQL for MySQL instances. | +| Cloud SQL for MySQL: Storage | https://docs.cloud.google.com/sql/docs/mysql/storage-options-overview.md.txt | Helps you select the best storage options (SSD vs. HDD, automatic storage increase) for Cloud SQL for MySQL databases based on IOPS and throughput needs. | +| Cloud SQL for MySQL: Region availability | https://docs.cloud.google.com/sql/docs/mysql/region-availability-overview.md.txt | Provides information on regional availability and feature support across Google Cloud regions for Cloud SQL for MySQL. | +| Cloud SQL for PostgreSQL: Editions | https://docs.cloud.google.com/sql/docs/postgres/choose-edition.md.txt | Provides guidance on choosing between Enterprise and Enterprise Plus editions for Cloud SQL for PostgreSQL. | +| Cloud SQL for PostgreSQL: Machine series | https://docs.cloud.google.com/sql/docs/postgres/machine-series-overview.md.txt | Guides you in choosing the optimal machine family and series (general-purpose, memory-optimized, etc.) for your Cloud SQL for PostgreSQL instances. | +| Cloud SQL for PostgreSQL: Region availability | https://docs.cloud.google.com/sql/docs/postgres/region-availability-overview.md.txt | Provides information on regional availability and feature support across Google Cloud regions for Cloud SQL for PostgreSQL. | +| Cloud SQL for PostgreSQL: Storage | https://docs.cloud.google.com/sql/docs/postgres/storage-options-overview.md.txt | Helps you select the best storage options (SSD vs. HDD, automatic storage increase) for Cloud SQL for PostgreSQL databases based on IOPS and throughput needs. | +| Cloud SQL for SQL Server: Editions | https://docs.cloud.google.com/sql/docs/sqlserver/choose-edition.md.txt | Provides guidance on choosing between Enterprise and Enterprise Plus editions for Cloud SQL for SQL Server. | +| Cloud SQL for SQL Server: Machine series | https://docs.cloud.google.com/sql/docs/sqlserver/machine-series-overview.md.txt | Guides you in choosing the optimal machine family and series (general-purpose, memory-optimized, etc.) for your Cloud SQL for SQL Server instances. | +| Cloud SQL for SQL Server: Region availability | https://docs.cloud.google.com/sql/docs/sqlserver/region-availability-overview.md.txt | Provides information on regional availability and feature support across Google Cloud regions for Cloud SQL for SQL Server. | +| Cloud SQL for SQL Server: Storage | https://docs.cloud.google.com/sql/docs/sqlserver/storage-options-overview.md.txt | Helps you select the best storage options (SSD vs. HDD, automatic storage increase) for Cloud SQL for SQL Server databases based on IOPS and throughput needs. | +| Cloud Storage: Bucket location | https://docs.cloud.google.com/storage/docs/locations.md.txt | Provides guidance to help you choose appropriate locations for Cloud Storage buckets. | +| Compute Engine: Migration path | https://docs.cloud.google.com/compute/docs/import.md.txt | Helps you evaluate and select the best migration strategy and toolset for migrating your virtual machine workloads into Compute Engine. | +| Compute Engine: Reservation type | https://docs.cloud.google.com/compute/docs/instances/choose-reservation-type.md.txt | Describes reservation types to help you decide how to reserve compute capacity for Compute Engine instances based on your workload needs. | +| Compute Engine: VM deployment strategy | https://docs.cloud.google.com/compute/docs/choose-compute-deployment-option.md.txt | Helps you select an appropriate VM deployment strategy on Compute Engine based on workload resilience, scalability, and cost requirements. | +| Compute Engine: Region selection | https://docs.cloud.google.com/solutions/best-practices-compute-engine-region-selection.md.txt | Describes the criteria that you should consider when you choose Google Cloud regions for your Compute Engine resources | +| Container runtimes | https://docs.cloud.google.com/architecture/select-managed-container-runtime-environment.md.txt | A selection guide comparing managed container options (GKE Autopilot vs. Cloud Run vs. App Engine Flexible) based on organizational and technical factors. | +| Container runtimes: GKE vs. Cloud Run | https://docs.cloud.google.com/kubernetes-engine/docs/concepts/gke-and-cloud-run.md.txt | Provides a comparison of GKE and Cloud Run and their advantages, and helps you find out if a single-platform or hybrid strategy will work for you. | +| Databases: Google Cloud database services | https://github.com/google/skills/blob/main/skills/cloud/cloud-databases-onboarding/references/recommendation_matrix.txt | Provides guidance to help you choose appropriate Google Cloud database services based on the requirements of your workload. | +| Eventarc: Advanced vs. Standard | https://docs.cloud.google.com/eventarc/standard/docs/choose-product-edition.md.txt | Compares the features, scalability, and event-routing models of Eventarc Standard and Eventarc Advanced to help you choose the appropriate edition. | +| Firestore: Native mode vs. Datastore mode | https://docs.cloud.google.com/datastore/docs/firestore-or-datastore.md.txt | Detailed guide comparing Firestore in Native mode versus Datastore mode, including features, scaling limits, and target use cases. | +| Gemini Enterprise Agent Platform: Serverless training method | https://docs.cloud.google.com/vertex-ai/docs/training/custom-training-methods.md.txt | Helps you compare custom training options in Agent Platform, such as custom jobs, hyperparameter tuning jobs, and training pipelines. | +| Gemini Enterprise Agent Platform: Training method | https://docs.cloud.google.com/vertex-ai/docs/start/training-methods.md.txt | Guides you in selecting the appropriate model training approach in Agent Platform, comparing AutoML, custom training, and BigQuery ML. | +| Gemini Enterprise Agent Platform: Vector database for RAG Engine | https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/vector-db-choices.md.txt | Describes and compare the vector database options that are supported on Agent Platform RAG Engine. | +| GKE: Cluster mode | https://docs.cloud.google.com/kubernetes-engine/docs/concepts/choose-cluster-mode.md.txt | Compares GKE Autopilot and Standard modes to help you decide which level of operational control and management is best for your cluster. | +| GKE: Multi-cluster load balancing API | https://docs.cloud.google.com/kubernetes-engine/docs/concepts/choose-mc-lb-api.md.txt | Compares Multi-Cluster Gateway versus Multi-Cluster Ingress to help you choose the correct multi-cluster load balancing approach for GKE. | +| GKE: Predefined ComputeClasses for Autopilot Pods | https://docs.cloud.google.com/kubernetes-engine/docs/how-to/autopilot-compute-classes.md.txt | Explains GKE Autopilot ComputeClasses (Balanced, Scale-Out, Performance) to help you choose the appropriate hardware profile for your containers. | +| Google Cloud Observability: Instrumentation strategy | https://docs.cloud.google.com/stackdriver/docs/instrumentation/choose-approach.md.txt | Guides you through the process of choosing a telemetry instrumentation strategy (such as OpenTelemetry vs. legacy agents) for Google Cloud Observability. | +| Load balancing | https://docs.cloud.google.com/load-balancing/docs/choosing-load-balancer.md.txt | Helps you choose the appropriate Google Cloud load balancer based on client location, protocol, and proxy requirements. | +| Looker: Hosting | https://docs.cloud.google.com/looker/docs/choosing-hosting-option.md.txt | Provides a comprehensive guide to selecting the optimal hosting model (Looker-hosted vs. customer-hosted) based on your requirements | +| Model inference on GKE: Load balancing strategy | https://docs.cloud.google.com/kubernetes-engine/docs/concepts/machine-learning/choose-lb-strategy.md.txt | Provides guidance on load balancing strategies for AI/ML inference workloads on Google Kubernetes Engine. | +| Network Connectivity | https://docs.cloud.google.com/network-connectivity/docs/how-to/choose-product.md.txt | Provides guidance to help you choose appropriate hybrid connectivity options: Cloud Interconnect, Cloud VPN, and Network Connectivity Center. | +| Pub/Sub vs. Cloud Managed Service for Apache Kafka | https://docs.cloud.google.com/pubsub/docs/choose-pubsub-kafka.md.txt | Compares serverless global Pub/Sub versus Google Cloud's Managed Service for Apache Kafka. | +| Pub/Sub vs. Cloud Tasks | https://docs.cloud.google.com/pubsub/docs/choosing-pubsub-or-cloud-tasks.md.txt | Describes the fundamental differences (implicit vs. explicit invocation) between Pub/Sub and Cloud Tasks. | +| Pub/Sub vs. Pub/Sub Lite | https://docs.cloud.google.com/pubsub/docs/choosing-pubsub-or-lite.md.txt | Helps you choose between standard Pub/Sub and Pub/Sub Lite based on budget, operations, and scale requirements. | +| Secret Manager: Replication policy | https://docs.cloud.google.com/secret-manager/docs/choosing-replication.md.txt | Compares automatic replication versus user-managed replication policies in Secret Manager to help you decide how to secure and distribute secrets. | +| Security Command Center: Security sources | https://docs.cloud.google.com/security-command-center/docs/concepts-security-sources.md.txt | Guides you on choosing and configuring security sources (built-in, Google-provided, and third-party) to integrate with Security Command Center. | +| Storage for AI and ML | https://docs.cloud.google.com/ai-hypercomputer/docs/storage.md.txt | Introduces and compares storage services in Google Cloud that can best help you optimize GPU or TPU performance and provides recommendations on the ideal service for specific AI and ML use cases. | +| Storage strategy | https://docs.cloud.google.com/architecture/storage-advisor.md.txt | Helps you understand and choose appropriate storage services for any workload. | +| VPC: Private access | https://docs.cloud.google.com/vpc/docs/private-access-options.md.txt | Compares different private access options on Google Cloud VPC, such as Private Google Access, Private Service Connect, and serverless VPC access. | +| Workflows vs. Application Integration | https://docs.cloud.google.com/workflows/docs/choose-app-integ-or-workflows.md.txt | Compares the capabilities and ideal scenarios for Google Cloud Workflows and Application Integration to help you choose the appropriate orchestration service. | +| Workflows vs. Managed Airflow for service orchestration | https://docs.cloud.google.com/workflows/docs/choose-orchestration.md.txt | Compares Workflows versus Managed Service for Apache Airflow (Cloud Composer) based on latency, scaling models, and language (YAML vs. Python). | \ No newline at end of file diff --git a/skills/vendor/google/google-cloud-waf-cost-optimization/SKILL.md b/skills/vendor/google/google-cloud-waf-cost-optimization/SKILL.md new file mode 100644 index 0000000..db88022 --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-cost-optimization/SKILL.md @@ -0,0 +1,179 @@ +--- +name: google-cloud-waf-cost-optimization +metadata: + category: WellArchitectedFramework +description: Generates cost optimization guidance for Google Cloud workloads based on the Google Cloud Well-Architected Framework (WAF). Use this skill to evaluate a workload, identify cost requirements and constraints, and provide actionable recommendations for build, deploy, and manage the workload cost-efficiently in Google Cloud. +--- + +# Google Cloud Well-Architected Framework skill for the Cost Optimization pillar + +## Overview + +The Cost Optimization pillar of the Google Cloud Well-Architected Framework +provides a structured approach to optimize the costs of your cloud workloads +while maximizing business value. Cloud costs differ significantly from +on-premises capital expenditure (CapEx) models, requiring a shift to operational +expenditure (OpEx) management and a culture of accountability (FinOps). +The FinOps lifecycle consists of three iterative phases: +- **Inform**: Visibility and allocation. Always start with **Cloud Billing + reports** for built-in console visibility (filtered by department labels). + Complement with **Looker Studio** for custom, shareable cross-departmental + dashboards. + +- **Optimize**: Rates and usage. Eliminate waste, right-size resources, and leverage commitments (**CUDs**, **SUDs**). +- **Operate**: Continuous improvement. Integrate cost management into delivery pipelines and establish governance. + +## Operational instructions + +- **Comprehensive First**: Always provide a complete list of standard recommendations/strategies relevant to the service or scenario mentioned. Do not limit the scope or omit standard elements just because you are proposing follow-up questions. +- **Full Conjunction**: When an instruction bundles multiple actions (e.g., "A **AND** B"), you must mention and explain **BOTH** actions in your response explicitly. +- **Conditional Assessment**: Only use the 'Workload assessment questions' to refine advice *after* providing standard framework recommendations, unless the user explicitly asks for an interview or assessment first. + +## Core principles + +The recommendations in the cost optimization pillar of the Well-Architected +Framework are aligned with the following core principles: + +- **Align cloud spending with business value**: Ensure that your cloud + resources deliver measurable business value by aligning IT spending with + business objectives. Prioritize investments that directly contribute to + revenue, customer satisfaction, or operational efficiency. Grounding + document: + https://docs.cloud.google.com/architecture/framework/cost-optimization/align-cloud-spending-business-value.md.txt + +- **Foster a culture of cost awareness**: Ensure that people across your + organization consider the cost impact of their decisions and activities. + Provide teams with the visibility and information they need to make informed, + cost-conscious choices. Grounding document: + https://docs.cloud.google.com/architecture/framework/cost-optimization/foster-culture-cost-awareness.md.txt + +- **Optimize resource usage**: Provision only the resources that you need and + pay only for what you consume. Select the most cost-effective resource types, + sizes, and locations that meet your technical and business requirements. + Grounding document: + https://docs.cloud.google.com/architecture/framework/cost-optimization/optimize-resource-usage.md.txt + +- **Optimize continuously**: Continuously monitor your cloud resource usage and + costs, and proactively make adjustments as needed to optimize your spending. + This iterative approach helps identify and address inefficiencies before they + become significant. Grounding document: + https://docs.cloud.google.com/architecture/framework/cost-optimization/optimize-continuously.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to cost optimization: + +- **Visibility and monitoring**: + + - **Cloud Billing reports**: Built-in dashboards for visualizing spending and + trends. **Essential for visibility within the console.** + - **BigQuery billing export**: Enables granular, custom analysis of billing + data using SQL and BI tools. + - **Looker Studio**: Used for creating detailed, shared cost dashboards and + reports. **Use alongside Cloud Billing reports for custom visual insights.** + - **Billing alerts and budgets**: Automated notifications when spending + reaches predefined thresholds. + - **Storage Insights**: Used to analyze Cloud Storage access patterns and identify + cost-saving opportunities. + +- **Automation and optimization tools**: + + - **Recommender / Active Assist**: Automatically identifies idle resources, + rightsizing opportunities, and unused commitments. + - **Cloud Hub Optimization**: Integrates billing and resource utilization data + to help developers and application owners quickly identify their most + expensive, fluctuating, or underutilized cloud resources. + - **FinOps hub**: Presents active savings and optimization opportunities in + one dashboard. + - **Billing quotas**: Limits on resource consumption to prevent unexpected + cost spikes. + +- **Efficient infrastructure**: + + - **Managed services and serverless services**: Services like Cloud Run, Cloud + Run functions, and GKE Autopilot reduce operational overhead and pay-per-use + scaling. + - **Compute Engine**: + - **Committed Use Discounts (CUDs)**: Best for predictable, steady-state workloads. + - **Spot VMs**: Best for fault-tolerant, interruptible, or unpredictable batch tasks. + - **Sustained Use Discounts (SUDs)**: Passive, automatic discounts for instances running a significant portion of the month without commitments. **Always mention this as a passive alternative or complement to CUDs.** + + - **Cloud Storage Lifecycle Policies**: Automated moves data to lower-cost + storage classes (Nearline, Coldline, Archive) based on age or access. + **Note**: Always recommend **Storage Insights** first to understand current + access patterns before defining lifecycle rules. + + - **Networking and Content Delivery**: + - **Location awareness**: Keep traffic within a single region where possible to avoid inter-region data transfer costs. + - **Cloud CDN**: Caches content to reduce data egress from the origin. + - **Network Service Tiers**: Offers **Standard Tier** as a lower-cost option compared to **Premium Tier** for latency-tolerant traffic. + - **Cloud Interconnect / Direct Peering**: Optimizes costs for high-volume data transfer to on-premises environments. **Note**: Always clarify hybrid connectivity options when discussing egress control, as on-premises sync is often a factor in multi-regional designs. + - **Managed Databases**: + - **Instance sizing**: Right-size CPU and memory based on Cloud Monitoring metrics. + - **High Availability (HA)**: Implement HA only for production environments to avoid doubling node costs for all environments. + - **Storage Optimization**: Optimize storage costs by managing backup retention policies **AND** explicitly identifying and deleting unused or idle resources (like unused and orphaned disks, expired snapshots, or idle instances). + + +- **Organization and governance**: + + - **Resource Manager**: Logical structure (Organizations, Folders, Projects) + for cost attribution. + - **Labels**: Metadata tags for categorizing and filtering costs by + environment, team, or application. + - **Organization Policy Service**: Enforces constraints (e.g., restricted + regions or machine types) to control costs. + +## Workload assessment questions + +Ask appropriate questions to understand the cost-related requirements and +constraints of the workload and the user's organization. Choose questions from +the following list: + +- How do you incorporate cost considerations into your cloud architecture design + process? +- How do you foster a culture of cost awareness among your development teams? +- How do you monitor and manage cloud costs across different projects or + departments? +- What strategies do you use to optimize the cost of your compute resources? +- How do you balance cost optimization with the need for agility and innovation? +- How do you ensure that you are not over-provisioning cloud resources? +- How do you use data and analytics to drive cost optimization decisions? +- How do you optimize costs in different environments (e.g., development, + testing, production)? +- How do you ensure that your cost optimization efforts are sustainable and + ongoing? +- How do you measure the success of your cloud cost optimization initiatives? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +cost-optimization recommendations: + +- **Cost Attribution**: 100% of resources are labeled with key metadata + (e.g., `env`, `team`, `app`). +- **Granular Visibility**: BigQuery billing export is enabled and used for + regular cost reviews. +- **Budgets and Alerts**: Every project or business unit has defined budgets + and active alerts. +- **Rightsizing**: Resources are regularly adjusted based on rightsizing + suggestions provided by Active Assist Recommender. +- **Commitment Strategy**: Spend is reviewed monthly to optimize Committed Use Discount (CUD) coverage. For non-committed workloads, verify if **Sustained Use Discounts (SUDs)** are being captured automatically. +- **Idle Resource Management**: Unused disks, IP addresses, and idle VMs are + identified and removed monthly. +- **Managed Services**: Serverless options are preferred for new workloads + unless specific technical constraints exist. +- **Storage Tiers**: Lifecycle policies are active for all major storage + buckets to minimize archival costs. Be aware of **retrieval fees** + associated with Nearline, Coldline and Archive storage classes. +- **Network Egress**: Data transfer is minimized by keeping traffic regional, + using **Cloud CDN**, and leveraging **Standard Network Tier** where + appropriate. High-volume on-premises traffic uses **Direct Peering** or + **Cloud Interconnect** (always verify if hybrid connectivity is involved). +- **Native Reporting**: **Cloud Billing reports** must be used for standard + views of spending trends in the console. +- **Custom Dashboards**: **Looker Studio** is used for advanced, shareable, and + customized reporting. + + + diff --git a/skills/vendor/google/google-cloud-waf-operational-excellence/SKILL.md b/skills/vendor/google/google-cloud-waf-operational-excellence/SKILL.md new file mode 100644 index 0000000..83cb7ac --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-operational-excellence/SKILL.md @@ -0,0 +1,149 @@ +--- +name: google-cloud-waf-operational-excellence +metadata: + category: WellArchitectedFramework +description: >- + Generates operations-focused guidance for Google Cloud workloads based on the + design principles and recommendations in the Operational Excellence pillar of + the Google Cloud Well-Architected Framework (WAF). Use this skill to evaluate + a workload, identify operational requirements, and provide actionable + recommendations for deployment, monitoring, and incident management. +--- + +# Google Cloud Well-Architected Framework skill for the Operational Excellence pillar + +## Overview + +The operational excellence pillar in the Google Cloud Well-Architected Framework +provides recommendations to operate workloads efficiently on Google Cloud. +Operational excellence in the cloud involves designing, implementing, and +managing cloud solutions that provide value, performance, security, and +reliability. The recommendations in this pillar help you to continuously improve +and adapt workloads to meet the dynamic and ever-evolving needs in the cloud. + +## Core principles + +The recommendations in the operational excellence pillar of the Well-Architected +Framework are aligned with the following core principles: + +- **Ensure operational readiness**: Define and measure criteria for a workload + to be considered ready for production, including staffing, processes, and + governance. Grounding document: + https://docs.cloud.google.com/architecture/framework/operational-excellence/operational-readiness-and-performance-using-cloudops.md.txt + +- **Manage incidents and problems**: Establish structured processes for + incident response, communication, and root cause analysis to minimize impact + and prevent recurrence. Grounding document: + https://docs.cloud.google.com/architecture/framework/operational-excellence/manage-incidents-and-problems.md.txt + +- **Manage and optimize cloud resources**: Monitor resource utilization and + right-size environments to maintain performance while ensuring operational + efficiency. Grounding document: + https://docs.cloud.google.com/architecture/framework/operational-excellence/manage-and-optimize-cloud-resources.md.txt + +- **Automate and manage change**: Use Infrastructure as Code (IaC) and CI/CD + pipelines to ensure consistent, repeatable, and low-risk deployments and + configuration changes. Grounding document: + https://docs.cloud.google.com/architecture/framework/operational-excellence/automate-and-manage-change.md.txt + +- **Continuously improve and innovate**: Regularly review architectures, + monitor industry trends, and adapt operations to meet evolving business + needs. Grounding document: + https://docs.cloud.google.com/architecture/framework/operational-excellence/continuously-improve-and-innovate.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to operational excellence: + +- **Observability and monitoring** + - **Cloud Monitoring**: Full-stack observability for Google Cloud and + hybrid environments. + - **Cloud Logging**: Real-time log management and analysis at scale. + - **Error Reporting**: Aggregates and displays errors for running cloud + services. + - **Service Monitoring**: Tools for defining and tracking Service Level + Objectives (SLOs). + +- **Automation and CI/CD** + - **Cloud Build**: Serverless platform for building, testing, and + deploying software. + - **Cloud Deploy**: Managed continuous delivery service for GKE, Cloud + Run, and GCE. + - **Terraform / Infrastructure Manager**: Managed service for + Infrastructure as Code (IaC) automation. + - **Artifact Registry**: Central repository for managing build artifacts + and container images. + +- **Resource management and optimization** + - **Recommender (Active Assist)**: Automatically identifies idle resources + and right-sizing opportunities. + - **Resource Manager**: Hierarchical management of resources across + organizations, folders, and projects. + +- **Incident response** + - **Incident response & management (IRM)**: Structured tools and processes + for managing operational disruptions. + +## Workload assessment questions + +Ask appropriate questions to understand operations-related requirements and +constraints of the workload and the user's organization. Choose questions from +the following list: + +- **Operational readiness and performance** + - How do you define and measure operational readiness for your cloud + workloads and what specific criteria or metrics do you use? + - Describe your process for defining, tracking, and achieving SLOs for + your critical workloads. + +- **Incident and problem management** + - Describe your incident management process, including roles, + responsibilities, and communication channels. + - How do you conduct post-incident reviews (PIRs) to identify root causes + and implement preventive measures? + +- **Resource management and optimization** + - How do you ensure that your cloud resources are right-sized for your + workloads, and what tools or techniques do you use? + +- **Change automation** + - Describe your change management process, including approval workflows, + testing procedures, and deployment strategies. + - How do you automate deployments, ensure their consistency and manage + configuration? + +- **Continuous improvement** + - How do you ensure that your cloud operations are continuously adapting + to meet evolving business needs and technological advancements? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +operational excellence recommendations: + +- **Operational readiness** + - [ ] A formal framework or set of criteria exists to assess operational + readiness before production deployment. + - [ ] Service Level Objectives (SLOs) are explicitly defined and monitored + using automated tools. + +- **Incident management** + - [ ] Incident response roles and communication channels are clearly + defined and documented. + - [ ] A structured, blameless post-mortem process is followed for all + major incidents. + +- **Change automation** + - [ ] All infrastructure changes are performed using Infrastructure as + Code (IaC) to ensure consistency. + - [ ] CI/CD pipelines are integrated with automated testing for all + deployment changes. + +- **Resource optimization** + - [ ] Resource utilization is regularly reviewed using recommendations + from Active Assist or performance data. + +- **Culture of improvement** + - [ ] A documented strategy is in place for regularly reviewing and + adapting cloud operations to industry advancements. diff --git a/skills/vendor/google/google-cloud-waf-performance-optimization/SKILL.md b/skills/vendor/google/google-cloud-waf-performance-optimization/SKILL.md new file mode 100644 index 0000000..35bfdf1 --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-performance-optimization/SKILL.md @@ -0,0 +1,149 @@ +--- +name: google-cloud-waf-performance-optimization +metadata: + category: WellArchitectedFramework +description: >- + Generates performance-focused guidance for Google Cloud workloads based on the + design principles and recommendations in the Performance Optimization pillar + of the Google Cloud Well-Architected Framework (WAF). Use this skill + to evaluate a workload, identify performance requirements, and provide + actionable recommendations for resource allocation, modular design, and + elasticity. +--- + +# Google Cloud Well-Architected Framework skill for the Performance Optimization pillar + +## Overview + +The Performance Optimization pillar of the Google Cloud Well-Architected +Framework provides principles and recommendations to help you design, build, and +operate high-performing workloads. It focuses on efficiently allocating +resources, leveraging modular architectures, and using data-driven insights to +continuously monitor and improve performance as your business needs evolve. + +## Core principles + +The recommendations in the performance optimization pillar of the +Well-Architected Framework are aligned with the following core principles: + +- **Plan resource allocation**: Carefully select and configure the compute, + storage, and networking resources that best match the specific requirements + of your workload. Grounding document: + https://docs.cloud.google.com/architecture/framework/performance-optimization/plan-resource-allocation.md.txt + +- **Take advantage of elasticity**: Utilize automated scaling and serverless + technologies to dynamically adjust resource capacity in response to + real-time demand fluctuations. Grounding document: + https://docs.cloud.google.com/architecture/framework/performance-optimization/elasticity.md.txt + +- **Promote modular design**: Architect systems using independent, loosely + coupled components to enhance scalability and allow individual parts to be + optimized without affecting the entire system. Grounding document: + https://docs.cloud.google.com/architecture/framework/performance-optimization/promote-modular-design.md.txt + +- **Continuously monitor and improve performance**: Implement robust + observability to identify bottlenecks and use performance data to drive + iterative enhancements throughout the software development lifecycle. + Grounding document: + https://docs.cloud.google.com/architecture/framework/performance-optimization/continuously-monitor-and-improve-performance.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to performance optimization: + +- **Compute and scaling** + - **Compute Engine (MIGs)**: Managed instance groups that support + autoscaling and load balancing for VM-based workloads. + - **Google Kubernetes Engine (GKE)**: Provides container orchestration + with horizontal and vertical pod autoscaling. + - **Cloud Run**: A fully managed serverless platform that automatically + scales containers to zero or up based on traffic. + +- **Data and caching** + - **Cloud CDN**: Low-latency content delivery network to cache static and + dynamic content closer to end-users. + - **Memorystore**: Managed in-memory data store for Valkey and Redis to + provide sub-millisecond data access. + - **Bigtable**: NoSQL database service for analytical and operational + workloads requiring low latency and high throughput. + - **Spanner**: RDBMS that provides global consistency, high availability, + and horizontal scaling for mission-critical transactional applications. + +- **Performance analysis and monitoring** + - **Cloud Trace**: Distributed tracing system that helps identify latency + bottlenecks. + - **Cloud Profiler**: Continuous CPU and memory profiling to identify + resource-heavy application code. + - **Cloud Monitoring**: Provides dashboards and alerts based on + performance KPIs like latency and throughput. + +## Workload assessment questions + +Ask appropriate questions to understand the performance-related requirements and +constraints of the workload and the user's organization. Choose questions from +the following list: + +- **Plan resource allocation** + - When initially provisioning compute resources for a new application, + which approach do you use to determine the required capacity for + expected peak loads? + - Which caching strategies (browser, in-memory, CDN, database) do you + utilize to improve performance and responsiveness? + - How do you optimize the performance of your data storage solutions + (e.g., SSD vs HDD, storage classes) for your applications? + +- **Promote modular design** + - Which architectural patterns (microservices, asynchronous messaging, + stateless servers) do you employ to enhance performance and resilience? + - How do you design your application to minimize the impact of failures in + one part of the system on other parts? + +- **Continuously monitor and improve performance** + - How frequently do you review and analyze the performance of your + production applications and infrastructure? + - Which tools or techniques (APM, distributed tracing, load testing) do + you use to proactively identify and diagnose performance bottlenecks? + - How do you incorporate performance considerations into your software + development lifecycle (SDLC)? + +- **Take advantage of elasticity** + - Which methods do you use to manage and optimize the cost of your cloud + resources while maintaining performance? + - How do you typically handle sudden spikes in traffic or workload on your + applications? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +performance optimization recommendations: + +- **Resource allocation** + - [ ] Initial provisioning is based on load testing or historical data + rather than general estimates. + - [ ] Caching is implemented at multiple layers (CDN, in-memory, or + browser) to offload backend systems. + - [ ] Storage types (SSD/HDD) and classes are selected based on the + specific I/O requirements of the workload. + +- **Modular design** + - [ ] The architecture uses microservices or decoupled components to allow + independent scaling. + - [ ] Circuit breakers or bulkheads are implemented to isolate failures + and prevent performance degradation across the system. + +- **Monitoring and continuous improvement** + - [ ] Automated dashboards and alerts are configured for key performance + indicators (KPIs). + - [ ] Distributed tracing and profiling tools are used to identify + code-level bottlenecks. + - [ ] Performance testing (unit and integration) is integrated into the + software development lifecycle. + +- **Elasticity** + - [ ] Auto-scaling rules are configured and validated to handle variable + demand. + - [ ] The architecture leverages serverless or managed services to + dynamically match capacity to load. + - [ ] Resource utilization is reviewed regularly to eliminate idle + overhead and balance cost with performance. diff --git a/skills/vendor/google/google-cloud-waf-reliability/SKILL.md b/skills/vendor/google/google-cloud-waf-reliability/SKILL.md new file mode 100644 index 0000000..f9d648b --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-reliability/SKILL.md @@ -0,0 +1,147 @@ +--- +name: google-cloud-waf-reliability +metadata: + category: WellArchitectedFramework +description: >- + Generates guidance for reliability, resilience, availability, redundancy, + fault-tolerance, and disaster recovery (DR) for Google Cloud workloads based + on the design principles and recommendations in the Google Cloud + Well-Architected Framework. Use when the user asks to evaluate, design, or + improve the reliability, resilience, availability, or disaster recovery + capabilities of Google Cloud workloads. +--- + +# Google Cloud Well-Architected Framework skill for the Reliability pillar + +## Overview + +The Reliability pillar of the Google Cloud Well-Architected Framework provides +principles and recommendations to help you design, deploy, and manage reliable, +resilient, and highly available workloads in Google Cloud. A reliable system +consistently performs its intended functions under defined conditions, is +resilient to failures, and recovers gracefully from disruptions, thereby +minimizing downtime, enhancing user experience, and ensuring data integrity. + +## Core principles + +The recommendations in the reliability pillar of the Well-Architected Framework +are aligned with the following core principles: + +- **Define reliability based on user-experience goals**: Measurement of + reliability should reflect the actual experience of the system's users rather + than merely relying on infrastructure metrics. Focus on outcomes that matter + most to users. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/define-reliability-based-on-user-experience-goals.md.txt + +- **Set realistic targets for reliability**: Determine appropriate Service + Level Objectives (SLOs) that balance the cost and complexity of maximizing + availability against business requirements. Provide guidance on defining + Service Level Objectives (SLOs) based on monitoring signals, error budgets, + and user experience goals. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/set-targets.md.txt + +- **Build highly available systems through resource redundancy**: Eliminate + single points of failure by duplicating critical components across zones and + regions to maintain operations during localized outages. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/build-highly-available-systems.md.txt + +- **Take advantage of horizontal scalability**: Design system architectures to + scale horizontally (adding more instances) to seamlessly accommodate load + fluctuations and improve overall fault tolerance. Incorporate proactive + capacity planning to monitor and adjust project quotas and resource + availability anticipating sudden load spikes. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/horizontal-scalability.md.txt + +- **Detect potential failures by using observability**: Implement thorough + monitoring, logging, and alerting systems to proactively detect, diagnose, + and address anomalies before they cause user-facing issues. Monitor the + golden signals (latency, traffic, errors, and saturation) and set up alerts + for when the signals cross specified thresholds. Use Cloud Monitoring to + build comprehensive dashboards for the golden signals. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/observability.md.txt + +- **Design for graceful degradation**: Architect systems to maintain critical + functionality, even if at reduced performance or with limited features, when + dependencies fail or the system experiences extreme stress. To avoid + cascading failures, recommend setting up alerts to detect failures early, + using the circuit-breaker pattern, handling timeouts effectively to release + blocked resources, utilizing retries with exponential backoff and jitter to + avoid overwhelming recovering backend systems, and returning custom error + responses or static fallback pages. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/graceful-degradation.md.txt + +- **Perform testing for recovery from failures**: Build confidence in system + resilience by continuously simulating failures and verifying the + effectiveness of automated and manual recovery procedures. Grounding + document: + https://docs.cloud.google.com/architecture/framework/reliability/perform-testing-for-recovery-from-failures.md.txt + +- **Perform testing for recovery from data loss**: Regularly test backup and + restore protocols to ensure rapid recovery from data corruption or loss, + remaining within the defined Recovery Time Objective (RTO) and Recovery Point + Objective (RPO). Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/perform-testing-for-recovery-from-data-loss.md.txt + +- **Conduct thorough postmortems**: Foster a blameless culture by investigating + outages comprehensively to understand root causes, followed by implementing + measures that prevent recurrence. Grounding document: + https://docs.cloud.google.com/architecture/framework/reliability/conduct-postmortems.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to reliability: + +- **Compute**: Compute Engine Managed Instance Groups (MIGs), Google Kubernetes + Engine (GKE), Cloud Run +- **Networking**: Cloud Load Balancing, Cloud CDN, Cloud DNS +- **Storage and databases**: Cloud Storage (multi-region), Cloud SQL High + Availability, Spanner, Filestore, Firestore +- **Operations**: Cloud Monitoring, Cloud Logging, Google Cloud Managed Service + for Prometheus +- **Disaster recovery**: Backup and DR Service, Filestore backups + +## Workload assessment questions + +Ask appropriate questions to understand the reliability-related requirements and +constraints of the workload and the user's organization. Choose questions from +the following list: + +- How does your organization define and measure the reliability of your systems + in relation to user experience? +- How does your organization approach setting reliability targets for your + services? +- What is your organization's strategy for ensuring high availability through + resource redundancy? +- How does your organization leverage horizontal scalability to maintain + performance and reliability? +- How does your organization utilize observability (metrics, logs, traces) to + gain insights and detect potential failures? +- How does your organization manage alerting based on observability data to + ensure timely responses to significant issues without causing alert fatigue? +- What measures does your organization take to ensure systems can gracefully + degrade during high load or partial failures? +- How frequently and comprehensively does your organization test for recovery + from system failures (e.g., regional failovers, release rollbacks)? +- What is your organization's approach to testing for recovery from data loss? +- How does your organization conduct and utilize postmortems after incidents? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +reliability recommendations: + +- User-focused SLIs and SLOs are explicitly defined and actively monitored. +- The architecture avoids single points of failure through cross-zone or + cross-region redundancy. +- Autoscaling is enabled to handle variable demand without manual intervention. +- Application and infrastructure health checks are configured to trigger + automated failovers. +- Regular backup schedules are in place, and restoration processes are routinely + tested. +- The system architecture incorporates patterns like circuit breakers, retries + with exponential backoff, and rate limiting to support graceful degradation. +- Game days or chaos engineering practices are regularly held to validate + failure recovery. +- A formalized, blameless postmortem process exists to ensure organizational + learning from operational incidents. diff --git a/skills/vendor/google/google-cloud-waf-security/SKILL.md b/skills/vendor/google/google-cloud-waf-security/SKILL.md new file mode 100644 index 0000000..650569c --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-security/SKILL.md @@ -0,0 +1,352 @@ +--- +name: google-cloud-waf-security +metadata: + category: WellArchitectedFramework +description: >- + Generates security-focused guidance for Google Cloud workloads based on the + design principles and recommendations in the Google Cloud Well-Architected + Framework (WAF). Use this skill to evaluate workloads, identify security + requirements, and provide actionable recommendations for IAM, network + security, data protection, and operational security. +--- + +# Google Cloud Well-Architected Framework skill for the Security pillar + +## Overview + +The security pillar of the Google Cloud Well-Architected Framework provides +design principles and best practices for building a robust security posture by +integrating security into every layer of the architecture for cloud workloads. +It focuses on maintaining confidentiality and integrity of data and systems +while ensuring compliance and privacy. It provides a structured approach to risk +management, threat defense, and identity control, enabling you to operate cloud +workloads securely and at scale. + +## Workflow + +When this skill is activated, follow these steps to evaluate and improve the +security posture of the specified Google Cloud workload: + +1. **Understand the context**: Ask targeted questions from the **Workload + assessment questions** list to gather information about the user's current + architecture, security requirements, and constraints. +2. **Analyze and identify gaps**: Evaluate the workload against the **Core + principles** and the **Validation checklist** to identify security + vulnerabilities, missing controls, or deviations from best practices. +3. **Formulate recommendations**: Provide actionable, prioritized guidance + based on the Google Cloud Well-Architected Framework. Recommend specific + products from **Relevant Google Cloud products** to address the identified + gaps. +4. **Explain the recommendations**: Align all recommendations with the + appropriate **Core principles** and state the benefits that each + recommendation provides. +5. **Iterate and refine**: Help the user adapt the recommendations to their + specific requirements and constraints. + +## Core principles + +The recommendations in the security pillar of the Well-Architected Framework are +aligned with the following core principles: + +- **Implement security by design**: Integrate cloud security and network + security considerations starting from the initial design phase of your + applications and infrastructure. Google Cloud provides architecture + blueprints and recommendations to help you apply this principle. Grounding + document: + https://docs.cloud.google.com/architecture/framework/security/implement-security-by-design.md.txt + +- **Implement zero trust**: Use a _never trust, always verify_ approach, where + access to resources is granted based on continuous verification of trust. + Google Cloud supports this principle through products like Chrome Enterprise + Premium, Identity-Aware Proxy (IAP) and IAM Recommender. Grounding document: + https://docs.cloud.google.com/architecture/framework/security/implement-zero-trust.md.txt + +- **Implement shift-left security**: Implement security controls early in the + software development lifecycle. Avoid security defects before system changes + are made. Detect and fix security bugs early, fast, and reliably after the + system changes are committed. Google Cloud supports this principle through + products like Cloud Build, Binary Authorization, and Artifact Registry. + Grounding document: + https://docs.cloud.google.com/architecture/framework/security/implement-shift-left-security.md.txt + +- **Implement preemptive cyber defense**: Adopt a proactive approach to + security by implementing robust fundamental measures like threat + intelligence. This approach helps you build a foundation for more effective + threat detection and response. Google Cloud's approach to layered security + controls aligns with this principle. Google Cloud supports this principle + through products like Security Command Center, Google Threat Intelligence, + and Google SecOps. Grounding document: + https://docs.cloud.google.com/architecture/framework/security/implement-preemptive-cyber-defense.md.txt + +- **Use AI securely and responsibly**: Develop and deploy AI systems in a + responsible and secure manner. The recommendations for this principle are + aligned with guidance in the AI and ML perspective of the Well-Architected + Framework and in Google's Secure AI Framework (SAIF). Grounding document: + https://docs.cloud.google.com/architecture/framework/security/use-ai-securely-and-responsibly.md.txt + +- **Use AI for security**: Use AI capabilities to improve your existing + security systems and processes through Gemini in Security and overall + platform-security capabilities. Use AI as a tool to increase the automation + of remedial work and ensure security hygiene to make other systems more + secure. Google Cloud supports this principle through products like Google + Threat Intelligence and Google SecOps. Grounding document: + https://docs.cloud.google.com/architecture/framework/security/use-ai-for-security.md.txt + +- **Meet regulatory, compliance, and privacy needs**: Adhere to + industry-specific regulations, compliance standards, and privacy + requirements. Google Cloud helps you meet these obligations through products + like Assured Workloads, Organization Policy Service, and our compliance + resource center. Grounding document: + https://docs.cloud.google.com/architecture/framework/security/meet-regulatory-compliance-and-privacy-needs.md.txt + +- **Shared responsibilities and shared fate on Google Cloud**: Understand that + Google is responsible for the security _of_ the cloud and you're responsible + for the security of your workloads _in_ the cloud. Recognize how this division + of responsibilities varies based on the workload type. Learn what Google does + to help ensure that security _of_ the cloud. Take appropriate actions to help + ensure that your workloads are secure _in_ the cloud. + Grounding document: https://docs.cloud.google.com/architecture/framework/security/shared-responsibility-shared-fate.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to security: + +- **Identity and access management** + + - **Cloud Identity**: Manage user lifecycles, authentication, and identity + federation. + - **Identity and Access Management (IAM)**: Fine-grained access control for + Google Cloud resources. + - **Identity-Aware Proxy (IAP)**: Secure access to applications without a VPN. + - **Chrome Enterprise Premium**: Endpoint security and context-aware access. + - **IAM Recommender**: Provide policy intelligence. + +- **Network security** + + - **Google Cloud Armor**: DDoS protection and Web Application Firewall (WAF). + - **VPC Service Controls**: Define security perimeters to prevent data + exfiltration. + - **Cloud Next-Generation Firewall (NGFW)**: Advanced threat protection for + network traffic. + - **Shared VPC**: Centralized network management across projects. + - **Cloud Interconnect and IPsec VPN**: Secure, private connectivity. + -**Private Service Connect**: Provide private access to managed services + +- **Data security** + + - **Cloud Key Management Service (KMS)**: Manage encryption keys. + - **Sensitive Data Protection (formerly Cloud DLP)**: Discover and redact + sensitive data. + - **Confidential Computing**: Encrypt data in use (memory). + +- **Security operations (SecOps)** + + - **Google SecOps (Chronicle)**: Threat detection and security analytics. + - **Security Command Center (SCC)**: Centralized vulnerability and threat + management. + - **Cloud Logging and Cloud Monitoring**: Visibility into system activity. + - **BigQuery**: Storing exported logs for analysis. + +- **Automation and supply chain** + + - **Cloud Build**: Secure CI/CD pipelines. + - **Artifact Analysis**: Vulnerability scanning for container images. + - **Binary Authorization**: Deploy-time policy enforcement. + - **Assured open source software**: Use secured OSS packages. + +## Workload assessment questions + +Ask appropriate questions to understand the security-related requirements and +constraints of the workload and the user's organization. Choose questions from +the following list: + +- **Security by design**: + + - How do you incorporate security considerations into your project's initial + planning and design phases? + - How do you define and document security requirements for new applications + and services? + - How do you ensure that security is integrated into your development + lifecycle? + - What tools and techniques do you use to perform threat modeling during the + design phase? + - How do you manage and prioritize security vulnerabilities discovered during + the design and development process? + - How do you handle security updates and patches for your applications and + infrastructure? + - How do you document and communicate security design decisions to your team + and stakeholders? + - How do you ensure that security configurations are consistently applied + across your environments? + - How do you validate the effectiveness of your security controls and + measures? + - How do you handle security exceptions and deviations from your security + design? + +- **Zero trust**: + + - How do you verify and authenticate users and devices accessing your Google + Cloud resources? + - How do you implement the principle of least privilege for access control? + - How do you monitor and control network traffic within your Google Cloud + environment? + - How do you secure data in transit and at rest in your Google Cloud + environment? + - How do you implement continuous monitoring and logging of user and device + activity? + - How do you handle and respond to security incidents and breaches in a Zero + Trust environment? + - How do you manage and update security policies and controls in a Zero Trust + environment? + - How do you ensure that third-party applications and services comply with + your Zero Trust principles? + - How do you handle remote access and BYOD devices in a Zero Trust + environment? + - How do you educate and train your employees on Zero Trust principles and + practices? + +- **Shift-left security**: + + - How do you integrate security testing into your development pipeline early + in the process? + - What types of security testing do you perform during the development phase? + - How do you provide developers with feedback on security vulnerabilities and + best practices? + - How do you empower developers to take ownership of security in their code? + - How do you ensure that security requirements are clearly defined and + communicated to developers? + - How do you measure the effectiveness of your Shift Left security + initiatives? + - How do you handle security dependencies and third-party libraries in your + code? + - How do you manage and update security configurations in your development + environment? + - How do you handle security exceptions and deviations from your security + policies in development? + - How do you promote a culture of security awareness and responsibility among + developers? + +- **Preemptive cyber defense**: + + - How do you proactively identify and mitigate potential security threats + before they impact your systems? + - What tools and techniques do you use for continuous security monitoring and + analysis? + - How do you respond to and remediate security alerts and incidents? + - How do you simulate and test your incident response plans? + - How do you stay up-to-date with the latest security threats and + vulnerabilities? + - How do you handle and mitigate DDoS attacks against your applications and + services? + - How do you protect your sensitive data from insider threats? + - How do you ensure that your security controls are effective against advanced + persistent threats (APTs)? + - How do you handle security vulnerabilities in your supply chain? + - How do you adapt your security posture to evolving threats and technologies? + +- **Security of AI workloads**: + + - How do you ensure the security of your AI models and data? + - How do you address potential biases and ethical concerns in your AI models? + - How do you protect your AI models from adversarial attacks and data + poisoning? + - How do you ensure the privacy of data used in your AI models? + - How do you explain and interpret the decisions made by your AI models? + - How do you manage and control access to your AI models and data? + - How do you ensure compliance with regulations and standards related to + AI and ML? + - How do you monitor and detect anomalies in the behavior of your AI models? + - How do you handle and respond to security incidents involving your AI + models? + - How do you educate and train your employees on the secure and responsible + use of AI and ML? + +- **AI for security**: + + - How do you leverage AI and ML to enhance your security posture? + - What types of AI models do you use for security purposes? + - How do you train and validate your AI models for security applications? + - How do you ensure the accuracy and reliability of AI-based security + systems? + - How do you handle false positives and false negatives from AI-based + security systems? + - How do you integrate AI-based security systems with your existing security + infrastructure? + - How do you manage and update your AI models for security applications? + - How do you explain and interpret the decisions made by your AI models for + security applications? + - How do you ensure the ethical and responsible use of AI and ML for security + purposes? + - How do you measure the effectiveness of AI and ML in improving your security + posture? + +- **Regulatory compliance and privacy**: + + - What regulatory compliance frameworks and privacy standards do you need to + adhere to? + - How do you assess and manage compliance risks in your Google Cloud + environment? + - How do you ensure the privacy of sensitive data stored and processed in + Google Cloud? + - How do you handle data subject requests (DSRs) related to privacy + regulations? + - How do you document and track compliance activities and evidence? + - How do you ensure that third-party vendors and partners comply with your + regulatory and privacy requirements? + - How do you handle data breaches and security incidents related to compliance + regulations? + - How do you stay up-to-date with changes in regulatory compliance and privacy + standards? + - How do you educate and train your employees on regulatory compliance and + privacy requirements? + - How do you demonstrate and prove compliance to auditors and regulators? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +security recommendations: + +- **Security by design**: + + - Are system components selected based on their security features and + hardening? + - Is defense-in-depth implemented at the network, host, and application + layers? + - Are safe libraries and application frameworks used to prevent common + vulnerabilities? + - Is a risk assessment performed using industry standards? + +- **Zero trust**: + + - Is Cloud Identity used as a centralized identity provider for managing user + lifecycles and federation? + - Is access control enforced based on user identity and context (device, + location)? + - Are private connectivity methods (Cloud Interconnect, VPN) used for internal + traffic? + - Are default networks disabled in all projects? + - Are VPC Service Controls perimeters established around sensitive data? + +- **Shift-left security**: + + - Is infrastructure provisioned using Infrastructure as Code + (e.g., Terraform)? + - Are automated security scans integrated into the CI/CD pipeline? + - Is there a process for scanning and patching vulnerabilities in + dependencies? + - Is Binary Authorization used to ensure only trusted images are deployed? + +- **Preemptive cyber defense**: + + - Is threat intelligence integrated into security operations? + - Is security logging enabled and centralized for all critical resources? + - Are automated responses configured for common security threats? + - Are defenses validated through periodic testing or red-teaming? + +- **AI security and governance**: + + - Are AI pipelines secured against tampering and data poisoning? + - Is differential privacy or data masking used for training data where + appropriate? + - Are Vertex Explainable AI and fairness indicators used for model governance? diff --git a/skills/vendor/google/google-cloud-waf-sustainability/SKILL.md b/skills/vendor/google/google-cloud-waf-sustainability/SKILL.md new file mode 100644 index 0000000..10362b8 --- /dev/null +++ b/skills/vendor/google/google-cloud-waf-sustainability/SKILL.md @@ -0,0 +1,253 @@ +--- +name: google-cloud-waf-sustainability +metadata: + category: WellArchitectedFramework +description: >- + Generates sustainability-focused guidance for Google Cloud workloads based on + the design principles and recommendations in the Google Cloud Well-Architected + Framework (WAF). Use this skill to evaluate a workload, identify environmental + impact requirements, and provide actionable recommendations to build, deploy, + and manage the workload sustainably in Google Cloud. +--- + +# Google Cloud Well-Architected Framework skill for the Sustainability pillar + +## Overview + +The Sustainability pillar of the Google Cloud Well-Architected Framework +provides principles and recommendations to help you minimize the environmental +impact of your cloud workloads. It focuses on a shared responsibility +model—Google optimizes the sustainability *of* the cloud, while customers +optimize sustainability *in* the cloud. By making informed decisions about +architecture, resource allocation, and region selection, you can significantly +reduce your carbon footprint and improve overall energy efficiency. + +## Core principles + +The recommendations in the sustainability pillar of the Well-Architected +Framework are aligned with the following core principles: + +- **Shared responsibility**: Define the boundaries of responsibility and + embrace a shared fate model, working with your cloud provider and partners + to achieve optimal environmental outcomes for the entire ecosystem. + Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability.md.txt + +- **Use regions that consume low-carbon energy**: Prioritize Google Cloud + regions with a high percentage of Carbon-Free Energy (CFE) and "Low CO2" + indicators to lower the gross carbon emissions of your deployments. + Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/low-carbon-regions.md.txt + +- **Optimize AI and ML workloads**: Maximize computations per watt by matching + algorithmic needs to specialized hardware (like TPUs) and applying + mathematical techniques to reduce computational complexity. Grounding + document: + https://docs.cloud.google.com/architecture/framework/sustainability/ai-ml-energy-efficiency.md.txt + +- **Optimize resource usage**: Eliminate energy waste by scaling resources to + zero when idle, rightsizing virtual machines, and prioritizing managed + services that dynamically match actual demand. Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/optimize-resource-usage.md.txt + +- **Develop energy-efficient software**: Design your applications to minimize + unnecessary CPU, memory, and network activity on both backend servers and + end-user devices by using event-driven logic and optimized assets. Grounding + document: + https://docs.cloud.google.com/architecture/framework/sustainability/energy-efficient-software.md.txt + +- **Optimize data and storage**: Reduce the environmental footprint of your + storage by implementing lifecycle management to archive cold data and + eliminating "dark data" that provides no business value. Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/optimize-storage.md.txt + +- **Continuously measure and improve**: Gain visibility into your carbon + emissions by analyzing granular data, identifying hotspots, and taking + proactive steps to remediate inefficiencies. Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/continuously-measure-improve.md.txt + +- **Promote a culture of sustainability**: Embed sustainability into your + organizational governance, connect technical decisions to environmental + goals, and ensure staff have the skills to implement green practices. + Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/culture.md.txt + +- **Align sustainability practices with industry guidelines**: Ensure that + your sustainability initiatives are aligned with industry guidelines for + measurement, reporting, and verification, such as W3C Web Sustainability + Guidelines, Green Software Foundation, and Greenhouse Gas Protocol. + Grounding document: + https://docs.cloud.google.com/architecture/framework/sustainability/industry-guidelines.md.txt + +## Relevant Google Cloud products + +The following are _examples_ of Google Cloud products and features that are +relevant to sustainability: + +- **Visibility and measurement**: + - **Carbon Footprint**: Provides dashboard visibility into greenhouse gas + emissions associated with Google Cloud usage. + - **BigQuery**: Analyzes exported Carbon Footprint data alongside billing + data to identify emission hotspots. + +- **Infrastructure and operations**: + - **Google Cloud Region Picker**: Helps weigh carbon footprint, cost, and + latency when selecting deployment locations. + - **Active Assist / Recommender**: Automatically identifies idle resources + and provides VM rightsizing recommendations to reduce waste. + - **Cloud Run / GKE Autopilot**: Fully managed compute environments that + optimize cluster usage and can scale to zero when idle. + - **Cloud Batch**: Optimizes the scheduling of batch jobs, allowing + execution during periods of high Carbon-Free Energy. + - **Spot VMs**: Utilizes unused data center capacity for fault-tolerant + workloads, improving overall hardware efficiency. + +- **Data and AI**: + - **Cloud Storage Lifecycle Management**: Automatically transitions older + data to lower-energy storage classes (Nearline, Coldline, Archive). + - **Cloud TPUs**: Specialized hardware optimized for the energy efficiency + of large-scale AI/ML matrix multiplications. + +## Workload assessment questions + +Ask appropriate questions to understand the sustainability-related requirements +and constraints of the workload and the user's organization. Choose questions +from the following list: + +- **Cloud sustainability**: + - How do you define the boundaries of sustainability responsibility + between your organization and your cloud provider? + - How do you leverage cloud capabilities and AI to drive sustainability + outcomes for your broader business operations? + - How does your cloud strategy account for the sustainability impact of + your partner ecosystem and multi-cloud environments? + +- **Use regions that consume low-carbon energy**: + - How do you incorporate carbon intensity into your Google Cloud region + selection strategy? + +- **Optimize AI and ML workloads**: + - How do you optimize the energy efficiency of your AI and machine + learning lifecycles? + +- **Optimize resource usage**: + - How do you ensure your infrastructure footprint dynamically matches + actual workload demand? + - How do you select and maintain the hardware types used for your cloud + workloads? + - What is your strategy for handling non-urgent or compute-intensive + background tasks? + - How do you balance the need for high availability and disaster recovery + with sustainability? + +- **Develop energy-efficient software**: + - How do you ensure your backend logic minimizes unnecessary CPU, memory, + and network activity? + - How do you manage the overall efficiency and maintenance of your + codebase for sustainability? + - How do you minimize the data volume and processing load that your + application places on end-user devices? + - How does your user experience (UX) design contribute to energy + efficiency for the end user? + +- **Optimize data and storage**: + - What process do you have for managing the environmental footprint of + your data and storage? + +- **Continuously measure and improve**: + - How do you analyze your carbon data to prioritize optimization efforts? + - How is sustainability measurement embedded into your organization’s + governance and culture? + - What is your current process for gaining visibility into your + cloud-related carbon emissions? + - What proactive steps do you take to remediate identified carbon + hotspots? + +- **Promote a culture of sustainability**: + - How do you connect individual technical decisions to the organization's + mission and hold teams accountable for results? + - How do you ensure your technical and business staff have the specific + skills required to implement sustainability practices? + +## Validation checklist + +Use the following checklist to evaluate the architecture's alignment with +sustainability recommendations: + +- **Cloud sustainability**: + - [ ] The organization embraces a shared responsibility and shared fate + model for sustainability. + - [ ] AI is used as a catalyst for profitability and resilience to + streamline operations, or sustainability is integrated into the design + process to create positive feedback loops. + - [ ] Collaborations with sustainable partners are prioritized and + multi-cloud data portability is leveraged, or internal practices align + with recognized global standards like the Green Software Foundation. + +- **Use regions that consume low-carbon energy**: + - [ ] A data-driven policy prioritizes regions with high Carbon-Free + Energy (CFE%) and "Low CO2" indicators, or the Google Cloud Region + Picker is actively used to balance carbon footprint with cost and + latency. + +- **Optimize AI and ML workloads**: + - [ ] Algorithmic needs are matched to specialized hardware (TPUs) to + maximize computations per watt, or mathematical techniques like model + compression and PEFT are applied to reduce computational complexity. + +- **Optimize resource usage**: + - [ ] Fully managed services that scale to zero when idle are utilized, or + Horizontal Pod Autoscaling (HPA) and Vertical Pod Autoscaling (VPA) are + used in GKE to prevent over-provisioning. + - [ ] A formal process exists to upgrade to the newest machine types for + improved performance-per-watt, or workloads are actively matched to + specialized machine families. + - [ ] Batch jobs are proactively scheduled to run during periods or in + regions with the highest proportion of CFE, or Spot VMs are utilized for + non-critical batch jobs. + - [ ] "Cold DR" or serverless failover is prioritized to ensure secondary + regions remain at zero energy consumption until an event occurs, or + Infrastructure as Code (IaC) is used to rapidly provision a recovery + environment only when needed. + +- **Develop energy-efficient software**: + - [ ] Resource-intensive busy loops or constant polling are replaced with + event-driven logic, or algorithms with optimal time complexity and data + structures are prioritized. + - [ ] The "Don't Repeat Yourself" (DRY) principle is adhered to with + regular refactoring, or intelligent caching (e.g., Memorystore) is + implemented with smart eviction policies. + - [ ] The download size of website products is measured and maintained + against a strict budget, or CI/CD pipelines automate the minimization + and compression of HTML, CSS, and JS files. + - [ ] Static sites or Progressive Web Apps (PWAs) are preferred for faster + loading, or DOM manipulation is minimized to reduce device power + consumption. + +- **Optimize data and storage**: + - [ ] Object Lifecycle Management is used to automatically move cold data + to Archive storage, or discovery techniques (e.g., Dataplex) are used to + identify and eliminate "dark data". + +- **Continuously measure and improve**: + - [ ] Carbon data is analyzed by project, region, and service to identify + gross emitters, or carbon data is joined with Billing data in BigQuery + to correlate cost and environmental impact. + - [ ] A formal GreenOps function defines accountability for carbon + reduction targets, or verified Carbon Footprint data from BigQuery + supports formal ESG disclosures. + - [ ] Applications are instrumented to measure the specific carbon + intensity of software features, or automated exports of Carbon Footprint + data to BigQuery are configured for deep analysis. + - [ ] The unattended project recommender and Active Assist are regularly + used to decommission idle resources, or proactive projects re-architect + hotspots by shifting workloads to low-carbon regions. + +- **Promote a culture of sustainability**: + - [ ] Abstract carbon metrics are transformed into tangible progress + indicators in annual reports, or sustainability is treated as a + first-class technical requirement (NFR) tied to KPIs and performance + reviews. + - [ ] Training tailored to specific job roles (e.g., developers on code + efficiency, FinOps on carbon unit economics) is provided, or teams are + formally trained to access and interpret carbon footprint data. diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/support.py b/tests/support.py new file mode 100644 index 0000000..d7eb91e --- /dev/null +++ b/tests/support.py @@ -0,0 +1,123 @@ +"""Scripted turns for a whole Execution of this agent's Workflow on its real roles.""" + +from __future__ import annotations + +import json +from typing import Any + +from execution_engine.adk.fake_runtime import Call + +from app.solution_architecture.workflow import ( + DEPENDENCY_GRAPH, + SAMPLE_DATA, + DeliverableKind, + sample_submission, +) + +K = DeliverableKind + +# A complete spec, small: the essential fields stated or left to the agent. +SPEC = """\ +metadata: + customer_case: bench +engagement: + kind: workload +intent: + statement: Accept webhooks and keep them for replay. +estate: + cloud_provider: gcp + mode: greenfield + regions: + primary: europe-west2 + data_residency: United Kingdom +compliance: + frameworks: [ISO27001] + data_classification: internal +workload: + users: + who: decide + count: decide + availability: + target: decide +cost: + monthly_budget: decide +""" +# The fields of SPEC that bind the design: each is carried by a requirement. +BINDING = [ + "estate.regions.primary", + "estate.data_residency", + "compliance.frameworks", + "compliance.data_classification", +] + + +def submission(kind: DeliverableKind, **files: str) -> Call: + call = sample_submission(kind) + return Call( + call.tool, {**call.args, "attachments": {**call.args["attachments"], **files}} + ) + + +def carrying(sources: list[str]) -> dict[str, list[Any]]: + """Turns for the Specialists along the Requirements chain in which one more + requirement, NFR-2, carries what the customer stated (`sources`), and a Check, + K-3, holds the design to it. From the Execution engine's tests.""" + requirements = json.loads(SAMPLE_DATA["requirements.json"]) + requirements.append( + { + "id": "NFR-2", + "kind": "non_functional", + "text": "The design honours what the customer stated.", + "conditions": ["Each stated choice is configured as stated."], + "from": sources, + } + ) + components = json.loads(SAMPLE_DATA["components.json"]) + components[0]["requirements"].append("NFR-2") + graph = json.loads(SAMPLE_DATA["target-architecture.json"]) + graph["checks"].append( + { + "id": "K-3", + "applies_to": "E-1", + "source": "NFR-2", + "statement": "the stated choices are configured", + } + ) + implementation = json.loads(SAMPLE_DATA["implementation.json"]) + implementation.append( + {"check": "K-3", "file": "terraform/main.tf", "address": "example.run"} + ) + verdicts = json.loads(SAMPLE_DATA["verdicts.json"]) + verdicts["checks"].append( + {"check": "K-3", "verdict": "pass", "evidence": "Configured as stated."} + ) + files = { + K.REQUIREMENTS: {"requirements.json": json.dumps(requirements)}, + K.TECHNICAL_DECOMPOSITION: {"components.json": json.dumps(components)}, + K.TARGET_ARCHITECTURE: {"target-architecture.json": json.dumps(graph)}, + K.DEPLOYMENT_GUIDANCE: {"implementation.json": json.dumps(implementation)}, + K.VALIDATION_RESULTS: {"verdicts.json": json.dumps(verdicts)}, + } + return { + DEPENDENCY_GRAPH[kind].specialist: [[submission(kind, **attached)]] + for kind, attached in files.items() + } + + +def whole_execution() -> dict[str, list[Any]]: + """Every Specialist submits once: the scope analyst SPEC, the Requirements chain + carrying its binding fields, the rest their samples.""" + turns: dict[str, list[Any]] = { + spec.specialist: [[sample_submission(kind)]] + for kind, spec in DEPENDENCY_GRAPH.items() + } + turns[DEPENDENCY_GRAPH[K.SCOPE].specialist] = [ + [submission(K.SCOPE, **{"scope.yaml": SPEC})] + ] + turns.update(carrying(BINDING)) + # The schema review reads the sample's placeholder resource types against the + # provider when Terraform is installed, and lets the run's next submission through. + architect = DEPENDENCY_GRAPH[K.TARGET_ARCHITECTURE].specialist + (only_turn,) = turns[architect] + turns[architect] = [only_turn * 2] + return turns diff --git a/tests/test_assembly.py b/tests/test_assembly.py new file mode 100644 index 0000000..21a9765 --- /dev/null +++ b/tests/test_assembly.py @@ -0,0 +1,84 @@ +"""The agent assembled from its own folder on the Execution engine: its role files, +its Skills and its provider bundle, with a scripted runtime in place of models.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from execution_engine.adk.fake_runtime import FakeAgentRuntime +from execution_engine.agent import open_assembly +from execution_engine.config import Settings +from execution_engine.recorder import InMemoryRecorder + +from app.main import ROOT +from app.solution_architecture.assembly import workflow_for +from app.solution_architecture.workflow import DEPENDENCY_GRAPH, WORKFLOW +from tests.support import SPEC, whole_execution + +CASE = "bench" + +# What the operating model agent digests of a completed architecture Execution. +DIGESTED = { + "components.json", + "products.json", + "recommendations.json", + "requirements.json", + "scope.json", + "target-architecture.json", + "verdicts.json", + "work-breakdown.json", +} + + +def settings(**overrides: Any) -> Settings: + values: dict[str, Any] = { + "CLOUD_PROVIDER": "gcp", + "CHECKPOINTER": "memory", + "MCP_ENABLED": False, + "LESSONS_ENABLED": False, + } + values.update(overrides) + return Settings(_env_file=None, **values) # type: ignore[call-arg] + + +def assembled(tmp_path: Path, runtime: FakeAgentRuntime, **overrides: Any) -> Any: + return open_assembly( + settings(**overrides), + workflow_for, + root=ROOT, + runtime=runtime, + recorder=InMemoryRecorder(), + output_root=tmp_path, + ) + + +async def test_every_role_the_workflow_names_has_its_file(tmp_path): + async with assembled(tmp_path, FakeAgentRuntime({})) as assembly: + roles = set(assembly.roles) + + assert {spec.specialist for spec in DEPENDENCY_GRAPH.values()} <= roles + assert {"orchestrator", "reply-writer"} <= roles + assert assembly.bundle.name == "gcp" + # The pillar advisors come from the provider bundle's pillar Skills. + assert assembly.engine.workflow.role_tools is not None + + +async def test_a_pre_approved_execution_delivers_what_the_operating_model_reads( + tmp_path, +): + async with assembled(tmp_path, FakeAgentRuntime(whole_execution())) as assembly: + result = await assembly.engine.start( + "Accept webhooks and keep them for replay.", + pre_approved=True, + customer_case=CASE, + scope=SPEC, + ) + + assert result.status == "completed", result.state.get("warnings") + out = tmp_path / "deliverables" / "cases" / CASE / "executions" + folder = next(out.iterdir()) + written = {path.name for path in folder.rglob("*.json")} + assert DIGESTED <= written + assert (folder / "execution.json").is_file() + assert (folder / WORKFLOW.final_file).is_file()