nwarila-platform/proxmox-vm-terraform-framework

# proxmox-vm-terraform-framework [](https://github.com/nwarila-platform/proxmox-vm-terraform-framework/actions/workflows/pr-validation.yaml) [](https://github.com/nwarila-platform/proxmox-vm-terraform-framework/actions/workflows/pages.yaml) [](https://github.com/nwarila-platform/proxmox-vm-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-platform.github.io/proxmox-vm-terraform-framework/) 一个结构化、生产级的 Terraform 框架，用于管理 [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview) 基础设施。专为可重复性、安全性和开发效率而设计 —— 开箱即用地提供多层验证、自动化文档和完整的 CI/CD 集成。 ## 目录 - [概述](#overview) - [功能](#features) - [前置条件](#prerequisites) - [快速入门](#getting-started) - [项目结构](#project-structure) - [开发流程](#developer-workflow) - [CI/CD 流水线](#cicd-pipeline) - [配置](#configuration) - [贡献](#contributing) - [安全](#security) - [许可证](#license) ## 概述 该框架为 Proxmox 基础设施即代码提供了一个标准化的基础。它抛弃了临时的脚本或一次性的配置，而是在开发生命周期的每个阶段（从本地提交到 CI pipeline）强制执行一致的格式、经过验证的输入以及自动化的安全检查。 **主要目标：** - **安全第一** —— 密钥检测、安全扫描和格式验证会在错误的提交产生影响前将其拦截 - **一致的开发体验** —— 通过 devcontainer、pre-commit hooks 和 VSCode 任务提供统一的工具链 - **自动化质量** —— CI 会验证每一次推送；文档会在提交时自动生成 - **专业级别** —— 强制使用 Conventional Commits、语义化版本控制以及自动生成的更新日志 ## 功能 | 类别 | 工具 | |---|---| | 格式化 | `terraform fmt`、`markdownlint`、`yamllint`、`.editorconfig` | | Linting | `tflint`（针对 bpg/proxmox 模块的完整 Terraform 规则集） | | 安全 | `trivy`（HIGH/CRITICAL 级别的配置错误及 CVE）、`gitleaks`（密钥检测）、`zizmor`（GitHub Actions 安全态势） | | 文档 | `terraform-docs`（在提交时自动生成） | | 提交质量 | 通过 `conventional-pre-commit` 强制执行 Conventional Commits | | CI/CD | GitHub Actions 可复用的验证、安全、发布和文档工作流 | | 依赖管理 | Renovate（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.62.0` | Terraform linting | | [Trivy](https://github.com/aquasecurity/trivy) | 最新版 | 安全扫描 | | [terraform-docs](https://terraform-docs.io/) | `= 0.23.0` | 文档生成 | | [pre-commit](https://pre-commit.com/) | `>= 4.0.0` | Git hook 管理 | | [gitleaks](https://github.com/gitleaks/gitleaks) | `= 8.24.0` | 密钥检测 | ## 快速入门 ### 选项 A — Devcontainer（推荐） 在 VSCode 中打开，并在出现提示时选择 **在容器中重新打开**。所有必需的工具均已预装。 ### 选项 B — 本地设置 **1. 克隆仓库** ``` git clone git@github.com:nwarila-platform/proxmox-vm-terraform-framework.git cd proxmox-vm-terraform-framework ``` **2. 安装 pre-commit hooks** ``` 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-vm-terraform-framework/ |-- .config/ # Linter configuration | |-- .markdownlint.json # Markdown lint rules | `-- .yamllint.yaml # YAML lint rules |-- .devcontainer/ # VS Code devcontainer definition |-- .github/ | |-- ISSUE_TEMPLATE/ # Issue templates | |-- workflows/ # CI, release, docs, and security workflows | |-- CODEOWNERS | `-- PULL_REQUEST_TEMPLATE.md |-- .vscode/ # VS Code workspace settings and tasks |-- docs/ # MkDocs source and generated references |-- examples/ # Usage examples |-- policies/opa/ # OPA plan policies and tests |-- terraform/ # Core Terraform configuration and tests |-- tools/ # Documentation, version, and OPA helpers |-- .editorconfig |-- .gitignore |-- .pre-commit-config.yaml |-- .terraform-docs.yml # terraform-docs output config |-- .tflint.hcl # TFLint full Terraform ruleset |-- Makefile |-- CHANGELOG.md |-- CONTRIBUTING.md |-- LICENSE |-- SECURITY.md `-- SUPPORT.md ``` ## 开发流程 所有的质量检查门禁都会在每次提交和推送时通过 pre-commit hooks 自动运行。若要手动运行它们： ``` # 对所有文件运行所有 hooks pre-commit run --all-files # 运行特定的 hook 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 流水线 ### PR 验证 (`pr-validation.yaml`) 在推送到 `main`、pull request、合并队列以及手动分发时触发。 调用锁定了特定版本的 `NWarila/terraform-framework-template` 可复用验证 工作流，并使用该仓库的 Terraform、TFLint、terraform-docs 和 OPA 版本锁。 | 步骤 | 动作 | |---|---| | 验证 | `mode: full` 可复用 Terraform 验证 | ### Release Please (`release-please.yaml`) 在推送到 `main` 时触发。解析 [Conventional Commits](https://www.conventionalcommits.org/) 以实现： - 自动提升语义化版本 - 生成并维护 `CHANGELOG.md` - 创建带有发布说明的 GitHub release ### CodeQL (`codeql.yaml`) 每周进行 SAST 扫描，并在每次推送到 `main` 时触发。扫描安全漏洞和代码质量问题。 ## 配置 ### Terraform Provider 该框架使用 [`bpg/proxmox`](https://registry.terraform.io/providers/bpg/proxmox/latest) provider。身份验证基于 API token： | 变量 | 描述 | |---|---| | `proxmox_hostname` | Proxmox VE 主机（FQDN 或 IP） | | `proxmox_api_token_id` | API token ID（`user@realm!token-name`） | | `proxmox_api_token_secret` | API token secret UUID | ### 工具版本 所有工具版本均已锁定。如需更新： - **Terraform / provider**：编辑 `terraform/versions.tf` - **pre-commit hooks**：编辑 `.pre-commit-config.yaml`，然后运行 `pre-commit autoupdate` - **GitHub Actions**：由 Renovate 自动管理 ## 安全 如需报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。请勿创建公开的 issue。 ## 许可证 [MIT](LICENSE) — 版权所有 2025 NWarila

标签：ECS, LXC容器, Proxmox, Terraform, 自动化配置, 虚拟化, 运维工具