NWarila/terraform-framework-template
GitHub: NWarila/terraform-framework-template
一个零外部依赖的 Terraform 框架参考模板，通过合成 provider 系统演示了生产级基础设施代码的模式、验证流水线和 OPA 策略，供平台团队派生出真实云框架使用。
Stars: 0 | Forks: 0
# terraform-framework-template
用于构建 Terraform framework 仓库的参考模板：即平台团队用来派生出真实云框架的那种仓库。它提供了规范的模块结构、验证工具、OPA 策略以及发布凭证流水线，这样可以通过派生此模板来建立新框架，而不必手动拼凑每一个部分。
## 前置条件
在运行完整的本地检测之前，请安装 CI 使用的相同外部工具：
- Terraform CLI 1.15.1
- TFLint 0.62.0
- terraform-docs 0.23.0
- OPA 1.10.0
- shellcheck
- bats
## 快速入门
```
make help
make setup
python tools/verify.py ci
python tools/verify.py integration
```
`python tools/verify.py ci` 会运行格式化、init、validate、TFLint、测试、OPA 检查以及 terraform-docs 漂移检查。`python tools/verify.py integration` 会在 `.tmp/ci/integration/` 下从 `terraform/` 构建一个临时工作区，复制单环境示例，并针对该组装好的模块运行面向 Terraform 的检测。
## 演示的模式
| 模式 | 查看位置 |
| --- | --- |
| 使用 `optional(, )` 的必需和可选标量变量 | [`variables.tf`](terraform/variables.tf) 中的 `all_environments` |
| 自定义验证规则（`condition`/`error_message`） | [`variables.tf`](terraform/variables.tf)，`all_environments` 的验证 |
| 带有操作上下文描述的敏感变量 | [`variables.tf`](terraform/variables.tf) 中的 `variable "secret_seed"` |
| 带有嵌套可选项的对象列表巨型变量 | [`variables.tf`](terraform/variables.tf) 中的 `manifests`、`lifecycle_hooks` |
| 单一可选子对象（在 main.tf 中变为 splat-on-optional dynamic block） | [`variables.tf`](terraform/variables.tf) 中的 `rotation`、`certificate`、`pet` |
| 记录已省略/已计算字段的普通 HCL 注释 | 贯穿全文 |
| Data-source 注入模式 | [`data.tf`](terraform/data.tf) → [`locals.tf`](terraform/locals.tf) → [`main.tf`](terraform/main.tf) |
| 基于层的默认值（按环境覆盖会回退到 data-source 默认值） | [`locals.tf`](terraform/locals.tf)，参见 `retention_days` / `pet.length` |
| 扁平化的组合键 for_each 映射（嵌套 list-of-objects → 可迭代资源展开） | [`locals.tf`](terraform/locals.tf)，`manifests_flat`、`lifecycle_hooks_flat` |
| 通过在扁平化映射上使用 for_each 实现的迭代子资源 | [`main.tf`](terraform/main.tf) 中的 `local_file.manifest`、`null_resource.lifecycle_hook` |
| 用于条件资源创建的过滤 for_each（每个环境 0..1 个） | [`main.tf`](terraform/main.tf) 中的 `time_rotating.environment_rotation`、`tls_self_signed_cert.environment` |
| Splat-on-optional dynamic block（`each.value["foo"][*]`） | [`main.tf`](terraform/main.tf) 中的 `dynamic "subject"` block |
| 敏感输出处理 | [`outputs.tf`](terraform/outputs.tf) 中的 `environment_secrets`、`environment_certificates` |
| 汇总输出 | [`outputs.tf`](terraform/outputs.tf) 中的 `framework_summary` |
| 带有真实 `apply` + 输出断言的 `terraform test` | [`tests/synthetic_environments.tftest.hcl`](terraform/tests/synthetic_environments.tftest.hcl) |
| 使用 `expect_failures` 的验证拒绝测试 | 同一文件，运行 5+ 次 |
## 对齐 Packer 的风格
本框架遵循在 [`nwarila-platform/proxmox-terraform-framework`](https://github.com/nwarila-platform/proxmox-terraform-framework) 中确立的“对齐 Packer”风格：
| 文件 | 作用 |
| --- | --- |
| [`terraform/versions.tf`](terraform/versions.tf) | `required_version` + `required_providers`（根据 [ADR-template/0001](docs/decision-records/template/0001-pin-terraform-and-provider-versions-exactly.md) 进行精确锁定） |
| [`terraform/providers.tf`](terraform/providers.tf) | Provider 块。直接引用变量，无逻辑。 |
| [`terraform/backend.tf`](terraform/backend.tf) | 后端配置。此展示项目使用本地配置；真实框架可使用注释掉的 S3/GCS/azurerm/HCP 变体。 |
| [`terraform/data.tf`](terraform/data.tf) | 数据源。演示 data-source 注入模式。 |
| [`terraform/variables.tf`](terraform/variables.tf) | **大文件。** Provider 级别的扁平变量 + 每种托管资源类型的一个内置了 `optional(, )` 的巨型对象。 |
| [`terraform/locals.tf`](terraform/locals.tf) | 带有区域部分的单一 `locals { }` 块。将变量展开为键控映射；注入 data-source 值；将嵌套列表扁平化为组合键的 for_each 映射。 |
| [`terraform/main.tf`](terraform/main.tf) | **哑文件。** 纯粹的 `each.value["key"]` 查找 + dynamic block。无计算。 |
| [`terraform/outputs.tf`](terraform/outputs.tf) | 按环境组合的输出 + 敏感输出处理演示。 |
| [`terraform/tests/*.tftest.hcl`](terraform/tests/) | 实际针对合成 provider 运行 `apply` 并对输出进行断言的 `terraform test`。 |
## 这是什么，又不是什么
| | 本仓库 | 真实框架 |
| --- | --- | --- |
| 演示框架模式 | 是 | 是 |
| 管理真实的云 / SaaS 基础设施 | 否，设计如此 | 是 |
| 用作派生框架的规范参考 | 是 | 不适用 |
| 适合“直接使用我来部署东西” | 否 | 是 |
如果你想部署真实的基础设施，请使用像 [`nwarila-platform/proxmox-terraform-framework`](https://github.com/nwarila-platform/proxmox-terraform-framework) 这样的真实框架。**本仓库的职责是教授模式**，而不是执行工作。
## 新框架检查清单
对于派生自此模板的真实框架，请先编辑以下内容：
1. `README.md` 和特定仓库的文档。
2. `terraform/` 中的 provider/resource 实现。
3. `examples/` 和生成的 `docs/reference/terraform.md`。
4. `docs/decision-records/repo/` 中的本地决策。
5. 可选的发布层，仅当仓库发布带版本号的 release 时。
镜像规则位于 [`docs/reference/mirroring.md`](docs/reference/mirroring.md)。
## 规范化仓库接口
本仓库使用与 Terraform runner 模板相同的验证命令界面：
| 命令 | 目的 |
| --- | --- |
| `make lint` | 仓库本地静态检查：fmt、init、validate、TFLint、Python 工具、workflow YAML。 |
| `make policy` | OPA 策略测试，加上源码感知和计划感知的策略评估。 |
| `make docs-check` | terraform-docs 漂移检查，加上 Diátaxis/ADR 文档布局。 |
| `python tools/verify.py ci` | 仓库本地质量门禁。 |
| `python tools/verify.py integration` | 从 `terraform/` 和 `examples/` 组装的临时框架工作区。 |
| `python tools/verify.py verify` | 完整的本地验证：`ci` 加上 `integration`。 |
要查看框架针对更丰富输入的 apply 情况：
```
cp examples/multi-environment/terraform.tfvars.example terraform/terraform.tfvars
( cd terraform && terraform init && terraform apply )
# 检查生成的 state：
( cd terraform && terraform state list )
# 真实的 per-env 文件出现在 terraform/.synthetic-output/ 下
ls -la terraform/.synthetic-output/*/
```
## 状态后端
此展示项目根据 [ADR-template/0002](docs/decision-records/template/0002-keep-reference-framework-credential-free.md) 使用**本地后端**，以便示例在无需外部设置的情况下始终可以运行。生产框架应使用带有原生状态锁定的远程后端。请参阅 [`terraform/backend.tf`](terraform/backend.tf) 中被注释掉的变体，以获取规范的 S3、GCS、azurerm 和 HCP Terraform 配置。
## 折叠标记（`#region` / `#endregion`）
HCL 文件中全程使用 `#region ------ [ Title ] ----...---- #` / `#endregion --- [ Title ] ----...---- #` 标记。这些标记可被 [Explicit Folding](https://marketplace.visualstudio.com/items?itemName=zokugun.explicit-folding) VS Code 扩展识别，用于在长文件中进行导航。确切的 regex 格式是折叠规则匹配所必需的。
## 为什么是“什么都不做”
一个“什么都不做”的框架是最强大的模式展示，因为它具有**零混淆细节**。每一行 HCL 都是关于 Terraform 本身的——模块结构、变量形状、locals 组合、资源展开、dynamic block 模式——而不是关于理解 AWS S3 存储桶的含义或 Proxmox API 的工作原理。真实框架在此基础之上叠加了 provider 语义；而在 provider 语义发挥作用之前，这个基础必须正确。
选择合成 provider（`null`、`random`、`local`、`time`、`tls`）的原因是：
- 这五个都是官方的 HashiCorp provider，拥有极其稳定的 API（每年约零个破坏性更新）
- 这五个全部免费，全部可离线工作，全部生成真实的 `terraform.tfstate`
- 它们共同涵盖了每一种 dynamic-block 模式（迭代块、单一可选块、splat-on-optional、过滤 for_each）、敏感数据处理（私钥）以及时间驱动的资源生命周期（轮换）
## 许可证
MIT — 见 [LICENSE](LICENSE)。
标签：bats, EC2, ECS, HCL, IaC, OPA策略, PR验证, shellcheck, Terraform, terraform-docs, TFLint, tfstate, 云框架, 代码验证, 参考架构, 合成提供者, 安全策略, 平台团队, 平台工程, 开源框架, 持续集成, 提示词设计, 无外部依赖, 框架模板, 状态管理, 端到端测试, 逆向工具, 零成本