terraform-module-library

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Terraform Module Library (GCP)

Terraform模块库（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.

此工作区的GCP优先模块模式。模块涵盖：Cloud Run v2、Cloud SQL PostgreSQL、Artifact Registry、VPC + 私有服务、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

创建Terraform模块之前：
1. 加载terraform-skill以遵循命名规范和代码结构标准
2. 每个模块必须包含：main.tf、variables.tf、outputs.tf、versions.tf、README.md
3. 每个模块必须在tests/目录下使用原生terraform test（1.6+）搭配模拟提供程序编写测试
4. 敏感输出必须标记为sensitive = true
5. 调度terraform-specialist agent进行部署/配置 — 本技能仅用于模块编写

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+)

modules/
└── <module-name>/
    ├── main.tf              # 仅包含资源 — 无provider {}，无backend {}
    ├── variables.tf         # 所有输入需包含描述、类型和验证规则
    ├── outputs.tf           # 所有输出需包含描述和敏感标记
    ├── versions.tf          # required_version + required_providers
    ├── README.md            # 使用示例 + 变量/输出表格
    └── tests/
        └── main.tftest.hcl  # 使用mock_provider的原生terraform测试（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

你正在为哪个GCP资源构建模块？
    |
    +-- Cloud Run v2服务       -> 查看references/gcp-modules.md § Cloud Run
    +-- Cloud SQL（PostgreSQL）     -> 查看references/gcp-modules.md § Cloud SQL
    +-- Artifact Registry          -> 查看references/gcp-modules.md § Artifact Registry
    +-- VPC + 子网              -> 查看references/gcp-modules.md § VPC
    +-- Secret Manager             -> 查看references/gcp-modules.md § Secret Manager
    +-- Workload Identity Fed.     -> 查看references/gcp-modules.md § Workload Identity Federation

Reference Files

参考文件

File	Load When
`references/gcp-modules.md`	Writing or reviewing any GCP Terraform module — has full HCL for all 6 modules

文件	加载时机
`references/gcp-modules.md`	编写或审核任何GCP Terraform模块时 — 包含所有6个模块的完整HCL代码

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)

提交模块前需确认：

存在
```
versions.tf
```
，其中
```
google
```
提供程序固定为
```
~> 6.0
```
所有变量均声明了
```
description
```
和
```
type
```
所有敏感输出均标记为
```
sensitive = true
```
有状态资源（Cloud SQL、Artifact Registry）包含
```
deletion_protection
```
变量

tests/main.tftest.hcl

中包含至少一个使用

mock_provider "google"

的

command = apply

测试

```
README.md
```
包含使用示例、变量表格和输出表格
IAM成员和多实例资源使用
```
for_each
```
（而非
```
count
```
）
无硬编码的项目ID、区域或资源名称
Cloud Run的容器镜像设置
```
lifecycle.ignore_changes
```
（镜像由CI/CD管理，而非Terraform）
Cloud SQL设置
```
ipv4_enabled = false
```
（无公网IP）

Key Design Decisions

关键设计决策

Decision	Rationale
`lifecycle.ignore_changes = [image]` on Cloud Run	CI/CD updates the image; Terraform manages config/scaling only. Prevents Terraform drift on every deploy.
`ipv4_enabled = false` on Cloud SQL	No public IP; forces Cloud SQL Auth Proxy or private VPC access. Security baseline.
`random_password` + Secret Manager for DB	Never hardcode or commit passwords. Secret Manager is the source of truth.
`for_each` on IAM members	Stable resource addressing; `count` causes destroy/recreate when list reorders.
Cleanup policies on Artifact Registry	Prevents unbounded storage cost from accumulated untagged images.
WIF `attribute_condition` scoped to org	Prevents cross-org token impersonation.

决策	理由
Cloud Run设置 `lifecycle.ignore_changes = [image]`	镜像由CI/CD更新；Terraform仅管理配置/扩缩容。避免每次部署时出现Terraform漂移。
Cloud SQL设置 `ipv4_enabled = false`	无公网IP；强制使用Cloud SQL Auth Proxy或私有VPC访问。安全基线要求。
使用 `random_password` + Secret Manager管理数据库密码	绝不硬编码或提交密码。Secret Manager为可信数据源。
IAM成员使用 `for_each`	稳定的资源寻址； `count` 会在列表重排时导致资源销毁/重建。
Artifact Registry设置清理策略	避免因累积未标记镜像导致存储成本无限制增长。
WIF `attribute_condition` 限定在组织范围内	防止跨组织令牌冒充。

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

命名和测试规范：加载
```
terraform-skill
```
技能（优先加载）
GCP配置：调度
```
terraform-specialist
```
agent
配置工作流：
```
docs/workflows/cloud-run-terraform.md
```

模块开发工作流：

docs/workflows/terraform-module-development.md

部署后安全审核：调度
```
security-reviewer
```
agent