NWarila/terraform-runner-template
GitHub: NWarila/terraform-runner-template
一个面向 Terraform 运行器仓库的模板项目，通过分离框架与环境数据、提供 CI/CD 工作流、策略验证和漂移检测，实现多仓库基础设施部署的标准化治理。
Stars: 0 | Forks: 0
# terraform-runner-template
一个适用于消费框架的 Terraform 仓库模板：它们拥有数据（描述部署内容的输入项），但不拥有 Terraform 模块本身。使用它可以脚手架化一个新运行器仓库，并预先配置好 CI、策略、drift-gate 和发布证据。
一个仓库*群组*的严谨程度取决于其最薄弱的环节。按类型划分的模板系列将严谨性——工作流、策略、契约——集中到每种类型的一个位置，该类型的每个消费者都通过 SHA 引用它。当此处的标准得到改进时，每个运行器在下一次依赖项更新时都会获得该改进。当运行器发生偏离时，契约验证器会在下一次 PR 时捕获它。
## 快速入门
```
make help
make setup
python tools/verify.py ci
python tools/verify.py integration --framework-source ../terraform-framework-template/terraform
```
对于派生自此模板的实际运行器，请更新 `repos/public/`、私有清单源、`.github/workflows/pr-validation.yaml`、`.github/workflows/terraform-deploy.yaml`，以及 `docs/decision-records/repo/` 下的任何仓库本地决策。镜像规则位于 [`docs/reference/mirroring.md`](docs/reference/mirroring.md)；AWS 引导程序预期位于 [`docs/reference/aws-bootstrap-requirements.md`](docs/reference/aws-bootstrap-requirements.md)。
## 规范化仓库接口
此仓库使用与 Terraform 框架模板相同的验证命令界面：
| 命令 | 用途 |
| --- | --- |
| `make lint` | 仓库本地静态检查：Python 工具和工作流/契约 YAML。 |
| `make policy` | OPA 策略测试以及针对真实仓库文件的策略评估。 |
| `make docs-check` | Diátaxis/ADR 文档布局检查。 |
| `python tools/verify.py ci` | 仓库本地质量门禁。 |
| `python tools/verify.py integration` | 临时消费者工作区，由此运行器固件和框架检出组装而成。 |
| `python tools/verify.py verify` | 完整的本地验证：`ci` 加上 `integration`。 |
运行器集成默认预期框架模板位于此仓库旁边：
```
python tools/verify.py integration
# 或覆盖 framework module path
python tools/verify.py integration --framework-source ../terraform-framework-template/terraform
```
共享的 CI 线束位于 `tools/ci/` 中；运行器特定的固件位于 `fixtures/integration/basic/` 中。这反映了框架仓库的结构，同时保留了运行器不拥有顶级 `terraform/` 目录的规则。
## 此模板提供了什么
| 层面 | 机制 | 执行内容 |
| --- | --- | --- |
| 可复用验证 | [`reusable-terraform-validation.yaml`](.github/workflows/reusable-terraform-validation.yaml) (`mode: runner`) | 在 `framework_ref` 处检出框架，覆盖运行器数据，针对组装后的目录树运行框架质量门禁。 |
| 漂移门禁 | [`drift-gate.yaml`](.github/workflows/drift-gate.yaml) + [`baseline-manifest.json`](baseline-manifest.json) | 固定的 [`NWarila/drift-gate`](https://github.com/NWarila/drift-gate) 验证组织基线是否镜像至此处，并为消费者提供模板层级的清单，用于字节级相同的运行器脚手架文件。 |
| 契约验证器 | [`tools/check_template_contract.py`](tools/check_template_contract.py) | 运行器仓库所需的文件、路径和内容规则。 |
| 契约清单 | [`contract/runner-template-contract.yaml`](contract/runner-template-contract.yaml) | 单一的机器可读事实来源。 |
| 通用质量门禁 | `security.yaml`、可选的 `release.yaml` 和可复用工作流 | 安全工具是所需基线的一部分；发布工具适用于发布版本的仓库。 |
## 消费者如何采用此模板
每个消费运行器仓库从该模板继承标准化脚手架，然后将承载核心职责的调用者工作流固定到显式 SHA：
```
# .github/workflows/pr-validation.yaml
jobs:
validate:
uses: NWarila/terraform-runner-template/.github/workflows/reusable-terraform-validation.yaml@<40-char-sha>
with:
mode: runner
framework_repo: NWarila/terraform-framework-template
framework_ref:
overlay_paths: |
repos/public => terraform/repos/public
tests/fixtures/repos/private => terraform/repos/private
# ...tool versions...
```
```
# .github/workflows/terraform-deploy.yaml
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
jobs:
deploy:
permissions:
contents: read
id-token: write
uses: NWarila/terraform-framework-template/.github/workflows/reusable-terraform-deploy.yaml@<40-char-sha>
with:
framework_ref:
overlay_paths: |
repos/public => terraform/repos/public
backend_mode: s3
backend_key_prefix:
upload_plan_artifact: false
apply: true
secrets:
aws_role_arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
aws_region: ${{ secrets.AWS_REGION }}
backend_bucket: ${{ secrets.TF_BACKEND_BUCKET }}
```
当源是目录时，覆盖路径始终作为目录内容复制。为了可读性，可以接受尾部斜杠，但它没有单独的含义；`repos/public` 和 `repos/public/` 的行为是相同的。
Renovate 使 `uses:` SHA 和 `framework_ref` 输入保持最新。
运行器的 `pr-validation.yaml` 处理免凭证的 Pull Request 验证。运行器的 `terraform-deploy.yaml` 是受信任的部署路径：它使用来自已审查的输入和仓库或环境秘密的特定于仓库的 S3 后端和 OIDC 设置，调用框架的 `reusable-terraform-deploy.yaml`。
## 架构
此模板参与在 [`nwarila-platform/.github` ADR-0001](docs/decision-records/org/0001-use-architecture-decision-records.md) 中正式确立的三层 ADR 模型：
- **组织层** — ADR 适用于组合中的每个仓库，无论技术栈如何。镜像在 [`docs/decision-records/org/`](docs/decision-records/org/)，与 [`nwarila-platform/.github`](https://github.com/nwarila-platform/.github) 字节级相同。受 drift-gate 约束。
- **模板层** — ADR 适用于派生自此模板的每个 Terraform 运行器消费者。主副本位于 [`docs/decision-records/template/`](docs/decision-records/template/)；第一个 ADR 是 [`template/0001-pin-terraform-and-provider-versions-exactly.md`](docs/decision-records/template/0001-pin-terraform-and-provider-versions-exactly.md)。
- **仓库层** — 特定于某个消费者仓库的 ADR，位于该消费者的 [`docs/decision-records/repo/`](docs/decision-records/repo/)。
## 版本控制
Conventional Commits + release-please。消费者固定到提交 SHA（根据契约对它们强制执行的相同规则），并让 Renovate 推动固定版本向前更新。
标签：AWS, DPI, ECS, GitHub Actions, GitOps, IaC模板, OPA策略, Terraform, 仓储模板, 代码脚手架, 代码质量门禁, 发布证据, 开源框架, 持续集成, 模块化架构, 漂移检测, 漏洞利用检测, 特权提升, 环境配置, 自动化部署, 自动笔记, 逆向工具