Terraform Module Library

Terraform Module Library (GCP)

GCP-primary module patterns for this workspace. Modules cover: Cloud Run v2, Cloud SQL PostgreSQL, Artifact Registry, VPC + Private Services, Secret Manager, Workload Identity Federation.

Iron Law

BEFORE creating a Terraform module:
1. Load terraform-skill for naming conventions and code structure standards
2. Every module MUST have: main.tf, variables.tf, outputs.tf, versions.tf, README.md
3. Every module MUST have tests in tests/ using native terraform test (1.6+) with mock providers
4. Sensitive outputs MUST be marked sensitive = true
5. Dispatch terraform-specialist agent to apply/provision — this skill is for authoring only

Standard Module Structure

modules/
└── <module-name>/
    ├── main.tf              # Resources only — no provider {}, no backend {}
    ├── variables.tf         # All inputs with description, type, validation
    ├── outputs.tf           # All outputs with description and sensitive flag
    ├── versions.tf          # required_version + required_providers
    ├── README.md            # Usage example + variable/output tables
    └── tests/
        └── main.tftest.hcl  # Native terraform test with mock_provider (1.7+)

Pattern Selector

Which GCP resource are you modularizing?
    |
    +-- Cloud Run v2 service       -> See references/gcp-modules.md § Cloud Run
    +-- Cloud SQL (PostgreSQL)     -> See references/gcp-modules.md § Cloud SQL
    +-- Artifact Registry          -> See references/gcp-modules.md § Artifact Registry
    +-- VPC + Subnets              -> See references/gcp-modules.md § VPC
    +-- Secret Manager             -> See references/gcp-modules.md § Secret Manager
    +-- Workload Identity Fed.     -> See references/gcp-modules.md § Workload Identity Federation

Reference Files

Module Authoring Checklist

Before submitting any module:

• versions.tf present with google provider pinned to ~> 6.0
• All variables have description and type declared
• All sensitive outputs marked sensitive = true
• deletion_protection variable present for stateful resources (Cloud SQL, Artifact Registry)
• Tests in tests/main.tftest.hcl with at least one command = apply using mock_provider "google"
• README.md has usage example, variable table, and output table
• for_each used (not count) for IAM members and multi-instance resources
• No hardcoded project IDs, regions, or resource names
• lifecycle.ignore_changes on container image for Cloud Run (CI/CD manages image, not Terraform)
• ipv4_enabled = false for Cloud SQL (no public IP)

Key Design Decisions

Cross-References

• Naming and testing conventions: Load terraform-skill skill (load it first)
• GCP provisioning: Dispatch terraform-specialist agent
• Provisioning workflow: docs/workflows/cloud-run-terraform.md
• Module development workflow: docs/workflows/terraform-module-development.md
• Security review post-apply: Dispatch security-reviewer agent