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 <noreply@anthropic.com>
300 lines
12 KiB
Python
300 lines
12 KiB
Python
"""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"<namespace>/<name>/<provider>: {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 <namespace>/<name>/<provider>, optionally with "
|
|
f"//modules/<submodule>. 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)
|