Files
gcp_solution_architecture_a…/.agents/plans/iter-08-terraform-modules/steps/step-1-to-5.md
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

4.7 KiB

Steps 1 to 5 — Implementation Detail

Built on 2026-10-09. No Execution has run with it.

1. Which modules

terraform.modules.namespaces in the provider bundle lists the registry namespaces a module may come from; for Google Cloud, terraform-google-modules. TerraformRunner.validate and .plan refuse, before Terraform runs:

  • a source that is not <allowed namespace>/<name>/<provider>, optionally with //path: so any Git or HTTP URL, a GitHub shorthand, a local path, or another namespace;
  • a version that is not one exact version;
  • a module written in .tf.json.

With no namespace listed every module call is refused. The evaluation's own validation uses the same list, and only for a case that opts in.

The source the owner gave is a GitHub organisation; the registry namespace of the same name is what Terraform is pointed at, because the registry serves a fixed archive for a version and terraform init needs no Git.

2. What a module accepts

terraform_module(source, version, find) reads the public Terraform registry: a module's or submodule's inputs (required first, with type and description), its outputs and its submodules. It compares the module's provider requirements with the versions the bundle pins and says "NOT USABLE" when they exclude it. Only allowed namespaces can be looked up. Answers are cached for the life of the process.

It makes one new outbound call, to registry.terraform.io, which terraform init already reaches.

3. The Skill

skills/google-cloud-iac-modules/: when to use a module (it is in the table, it replaces three or more dependent resources, and every Check on the Elements it covers can be met through an input), and four references with a validated example each.

For Module Version
VPC, subnets, firewall rules, Cloud NAT network, cloud-nat 18.3.1, 7.1.0
Cloud SQL for PostgreSQL on a private address sql-db//modules/postgresql, //modules/private_service_access 28.3.0
A Cloud Storage bucket with retention, lifecycle, encryption, grants cloud-storage//modules/simple_bucket 12.4.1
A key ring, keys and grants kms 4.2.1

tests/test_iac_modules.py runs each example through terraform validate with the patterns Skill's versions file, and checks that every module call is from an allowed namespace at the version the table gives. It needs the network and is skipped without it.

The Skill is named in the bundle under terraform.modules.skill, not among any role's Skills. See step 5 for who is given it.

4. Checks through a module

A Check stays worded about the resource. implementation.json gives the module and the input that meets it, such as module.database.ip_configuration.ipv4_enabled. When no input sets what a Check needs, the module does not fit and the resources are written directly. The validator reads the input's value and confirms with the lookup what it sets, or what its default is.

This is instruction, in the Skills and the two role files. Nothing in code verifies that a module input does what a Check says: that would need a plan against a real project.

5. Opt-in per Execution

Infrastructure code is plain resources unless the Execution opts in.

  • ExecutionEngine.start(terraform_modules=...): true, false, or unset. Unset, a Change request does as its Baseline did, and any other Execution takes TERRAFORM_MODULES (off). Opting in is refused when the provider's bundle lists no sources.
  • Callers: terraform_modules in the /generate body, in A2A message metadata, and on an evaluation case.
  • Opted in: the roles that carry the terraform_module tool (the IaC author and the validator) are given the modules Skill, and their context says terraform_modules: true.
  • Not opted in: those roles get neither the Skill nor the tool, and any module block is refused by terraform_validate and terraform_plan with a message saying to write the resources directly. The refusal is in code (MODULES_OPTED_IN in app/tools/modules.py, set when a Specialist starts), not only in instructions.
  • execution.json records terraform_modules.

Reference routing (iteration 5 step 8) does not choose within the modules Skill, because it is not among a role's Skills at start-up.

Known limits

  • Modules also bring providers the bundle does not pin (google-beta, random, null), at whatever version their constraints allow.
  • The schema review and the target architect's lookups still describe resources. A Check's wording is unaffected by whether a module later creates the resource.
  • A module version in the catalogue goes stale; nothing flags a newer one.

Tests: tests/tools/test_modules.py (24), tests/test_iac_modules.py (6), tests/execution/test_terraform_modules.py (7).