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 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 19:49:28 +01:00
commit c84dbdea20
127 changed files with 14672 additions and 0 deletions

View File

@@ -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/<name>/google`, with `//modules/<submodule>` 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.

View File

@@ -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]
}
```

View File

@@ -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}"
}
]
}
```

View File

@@ -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"]
}
}
```

View File

@@ -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 `"<region>/<subnet_name>"`.
- `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"
}
```