NWarila/proxmox-packer-framework

# Proxmox Packer 框架 一个生产级、数据驱动的 [Packer](https://www.packer.io/) 框架，用于构建经过加固的 Proxmox VE 虚拟机模板。它结合了通过 Kickstart 进行的自动化 OS 安装、通过 Ansible 进行的配置管理，以及通过 OpenSCAP 实现的 DISA STIG 合规性 —— 交付安全、可复现且随时可供 Terraform 或 OpenTofu 进行基础设施即代码 (infrastructure-as-code) 使用的黄金镜像。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ .pkrvars.hcl (variables) │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │ │ │ Proxmox │ │ Hardware │ │ Network │ │ Disk / LVM │ │ │ │ API creds │ │ CPU, RAM │ │ IP, VLAN │ │ Partitions │ │ │ └─────┬──────┘ └─────┬──────┘ └──────┬──────┘ └────────┬─────────┘ │ │ └───────────────┴────────────────┴──────────────────┘ │ │ │ │ │ locals.pkr.hcl │ │ (normalize + defaults) │ │ │ │ │ source.pkr.hcl │ │ (proxmox-iso source) │ │ │ │ └────────────────────────────────────┼────────────────────────────────────┘ │ ┌────────────────┴────────────────┐ │ builds.pkr.hcl │ │ │ │ 1. Kickstart (ks.pkrtpl.hcl) │ │ ├─ Partitioning (LVM) │ │ ├─ DISA STIG (OpenSCAP) │ │ ├─ SSH hardening │ │ └─ Deploy user creation │ │ │ │ 2. Ansible Provisioning │ │ ├─ base (update + packages)│ │ ├─ users (fact injection) │ │ ├─ configure (cloud-init, │ │ │ SSH, hostname, SELinux) │ │ └─ clean (logs, keys, │ │ machine-id, cloud-init) │ │ │ │ 3. Manifest (build metadata) │ └────────────────┬─────────────────┘ │ ▼ Proxmox VM Template (ready for Terraform clone) ``` ## 特性 - **数据驱动配置** — 所有 VM 参数（CPU、内存、磁盘、网络、分区）均在 `.pkrvars.hcl` 文件中定义。`locals.pkr.hcl` 规范化层通过 `coalesce()` 应用合理的默认值，因此使用者只需覆盖所需内容。 - **DISA STIG 合规性** — Kickstart 模板在 OS 安装期间使用 OpenSCAP 插件 (`xccdf_org.ssgproject.content_profile_stig`) 应用 STIG 安全配置文件。 - **CIS 对齐的磁盘分区** — 为 `/`、`/home`、`/tmp`、`/var`、`/var/tmp`、`/var/log` 和 `/var/log/audit` 设置独立的 LVM 卷，并使用限制性的挂载选项 (`noexec`、`nosuid`、`nodev`)。 - **SSH 加固** — 禁用 Root 登录，强制公钥认证，禁用 X11 转发，显式配置 SFTP 子系统，并锁定 `MaxAuthTries` / `LoginGraceTime` —— 在 Kickstart `%post` 和 Ansible 中均应用以实现纵深防御。 - **Cloud-init 生命周期** — 安装 cloud-init，配置 Proxmox 数据源，启用所有 cloud-init 服务，加载 `isofs` 内核模块以进行基于 CDROM 的配置驱动器检测，并在模板封装前执行完整清理 (`cloud-init clean --logs --seed`)。 - **模板就绪清理** — `clean` 角色移除 SSH 主机密钥、machine-id、audit/system 日志、tmp 目录、NetworkManager 连接、udev 规则和 Shell 历史记录，以确保每个克隆在首次启动时获得唯一身份。 - **构建元数据** — 每次构建都会生成一个 JSON 清单，其中包含 git commit 哈希、构建时间戳、硬件配置和部署用户名，以实现完全的可追溯性。 - **自动化构建时间戳** — `template_description` 通过 Packer 的 `timestamp()` 函数自动标记构建时间，使下游 Terraform 能够通过 `replace_triggered_by` 检测模板变更。 ## 支持的操作系统 | OS | 版本 | 安装方式 | 示例 | |----|---------|---------------|---------| | Rocky Linux | 9.x | Kickstart | [rocky-linux-9.pkrvars.hcl](examples/rocky-linux-9.pkrvars.hcl) | 该框架的变量结构支持任何 RHEL 家族的 OS（并且在 `base/vars/main.yml` 中包含 Debian、SUSE 和 Ubuntu 的包映射）。添加新 OS 只需一个新的 `.pkrvars.hcl` 文件，如有需要，还可添加一个安装模板。 ## 前置条件 | 工具 | 版本 | 用途 | |------|---------|---------| | [Packer](https://www.packer.io/) | 1.15.0 | 镜像构建器 | | [Ansible](https://docs.ansible.com/) | 2.15+ | 配置管理 | | [Proxmox VE](https://www.proxmox.com/) | 8.x | Hypervisor 目标 | | [pre-commit](https://pre-commit.com/) | 4.0+ | 本地 Hook 运行器 (可选) | ### Proxmox API Token 创建一个具有 Packer 创建 VM 和模板所需最小权限的专用 API Token： ``` 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/proxmox-packer-framework.git cd proxmox-packer-framework/packer packer init . ``` ### 2. 配置变量 复制示例文件并填入您的环境特定值： ``` cp examples/rocky-linux-9.pkrvars.hcl packer/my-rocky.pkrvars.hcl cp examples/secrets.pkrvars.hcl packer/my-secrets.pkrvars.hcl ``` 编辑 `my-secrets.pkrvars.hcl` 以包含您的 Proxmox API 凭证和部署用户设置。编辑 `my-rocky.pkrvars.hcl` 以匹配您的网络、存储和硬件要求。 ### 3. 验证并构建 ``` # 验证配置 packer validate \ -var-file="my-rocky.pkrvars.hcl" \ -var-file="my-secrets.pkrvars.hcl" . # 构建模板 (-force 替换具有相同 vm_id 的现有模板) packer build -force \ -var-file="my-rocky.pkrvars.hcl" \ -var-file="my-secrets.pkrvars.hcl" . ``` ### 4. 安装 pre-commit hooks (贡献者) ``` pre-commit install pre-commit install --hook-type commit-msg ``` ## 项目结构 ``` proxmox-packer-framework/ ├── .config/ # Linter configurations │ ├── .ansible-lint.yml │ ├── .markdownlint.json │ └── .yamllint.yaml ├── .github/ │ ├── ISSUE_TEMPLATE/ # Structured bug/feature forms │ ├── config/gitleaks.toml # Secret detection rules │ ├── scripts/get_packer_version.sh │ └── workflows/ │ ├── dev-promotion-gate.yml # Packer fmt + validate on DEV push │ ├── feature-push-gate.yml # Gitleaks on feature branches │ ├── pr-validation.yaml # Packer fmt + validate on PRs to main │ ├── release-please.yaml # Automated changelog + GitHub Releases │ └── security.yaml # Weekly Trivy + Gitleaks scan ├── .vscode/ # Editor settings + tasks ├── examples/ │ ├── rocky-linux-9.pkrvars.hcl # Full Rocky Linux 9 example │ └── secrets.pkrvars.hcl # Credential placeholder ├── packer/ │ ├── ansible/ │ │ ├── ansible.cfg # SSH, pipelining, transfer config │ │ ├── linux-playbook.yml # Main playbook (base → users → configure → clean) │ │ ├── linux-requirements.yml # Galaxy collections (ansible.posix, community.general) │ │ └── roles/ │ │ ├── base/ # OS updates, package installation, cloud-init install │ │ ├── users/ # Fact injection for deploy user │ │ ├── configure/ # SSH, hostname, SELinux, cloud-init datasource │ │ └── clean/ # Template sealing (logs, keys, machine-id, cloud-init) │ ├── data/ # Kickstart sub-templates (network, storage) │ ├── templates/ │ │ └── ks.pkrtpl.hcl # Data-driven Kickstart template │ ├── builds.pkr.hcl # Build definition (Ansible provisioner + manifest) │ ├── data.pkr.hcl # Git data source for build metadata │ ├── locals.pkr.hcl # Variable normalization layer │ ├── providers.pkr.hcl # Packer + plugin version pins │ ├── source.pkr.hcl # proxmox-iso source definition │ └── variables.pkr.hcl # Input variable declarations ├── .editorconfig # Cross-editor formatting ├── .gitattributes # Line endings, Linguist, export-ignore ├── .pre-commit.config.yaml # Hooks: hygiene, secrets, packer, ansible, yaml, markdown ├── .release-please-manifest.json # Current version tracker ├── release-please-config.json # Changelog sections + release config ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE # MIT ├── SECURITY.md └── SUPPORT.md ``` ## CI/CD 流水线 | 工作流 | 触发器 | 功能 | |----------|---------|-------------| | **Feature Push Gate** | 推送到除 DEV/TEST/PROD 以外的任何分支 | Gitleaks 密钥扫描 | | **DEV Promotion Gate** | 推送到 `DEV` (packer/** 变更) | Gitleaks + Packer fmt 检查 + Packer validate | | **PR Validation** | 指向 `main` 的 PR (packer/** 或 examples/** 变更) | Gitleaks + Packer fmt 检查 + Packer validate | | **Security Scanning** | 推送/PR 到 `main`，每周计划 | Trivy 文件系统扫描 (SARIF) + Gitleaks | | **Release Please** | 推送到 `main` | 自动生成变更日志 + GitHub Releases | ## 下游集成 此框架生成的 Proxmox VM 模板旨在供 Terraform 或 OpenTofu 使用。`template_description` 中的构建时间戳允许在构建新模板时自动替换 VM： ``` # 在你的 Terraform 配置中： 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/) 并通过 pre-commit hooks 强制执行。 ## 许可证 本项目基于 [MIT License](LICENSE) 授权。

标签：Ansible, EC2, ECS, Golden Image, IaC, Kickstart, KVM, LVM, OpenSCAP, OpenTofu, Packer, Proxmox, Proxmox VE, STIG, Terraform, 安全基线, 教学环境, 特权提升, 系统加固, 系统提示词, 网络安全研究, 自动化部署, 虚拟化, 虚拟机模板, 运维工具, 镜像构建