Files
gcp_solution_architecture_a…/app/tools/modules.py
Jonathan Boniface ef37f59bad feat: opt-in published Terraform modules from approved sources (iteration 8)
Infrastructure code is plain resources by default. An Execution may opt in
with terraform_modules; the deployment default is TERRAFORM_MODULES, off.

- A module is accepted only from the registry namespaces the provider bundle
  lists (terraform-google-modules), at one exact version. Any other source is
  refused before Terraform runs; until now nothing stopped generated code
  naming any source for terraform init to download.
- terraform_module looks up a module's inputs, outputs and submodules from
  the registry and says when it cannot be used with the pinned provider.
- skills/google-cloud-iac-modules: when a module fits, and four modules with
  examples a test validates against hashicorp/google 8.6.0.
- Opted in, the IaC author and validator get the Skill and the lookup. Not
  opted in, they get neither and a module block is refused in code.
- A Change request follows its Baseline. execution.json records the choice.
- case-07 runs case 03's request with modules opted into.

Azure (aztfm) and AWS (terraform-aws-modules) sources are recorded in the
plan for when those Cloud providers are added. No case has run with this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 22:09:29 +01:00

301 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 app.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)