NWarila/proxmox-terraform-framework
GitHub: NWarila/proxmox-terraform-framework
一套开箱即用的生产级 Terraform 框架，用于标准化管理和自动化部署 Proxmox VE 虚拟化基础设施。
Stars: 0 | Forks: 0
# proxmox-terraform-framework
[](https://github.com/NWarili/proxmox-terraform-framework/actions/workflows/terraform.yaml)
[](https://github.com/NWarili/proxmox-terraform-framework/actions/workflows/pages.yaml)
[](https://github.com/NWarili/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/)
一个结构化、生产级的 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 规则集) |
| 安全 | `trivy` (HIGH/CRITICAL 配置错误 + CVEs), `gitleaks` (密钥检测) |
| 文档 | `terraform-docs` (提交时自动生成) |
| 提交质量 | 通过 `conventional-pre-commit` 强制执行 Conventional Commits |
| CI/CD | GitHub Actions (跨平台: Linux bash + Windows PowerShell) |
| 依赖管理 | Dependabot (GitHub Actions + Terraform providers, 每日) |
| 开发环境 | Devcontainer (Ubuntu 24.04, 预装所有工具) |
## 前置条件
| 工具 | 版本 | 用途 |
|---|---|---|
| [Terraform](https://developer.hashicorp.com/terraform/install) | `= 1.14.6` | 基础设施 Provisioning |
| [TFLint](https://github.com/terraform-linters/tflint) | `= 0.61.0` | Terraform linting |
| [Trivy](https://github.com/aquasecurity/trivy) | latest | 安全扫描 |
| [terraform-docs](https://terraform-docs.io/) | `>= 0.19.0` | 文档生成 |
| [pre-commit](https://pre-commit.com/) | `>= 4.0.0` | Git hook 管理 |
| [gitleaks](https://github.com/gitleaks/gitleaks) | `= 8.24.0` | 密钥检测 |
## 快速开始
### 选项 A — Devcontainer (推荐)
在 VSCode 中打开，并在提示时选择 **Reopen in Container**。所有必需工具均已预装。
### 选项 B — 本地设置
**1. 克隆仓库**
```
git clone git@github.com:NWarila/proxmox-terraform-framework.git
cd proxmox-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-terraform-framework/
├── .config/ # Linter & tool configurations
│ ├── .markdownlint.json # Markdown lint rules
│ ├── .terraform-docs.yml # terraform-docs output config
│ ├── .tflint.hcl # TFLint rules (bpg/proxmox ruleset)
│ └── .yamllint.yml # YAML lint rules
├── .devcontainer/ # VSCode devcontainer definition
├── .github/
│ ├── actions/
│ │ ├── terraform-bash/ # Composite action (Linux)
│ │ └── terraform-powershell/ # Composite action (Windows)
│ ├── ISSUE_TEMPLATE/ # Bug report & feature request templates
│ ├── workflows/
│ │ ├── terraform.yaml # Terraform validation pipeline
│ │ ├── release-please.yaml # Automated releases & changelog
│ │ └── codeql.yaml # SAST security scanning
│ ├── CODEOWNERS
│ ├── dependabot.yml
│ └── pull_request_template.md
├── .vscode/ # VSCode workspace settings & tasks
├── docs/
│ └── TERRAFORM.md # Auto-generated by terraform-docs
├── examples/ # Usage examples
├── terraform/ # Core Terraform configuration
│ ├── backend.tf
│ ├── data.tf
│ ├── locals.tf
│ ├── outputs.tf
│ ├── providers.tf
│ ├── resources.tf
│ ├── variables.tf
│ └── versions.tf
├── .editorconfig
├── .gitignore
├── .pre-commit.config.yaml
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── SECURITY.md
└── SUPPORT.md
```
## 开发者工作流
所有质量关卡 (quality gates) 均通过 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` 定义了一个 **Full Validation** 任务 (默认构建任务)，该任务依次执行：
1. `terraform fmt --check`
2. `terraform init`
3. `terraform validate`
4. `tflint`
5. `trivy` 安全扫描
使用 `Ctrl+Shift+B` 运行。
## CI/CD 流水线
### Terraform Validator (`terraform.yaml`)
当 `.tf` 文件或工作流本身发生变更时，推送到 `main` 分支会触发此流程。在自托管 runners 上运行 (支持 Linux 和 Windows)。
| 步骤 | 动作 |
|---|---|
| Checkout | `actions/checkout` (固定 SHA, 不保留凭证) |
| 格式检查 | `terraform fmt -check -diff -recursive` |
| 初始化 | `terraform init -backend=false` |
| 验证 | `terraform validate` |
### Release Please (`release-please.yaml`)
推送到 `main` 时触发。解析 [Conventional Commits](https://www.conventionalcommits.org/) 以：
- 自动提升语义版本
- 生成并维护 `CHANGELOG.md`
- 创建包含发布说明的 GitHub releases
### 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**: 由 Dependabot 自动管理
## 贡献指南
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。所有提交必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式 —— 由 pre-commit hooks 强制执行。
允许的提交类型：`feat`, `fix`, `ci`, `docs`, `refactor`, `test`, `chore`, `security`
## 安全
如需报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。请勿公开提交 issue。
## 许可证
[MIT](LICENSE) — 版权所有 2025 NWarila
标签：bpg/proxmox, EC2, ECS, IaC, Packer, Proxmox VE, Terraform, 代码化管理, 基础设施自动化, 提示注入, 特权提升, 生产就绪, 私有云, 自动化部署, 虚拟化, 虚拟机模板, 集群管理