Skip to content

Adopt Packer + Cloud-Init for VM Template Standardization

Status

Accepted — Packer is the standard for building immutable VM templates on Proxmox; cloud-init is the default initialization system.

Context

Manual template builds via Proxmox UI cause configuration drift, lack auditability, and scale poorly. We require repeatable golden images that integrate with Terraform (provisioning) and Ansible (configuration management).

Decision

Use HashiCorp Packer (Proxmox ISO builder) to produce cloud-init-ready templates for: - Linux: Ubuntu 22.04/24.04 LTS, Rocky Linux 9/10 - Windows: Server 2022/2025, Windows 11 Enterprise (via Cloudbase-Init)

Templates are version-controlled in Git and rebuilt on a monthly cadence or when CVEs require patches.

Prerequisite: Enterprise network infrastructure per ADR-0015 (DHCP on management network, DNS, outbound access).

Principles

  1. Immutable images — Rebuild for changes; no in-place modifications
  2. Declarative — HCL configuration in Git with review trails
  3. Separation of concerns — Packer builds → Terraform provisions → Ansible configures
  4. Cloud-init first — Environment specifics applied at clone time
  5. VMID auto-increment — Conflicts resolved automatically during builds

Scope

In-scope: - Full VMs requiring bootable OS images (control nodes, RKE2 nodes, Linux/Windows servers) - Automated builds with evidence generation - Chain ID tracking for audit correlation

Out-of-scope: - LXC containers (see ADR-0018 – LXC Containers for Lightweight Workloads) - Application-layer configuration - Runtime network design (VLANs, SDN) - Docker/OCI images

Consequences

Positive

  • Repeatable, auditable builds with <5% drift rate
  • 80% reduction in template build time vs manual UI
  • Consistent hardening baselines across all images
  • Full audit trail via chain IDs and evidence artifacts

Negative

  • Team must learn Packer HCL and plugin specifics
  • Build pipeline adds <10 minutes per template
  • Requires template storage management and retention policies

Implementation Notes

  • Packer HCL lives in infra/packer-multi-os/
  • Provisioning toolkit (init, wrapper, evidence, unattended rendering) lives in control/tools/provision/packer/ (bin/ and remote/)
  • Proxmox API environment is written to infra/env/proxmox.credentials.tfvars via control/tools/provision/init/init-proxmox-env.sh
  • Evidence and logs are written under:
  • output/logs/packer/…
  • output/artifacts/platform/onprem/proxmox/packer/…
  • Chain IDs from chain-lib.sh are used to correlate init logs, build logs and proof artifacts

Metrics & Review Triggers

  • Success rate: ≥95%
  • Build time: <10min per template
  • Cloud-init success: ≥99%
  • Review triggers: Proxmox major upgrades, plugin API changes, failure rate >10%

Alternatives Considered

Option Rejected Because
Manual UI builds Configuration drift, no audit trail, slow
Ansible-only provisioning Not immutable, slower, blurs layer separation
Terraform-only OS installs Not designed for OS installation phase
Cloud-init without golden images Slow per-VM provisioning, inconsistent baselines
LXC-only architecture Insufficient isolation for security/kernel requirements

References

External: - HashiCorp Packer Documentation - Packer Proxmox Plugin - Proxmox VE API - cloud-init Documentation

Maintainer: HybridOps.Studio License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.