nwarila-platform/proxmox-packer-framework
GitHub: nwarila-platform/proxmox-packer-framework
Proxmox Packer框架，用于构建加固的Linux虚拟机模板。
Stars: 0 | Forks: 0
# Proxmox Packer 框架
[](https://github.com/nwarila-platform/proxmox-packer-framework/actions/workflows/main-validation.yml)
[](https://github.com/nwarila-platform/proxmox-packer-framework/actions/workflows/security.yaml)
[](https://github.com/nwarila-platform/proxmox-packer-framework/releases)
[](LICENSE)
一个数据驱动的 [Packer](https://www.packer.io/) 框架，用于构建加固的 Proxmox VE 虚拟机模板。该框架拥有 Proxmox 构建器合约、标准化层和 CI 验证流程。消费者仓库提供自己的安装模板、Ansible 内容和环境特定值。
## 目的
这个仓库是一个组织框架，而不是一个现成的镜像工厂。其任务是给下游仓库提供一个稳定、可重用的 Proxmox/Packer 合约，以便团队继承：
- 安全的基础设施默认值
- 共享的输入模式
- 一致的验证和 CI 行为
- 框架逻辑和消费者内容之间的清晰分离
框架不决定虚拟机操作系统应该包含哪些软件包、加固配置文件或应用程序堆栈。这些决定留给了消费者仓库。
## 所有权模型
| 层 | 所有者 | 默认源 |
|-------|-------|----------------|
| Packer 协调和变量合约 | 本框架 | 本仓库 |
| ISO 下载和 Proxmox 存储上的 SHA 验证 | [terraform-proxmox-iso-manager-framework](https://github.com/nwarila-platform/terraform-proxmox-iso-manager-framework) | 运行器仓库的 Terraform |
| OS 安装模板 | 消费者仓库 | `examples/packer/` 中的已发货安装示例 |
| Ansible 角色、剧本、Galaxy 要求 | 消费者仓库 | [ansible-framework](https://github.com/nwarila-platform/ansible-framework) |
本仓库仅提供安装示例。它不提供 Ansible 角色、剧本、清单或 `ansible.cfg`；消费者从 [ansible-framework](https://github.com/nwarila-platform/ansible-framework) 或等效仓库导入这些内容。
ISO 生命周期由外部拥有。运行器仓库调用 `terraform-proxmox-iso-manager-framework` 下载并 SHA-256 验证引导 ISO 到 Proxmox 存储，然后通过其 `var_file` 输入生成 `boot_iso` pkrvars 文件，由本框架的可重用工作流程使用。请参阅 [docs/explanation/architecture.md](docs/explanation/architecture.md#iso-lifecycle-boundary)。
## 架构
从高层次来看：
1. 消费者 `.pkrvars.hcl` 文件提供环境特定输入。
2. `packer/locals.pkr.hcl` 标准化这些输入并组装安装模板合约。
3. `packer/source.pkr.hcl` 将标准化值映射到 Proxmox ISO 构建器。
4. `packer/builds.pkr.hcl` 运行消费者提供的安装模板，然后运行消费者提供的 Ansible 剧本。
请参阅 [docs/explanation/architecture.md](docs/explanation/architecture.md) 了解设计决策，以及 [docs/reference/template-contract.md](docs/reference/template-contract.md) 了解模板变量合约。
## 支持的操作系统
| OS | 版本 | 安装方法 | 示例 | 状态 |
|----|---------|----------------|---------|--------|
| Rocky Linux | 9.x | Kickstart | [examples/packer/rocky-linux-9/](examples/packer/rocky-linux-9/) | 验证过的示例 |
| Ubuntu Server | 24.04 LTS | 自动安装 | [examples/packer/ubuntu-24-04/](examples/packer/ubuntu-24-04/) | 验证过的引导示例 |
| Windows Server | 2022 | 自动应答 | [examples/packer/windows-server-2022/](examples/packer/windows-server-2022/) | 验证过的引导示例 |
通用的 `install_template` 合约支持任何可以从虚拟 CD 引导的模板文件启动的虚拟机操作系统。
引导示例已在 CI 中验证，但消费者仍需：
- 从调用 `terraform-proxmox-iso-manager-framework` 的运行器仓库 Terraform 中提供 `boot_iso`（以及任何 `additional_iso_files`）
- 将 `ansible_config.*` 路径指向消费者拥有的 Ansible 内容
- 决定示例 TLS 和 WinRM 设置是否是其环境的可接受的引导异常
## 先决条件
| 工具 | 版本 | 目的 |
|------|---------|---------|
| [Packer](https://www.packer.io/) | 1.15.0 | 镜像构建器 |
| [Ansible](https://docs.ansible.com/) | 消费者定义 | 消费者拥有的配置内容 |
| [Proxmox VE](https://www.proxmox.com/) | 8.x | 虚拟机管理程序目标 |
| [pre-commit](https://pre-commit.com/) | 4.0+ | 本地钩子运行器 |
## Proxmox API 令牌
创建一个具有 Packer 所需最小权限的专用 API 令牌。以下示例使用 `--privsep=0`，这会禁用令牌权限分离。如果您的环境支持令牌范围 ACL，则首选具有仅所需权限的权限分离令牌。
```
pveum role add PackerBuilder -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Migrate VM.Monitor VM.PowerMgmt Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit ISO.Download Pool.Audit Pool.Allocate SDN.Use Sys.Modify"
pveum user add packer@pve
pveum aclmod / -user packer@pve -role PackerBuilder
pveum user token add packer@pve packer-token --privsep=0
```
## 快速入门
### 1. 克隆并初始化
```
git clone https://github.com/nwarila-platform/proxmox-packer-framework.git
cd proxmox-packer-framework
cd packer
packer init .
```
### 2. 复制示例输入
```
# Packer 示例输入
cp ../examples/packer/.env.example ./../.env.packer.example
cp ../examples/packer/rocky-linux-9/rocky-linux-9.pkrvars.hcl ./my-rocky.pkrvars.hcl
```
`.env.example` 文件是您应该导出到您的 shell 或 CI 环境的值的模板。它们不是由 Packer 自动加载的。
### 3. 配置您的环境
- 从复制的 Packer 环境示例中导出 `PKR_VAR_*` 值，用于 Proxmox 访问和部署用户凭证
- 编辑 `my-rocky.pkrvars.hcl` 以设置网络、存储、硬件和安装设置
- 将 `install_template.template_path` 和 `ansible_config.*` 路径指向消费者拥有的内容
框架要求调用者提供 `boot_iso`（以及任何 `additional_iso_files`）——没有捆绑的媒体默认值。在生产中，运行器仓库从 `terraform-proxmox-iso-manager-framework` 输出渲染这些块到自动加载的 pkrvars 文件。对于本地验证运行，`examples/packer/` 下的示例 pkrvars 文件直接固定已知的良好 Proxmox 存储路径和 SHA-256 校验和。
框架还接受 `PKR_VAR_proxmox_skip_tls_verify` 和 `PKR_VAR_proxmox_node` 作为匹配嵌套 `packer_image` 字段的顶级 CI 友好覆盖。
### 4. 验证和构建
```
# Packer 验证和构建
cd ../packer
packer validate \
-var-file="my-rocky.pkrvars.hcl" \
.
packer build -force \
-var-file="my-rocky.pkrvars.hcl" \
.
```
`vm_id` 值在 Proxmox 中是集群范围内的唯一值。提供的示例 ID 仅作为占位符。
### 5. 安装 pre-commit 钩子
```
pre-commit install
pre-commit install --hook-type commit-msg
```
## 项目结构
```
proxmox-packer-framework/
|-- .config/
|-- .github/
| |-- scripts/
| | |-- get_packer_version.sh
| | |-- validate_examples.sh
| | `-- validate_examples.ps1
| `-- workflows/
|-- .vscode/
|-- docs/
| |-- explanation/
| | `-- architecture.md
| `-- reference/
| `-- template-contract.md
|-- examples/
| |-- packer/
| | |-- .env.example
| | |-- rocky-linux-9/
| | |-- ubuntu-24-04/
| | `-- windows-server-2022/
| `-- terraform/
| |-- .env.example
| |-- README.md
| `-- terraform.tfvars.example
|-- packer/
| |-- builds.pkr.hcl
| |-- data.pkr.hcl
| |-- locals.pkr.hcl
| |-- packer.pkr.hcl
| |-- source.pkr.hcl
| `-- variables.pkr.hcl
|-- .editorconfig
|-- .gitattributes
|-- .pre-commit-config.yaml
|-- .release-please-manifest.json
|-- release-please-config.json
|-- CHANGELOG.md
|-- CODE_OF_CONDUCT.md
|-- CONTRIBUTING.md
|-- LICENSE
|-- SECURITY.md
`-- SUPPORT.md
```
## CI/CD 管道
| 工作流程 | 触发器 | 执行操作 |
|----------|---------|--------------|
| 主要验证 | 推送到 `main` 并触摸 `packer/**`、`examples/**`、`contract/**`、`tools/**`、`.github/scripts/**`、`.github/workflows/**`、`.pre-commit-config.yaml`（以及 release-please 输出） | 可重用工作流程合约检查、Packer init/fmt/validate |
| PR 验证 | 每个 `main` 的 PR（以及合并队列） | 可重用工作流程合约检查、Packer init/fmt/validate |
| 安全 | 推送到 `main`、合并队列、每周计划 | 调用 org `reusable-iac-security`（Trivy IaC 加 Gitleaks 密钥扫描）、`reusable-codeql` 和 `reusable-scorecard`（OpenSSF Scorecard）可重用 |
| Drift Gate | 每个 `main` 的 PR | 验证此仓库与 org 基线和 `packer-framework-template` 基线清单的一致性 |
| 仓库卫生 | `main` 的 PR、合并队列、每周计划 | 调用 org `reusable-repo-hygiene` 策略（SHA 固定操作、精确固定、`pull_request_target` 安全性） |
| 发布 | 推送到 `main`（通过 `RELEASE_PLEASE_ON_PUSH` 选择的）或已发布的发布 | 运行 release-please 以更新更改日志/发布，并发布发布证据/证明 |
秘密扫描和 IaC 扫描在安全工作流程中运行一次，通过 org 拥有的 `reusable-iac-security` 可重用；验证工作流程不再运行 Gitleaks。两个附加工作流程是可调用的而不是事件触发的：`reusable-packer-framework-build.yaml`（以下描述的下游构建/验证入口点）和 `reusable-release-evidence.yaml`（由发布工作流程调用）。
## 下游集成
下游 OS 模板仓库应在 CI 验证或构建针对 SHA 固定的框架修订版时通过其可重用工作流程调用此框架。该工作流程接受与 `NWarila/packer-framework-template` 相同的运行器协议输入名称：
```
jobs:
validate-template-inputs:
uses: nwarila-platform/proxmox-packer-framework/.github/workflows/reusable-packer-framework-build.yaml@0123456789abcdef0123456789abcdef01234567
with:
framework_ref: 0123456789abcdef0123456789abcdef01234567
input_repo: NWarila/
input_ref: fedcba9876543210fedcba9876543210fedcba98
overlay_paths: |
packer/repos/public/=>packer/repos/public/
var_file: |
packer/repos/public/rocky-linux-9.pkrvars.hcl
build: false
upload_artifacts: false
```
对于特权 Proxmox 构建，设置 `build: true` 并将 Proxmox 凭据作为可重用工作流程秘密传递。该工作流程下载固定的 `secure-packer-bootstrapper` 发布版本，验证其 SHA-256 校验和，在构建步骤中生成短期的部署用户密码/散列/密钥材料，将生成的密钥加载到 `ssh-agent` 中，然后运行 `packer build`。
```
jobs:
build-template:
uses: nwarila-platform/proxmox-packer-framework/.github/workflows/reusable-packer-framework-build.yaml@0123456789abcdef0123456789abcdef01234567
with:
framework_ref: 0123456789abcdef0123456789abcdef01234567
input_repo: NWarila/
input_ref: fedcba9876543210fedcba9876543210fedcba98
overlay_paths: |
packer/repos/public/=>packer/repos/public/
var_file: |
packer/repos/public/rocky-linux-9.pkrvars.hcl
build: true
upload_artifacts: true
secrets:
proxmox_hostname: ${{ secrets.PROXMOX_HOSTNAME }}
proxmox_api_token_id: ${{ secrets.PROXMOX_PACKER_FRAMEWORK_TOKEN_ID }}
proxmox_api_token_secret: ${{ secrets.PROXMOX_PACKER_FRAMEWORK_SECRET }}
proxmox_node: ${{ secrets.PROXMOX_NODE }}
deploy_user_name: ${{ secrets.DEPLOY_USER_NAME }}
```
此框架生成旨在由 Terraform 或 OpenTofu 消费的 Proxmox VM 模板。下游仓库可以在旁边检出其自己的消费者内容，将 `.auto.pkrvars.hcl` 文件放置在框架 `packer/` 工作目录中，并直接运行 `packer validate .` / `packer build .`，只要它提供：
- 指向消费者拥有的安装模板的 `install_template`
- 指向消费者拥有的 Ansible 内容的 `ansible_config`，其中 `ansible-playbook` 在运行时环境中可用在 PATH 中
- 从运行器仓库 Terraform 调用 `terraform-proxmox-iso-manager-framework` 生成的 `boot_iso`（以及任何 `additional_iso_files`）
`template_description` 中的构建时间戳可以用于在发布新模板时触发下游 VM 替换。
```
resource "terraform_data" "template_version" {
input = data.proxmox_virtual_environment_vm.template.description
}
resource "proxmox_virtual_environment_vm" "vm" {
lifecycle {
replace_triggered_by = [terraform_data.template_version]
}
}
```
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。此项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 并通过预提交钩子强制执行它们。
## 许可证
本项目采用 [MIT 许可证](LICENSE)。
标签：Ansible, CI验证, ECS, GitHub Advanced Security, ISO管理, Packer, Proxmox, SHA验证, Terraform, VM模板, 代码库, 可重用性, 基础设施, 安全加固, 开源, 数据驱动, 日志审计, 特权提升, 系统提示词, 自动化部署, 虚拟化, 软件构建