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>
This commit is contained in:
55
skills/google-cloud-iac-modules/SKILL.md
Normal file
55
skills/google-cloud-iac-modules/SKILL.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
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.
|
||||
- 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. A Check is not verifiable only when neither the code nor the module's documentation shows what the resource will get.
|
||||
102
skills/google-cloud-iac-modules/references/cloud-sql.md
Normal file
102
skills/google-cloud-iac-modules/references/cloud-sql.md
Normal 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]
|
||||
}
|
||||
```
|
||||
68
skills/google-cloud-iac-modules/references/cloud-storage.md
Normal file
68
skills/google-cloud-iac-modules/references/cloud-storage.md
Normal 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}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
54
skills/google-cloud-iac-modules/references/kms.md
Normal file
54
skills/google-cloud-iac-modules/references/kms.md
Normal 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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
68
skills/google-cloud-iac-modules/references/network.md
Normal file
68
skills/google-cloud-iac-modules/references/network.md
Normal 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"
|
||||
}
|
||||
```
|
||||
@@ -22,11 +22,14 @@ The files are your working copy: the files you wrote with `write_file`, or, when
|
||||
- `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. 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.
|
||||
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
|
||||
|
||||
|
||||
@@ -117,6 +117,8 @@ One entry per Check in the Target architecture, saying where the code satisfies
|
||||
]
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user