nwarila-platform/terraform-proxmox-iso-manager-framework
GitHub: nwarila-platform/terraform-proxmox-iso-manager-framework
该模块通过 Git 跟踪的 SHA 锁定记录，以声明式方式管理 Proxmox VE 上安装 ISO 的下载、校验与生命周期，供 Packer 模板仓库安全消费。
Stars: 0 | Forks: 0
# terraform-proxmox-iso-manager-framework
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/ci.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/security.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/actions/workflows/codeql.yaml)
[](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework/releases)
[](https://docs.renovatebot.com/)
[](https://conventionalcommits.org)
[](LICENSE)
用于一项任务的 Terraform 子模块：通过包含 `url`、`sha256` 和 `filename` 的 Git 跟踪锁定记录来管理一个 Proxmox VE 安装程序 ISO。
该模块将该锁定记录转换为一个经过 SHA 校验的 Proxmox ISO 路径，例如
`cephFS:iso/Rocky-9.6-x86_64-dvd.iso`，Packer 模板仓库可以将其渲染为与
[`nwarila-platform/proxmox-packer-framework`](https://github.com/nwarila-platform/proxmox-packer-framework)
变量类型相匹配的 `boot_iso` 和 `additional_iso_files` pkrvars。
## 这展示了什么
该仓库将一个小型 Terraform 子模块视为一个生产级平台组件：
- 精确的 Terraform 和 provider 锁定
- 带有验证覆盖的类型化输入
- 基于模拟且无实际 Proxmox 依赖的 Terraform 测试
- 经过 SHA 校验的 ISO 生命周期管理
- 对未托管文件采取失败即拒绝（fail-closed）的行为
- 明确的威胁模型和模块不变量
- Diataxis 文档结构
- ADR 支持的设计决策
- 作为 `make ci` 一部分的 OPA 策略测试
- CI 安全扫描
- 发布证据工件
## 用法
```
provider "proxmox" {
endpoint = "https://proxmox.example.test:8006/"
# Configure credentials in the root consumer, not in this child module.
}
module "iso" {
source = "git::https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework.git//terraform?ref="
family = "rocky9"
iso_pin = {
url = "https://dl.rockylinux.org/pub/rocky/9.6/isos/x86_64/Rocky-9.6-x86_64-dvd.iso"
sha256 = "8ff2a47e2f3bfe442617fceb7ef289b7b1d2d0502089dbbd505d5368b2b3a90f"
filename = "Rocky-9.6-x86_64-dvd.iso"
}
node = "pve-node-01"
storage = "cephFS"
}
output "boot_iso" {
value = {
iso_checksum = "sha256:${module.iso.iso_sha256}"
iso_file = module.iso.iso_path
iso_urls = null
cd_label = null
index = 0
iso_download_pve = false
iso_storage_pool = null
iso_target_extension = null
iso_target_path = null
keep_cdrom_device = false
type = "scsi"
unmount = true
}
}
output "additional_iso_files" {
value = []
}
```
上述输出与
[`nwarila-platform/proxmox-packer-framework`](https://github.com/nwarila-platform/proxmox-packer-framework)
声明的 `boot_iso` 和 `additional_iso_files` 变量类型相匹配，旨在通过 `templatefile()` 和 `local_file` 渲染到一个自动加载的 `*.auto.pkrvars.hcl` 文件中。有关渲染模式，请参阅
[从 Packer 模板中使用](docs/how-to/use-from-a-packer-template.md)。
使用者必须将该模块锁定到某个发布标签并导入 `//terraform` 子目录。
具体的 Terraform 和 provider 锁定版本位于 [`terraform/versions.tf`](terraform/versions.tf) 中。
该模块会拒绝带有令牌、格式错误或携带凭证的 ISO URL，因为 Terraform 状态和输出不是存放 bearer token 的安全位置。
## 示例
| 示例 | 用途 |
| --- | --- |
| [`examples/minimal/`](examples/minimal/) | 最小有效模块调用 |
| [`examples/packer-consumer/`](examples/packer-consumer/) | 用于 Packer 变量的消费者形状输出 |
| [`examples/adoption-recovery/`](examples/adoption-recovery/) | 显式的未托管文件接管路径 |
## 本地验证
运行与 CI 相同的核心检查：
```
make ci
```
CI 目标会检查 Terraform 格式化、初始化、验证、测试、TFLint、生成的 Terraform 文档偏差、文档布局以及 OPA 策略测试。
## 质量控制
| 控制 | 证据 |
| --- | --- |
| Terraform 格式化、初始化、验证、测试、TFLint、文档偏差、文档布局以及 OPA 策略测试 | 运行 `make ci` 的 `CI` 工作流 |
| GitHub Actions 静态分析 | `CodeQL Analysis` 工作流 |
| 文件系统、IaC 和密钥扫描 | `Security Scan` 工作流 |
| OpenSSF 仓库安全态势检查 | `Scorecard` 工作流 |
| 模板和组织基线偏差 | `Template Sync` 和 `Org ADR Sync` 工作流 |
| SHA 锁定、精确锁定以及特权工作流安全 | `Repo Hygiene` 工作流 |
| 发布 PR、变更日志、标签和证据 | `Release` 工作流 |
| 依赖更新 PR | Renovate |
## 文档
- [从 Packer 模板仓库使用](docs/how-to/use-from-a-packer-template.md)
- [开发此模块](docs/how-to/develop-this-module.md)
- [审查发布证据](docs/how-to/review-release-evidence.md)
- [采用此模板](docs/how-to/adopt-this-template.md)
- [架构](docs/explanation/architecture.md)
- [测试策略](docs/explanation/testing-strategy.md)
- [威胁模型](docs/explanation/threat-model.md)
- [Terraform 参考](docs/reference/terraform.md)
- [发布门禁](docs/reference/release-gates.md)
- [模块不变量](docs/reference/invariants.md)
- [模板镜像契约](docs/reference/mirroring.md)
- [决策记录](docs/decision-records/README.md)
## 安全性
上游 ISO 源的完整性不在该模块的威胁模型范围内。使用者有责任从上游分发渠道获取可信的 SHA-256 值。有关边界和报告流程，请参阅继承的[组织安全策略](https://github.com/nwarila-platform/.github/blob/main/SECURITY.md)以及 [`docs/explanation/threat-model.md`](docs/explanation/threat-model.md)。
特定于仓库的贡献和安全策略文件位于此仓库中。在 GitHub 支持继承社区健康文件的地方，仍然可以从 `nwarila-platform/.github` 继承组织范围的默认设置。
## 许可证
[MIT](LICENSE)。
标签：ECS, Packer, Proxmox VE, Terraform, 自动化运维, 镜像管理