nwarila-platform/proxmox-terraform-framework

# proxmox-terraform-framework [](https://github.com/nwarila-platform/proxmox-terraform-framework/actions/workflows/ci.yaml) [](https://github.com/nwarila-platform/proxmox-terraform-framework/actions/workflows/pages.yaml) [](https://github.com/nwarila-platform/proxmox-terraform-framework/actions/workflows/security.yaml) [](https://github.com/pre-commit/pre-commit) [](https://conventionalcommits.org) [](LICENSE) [](https://www.terraform.io/) [](https://registry.terraform.io/providers/bpg/proxmox/latest) [](https://nwarila.github.io/proxmox-terraform-framework/) 一个用于管理 [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview) 基础设施的标准化、生产级 Terraform 框架。旨在实现可重复性、安全性和开发者效率——具有多层验证、自动文档和开箱即用的完整 CI/CD 集成。 ## 目录 - [概述](#overview) - [功能](#features) - [前置条件](#prerequisites) - [入门](#getting-started) - [项目结构](#project-structure) - [开发者工作流程](#developer-workflow) - [CI/CD 管道](#cicd-pipeline) - [配置](#configuration) - [贡献](#contributing) - [安全](#security) - [许可](#license) ## 概述 本框架为 Proxmox 基础设施即代码提供标准化基础。而不是临时脚本或一次性配置，它在开发生命周期的每个阶段强制执行一致的格式、验证输入和自动安全检查——从本地提交到 CI 管道。 **关键目标：** - **安全第一**——秘密检测、安全扫描和格式验证阻止不良提交 - **一致的开发者体验**——通过 devcontainer、pre-commit 钩子和 VSCode 任务使用相同的工具链 - **自动质量**——CI 验证每个推送；文档在提交时自动生成 - **专业级**——强制执行常规提交、语义版本控制和自动变更日志 ## 功能 | 类别 | 工具 | |---|---| | 格式化 | `terraform fmt`, `markdownlint`, `yamllint`, `.editorconfig` | | Linting | `tflint`（使用 bpg/proxmox 规则集） | | 安全 | `trivy`（HIGH/CRITICAL 配置错误 + CVEs），`gitleaks`（秘密检测） | | 文档 | `terraform-docs`（在提交时自动生成） | | 提交质量 | 通过 `conventional-pre-commit` 强制执行常规提交 | | CI/CD | GitHub Actions（跨平台：Linux bash + Windows PowerShell） | | 依赖管理 | Dependabot（GitHub Actions + Terraform 提供商，每日） | | 开发环境 | Devcontainer（Ubuntu 24.04，所有工具预安装） | ## 前置条件 | 工具 | 版本 | 目的 | |---|---|---| | [Terraform](https://developer.hashicorp.com/terraform/install) | `= 1.15.2` | 基础设施部署 | | [TFLint](https://github.com/terraform-linters/tflint) | `= 0.61.0` | Terraform 检查 | | [Trivy](https://github.com/aquasecurity/trivy) | 最新版 | 安全扫描 | | [terraform-docs](https://terraform-docs.io/) | `>= 0.19.0` | 文档生成 | | [pre-commit](https://pre-commit.com/) | `>= 4.0.0` | Git 钩子管理 | | [gitleaks](https://github.com/gitleaks/gitleaks) | `= 8.24.0` | 秘密检测 | ## 入门 ### 选项 A — Devcontainer（推荐） 在 VSCode 中打开，并在提示时选择 **在容器中重新打开**。所有必需的工具都已预安装。 ### 选项 B — 本地设置 **1. 克隆仓库** ``` git clone git@github.com:nwarila-platform/proxmox-terraform-framework.git cd proxmox-terraform-framework ``` **2. 安装 pre-commit 钩子** ``` pip install pre-commit pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type commit-msg ``` **3. 设置 Proxmox 凭据** ``` export TF_VAR_proxmox_hostname="your-proxmox-host" export TF_VAR_proxmox_api_token_id="your-token-id" export TF_VAR_proxmox_api_token_secret="your-token-secret" ``` **4. 初始化和验证** ``` cd terraform terraform init terraform validate ``` ## 项目结构 ``` proxmox-terraform-framework/ |-- .config/ # Linter and tool configuration |-- .devcontainer/ # VS Code devcontainer definition |-- .github/ | |-- actions/ # Local composite Terraform actions | `-- workflows/ | |-- ci.yaml # Local make ci validation | |-- security.yaml # Org security, CodeQL, and Scorecard callers | |-- template-sync.yaml # Drift-gate against the Terraform framework template | |-- repo-hygiene.yaml # Org repo-hygiene policy | |-- terraform.yaml # Self-hosted Terraform validation pipeline | `-- release-please.yaml # Automated releases and changelog |-- .vscode/ # VS Code workspace settings and tasks |-- docs/ | |-- explanation/ | |-- how-to/ | `-- reference/ | `-- terraform.md # Auto-generated by terraform-docs |-- examples/ # Usage examples |-- terraform/ # Core Terraform configuration |-- .editorconfig |-- .gitignore |-- .pre-commit-config.yaml |-- CHANGELOG.md `-- LICENSE ``` ## 开发者工作流程 所有质量门在每次提交和推送时通过 pre-commit 钩子自动运行。要手动运行它们： ``` # 运行所有钩子针对所有文件 pre-commit run --all-files # 运行特定的钩子 pre-commit run terraform_fmt --all-files pre-commit run gitleaks --all-files ``` ### VSCode 任务 `.vscode/tasks.json` 定义了一个 **完整验证** 任务（默认构建任务），它链接： 1. `terraform fmt --check` 2. `terraform init` 3. `terraform validate` 4. `tflint` 5. `trivy` 安全扫描 使用 `Ctrl+Shift+B` 运行它。 ## CI/CD 管道 ### CI (`ci.yaml`) 在拉取请求、合并队列、手动调度和推送至 `main` 时运行。 安装固定的工具链并运行 `make ci`。 ### Terraform 验证器 (`terraform.yaml`) 在 `.tf` 文件或工作流程本身更改时，在推送至 `main` 时触发。在 GitHub 主机 Ubuntu 上使用固定的 Terraform 工具链运行。 | 步骤 | 操作 | |---|---| | 检出 | `actions/checkout`（固定 SHA，不持久化凭据） | | 格式检查 | `terraform fmt -check -diff -recursive` | | 初始化 | `terraform init -backend=false` | | 验证 | `terraform validate` | ### Release Please (`release-please.yaml`) 在推送至 `main` 时触发。解析 [常规提交](https://www.conventionalcommits.org/)： - 自动提升语义版本 - 生成并维护 `CHANGELOG.md` - 创建带有发布说明的 GitHub 发布 ### 安全 (`security.yaml`) 运行模板对齐的安全调用者，该调用者委托给 org `reusable-iac-security`、`reusable-codeql` 和 `reusable-scorecard` 工作流程。 ## 配置 ### Terraform 提供商 框架使用 `bpg/proxmox` 提供商。身份验证基于 API 令牌： | 变量 | 描述 | |---|---| | `proxmox_hostname` | Proxmox VE 主机（FQDN 或 IP） | | `proxmox_api_token_id` | API 令牌 ID（`user@realm!token-name`） | | `proxmox_api_token_secret` | API 令牌密钥 UUID | ### 工具版本 所有工具版本都已固定。要更新： - **Terraform / provider**：编辑 `terraform/versions.tf` - **Pre-commit 钩子**：编辑 `.pre-commit-config.yaml`，然后运行 `pre-commit autoupdate` - **GitHub Actions**：由 Dependabot 自动管理 ## 贡献 请参阅继承的 [组织贡献指南](https://github.com/nwarila-platform/.github/blob/main/CONTRIBUTING.md)。所有提交都必须遵循 [常规提交](https://www.conventionalcommits.org/) 格式，由 pre-commit 钩子强制执行。 允许的提交类型：`feat`、`fix`、`ci`、`docs`、`refactor`、`test`、`chore`、`security` ## 安全 要报告漏洞，请参阅继承的 [组织安全策略](https://github.com/nwarila-platform/.github/blob/main/SECURITY.md)。不要公开创建问题。 ## 许可 [MIT](LICENSE) — 版权所有 2025 NWarila

标签：ECS, MIT 许可, Proxmox, Terraform, 云基础设施, 代码审查, 基础设施自动化, 多层验证, 开发者效率, 文档自动化, 模板化部署, 特权提升, 生产级框架, 自动化部署, 虚拟化