Build Proxmox VM Templates (HyOps)¶

Purpose: Build (or rebuild) a Proxmox VM template with evidence and state captured under a HyOps environment.
Owner: Platform engineering
Trigger: Base image refresh, security patching, new template key required
Impact: New VMs cloned from this template inherit the baseline; template rebuilds affect future provisioning.
Severity: P2
Pre-reqs: Proxmox reachable; hyops installed; vault ready; Proxmox target initialised for the selected env.
Rollback strategy: Continue using the previous template, or destroy and rebuild this template with controlled inputs.

Context¶

This runbook executes:

Module: core/onprem/template-image
Driver: images/packer

The module publishes template identifiers into HyOps state so VM modules can consume a template via state, not hardcoded VMIDs.

Preconditions and safety checks¶

Choose the correct --env (for example dev, staging, prod).
Confirm workstation-to-Proxmox connectivity (API and SSH).
Confirm datastore capacity on the Proxmox node for template disks and ISOs.
Confirm the build network has DHCP and the build path has outbound access (ISO downloads and package installs).

Steps¶

1) Vault bootstrap (one-time per workstation)

hyops vault bootstrap

2) Init Proxmox for the environment (per env)

hyops init proxmox --env dev --bootstrap --proxmox-ip <proxmox-ip>

This writes:

$HOME/.hybridops/envs/dev/credentials/proxmox.credentials.tfvars
$HOME/.hybridops/envs/dev/meta/proxmox.ready.json

3) Prepare an inputs overlay

Minimal:

template_key: "ubuntu-24.04"

Recommended (portable default with optional custom naming):

template_key: "ubuntu-24.04"
# Optional: pin a reserved template VMID.
# vmid: 9001
# Optional: override the default template name (<template_key>-template).
# name: "<your-template-name>"

4) Preflight

hyops preflight --env dev --strict \
  --module core/onprem/template-image \
  --inputs <inputs.yml>

5) Build

hyops apply --env dev \
  --module core/onprem/template-image \
  --inputs <inputs.yml>

By default, hyops apply also runs an automatic post-build smoke validation (clone -> boot -> guest-agent IP -> cleanup) using the same Proxmox API credentials. This is warning-only unless inputs.post_build_smoke.required: true.

Operator UX note:

HyOps keeps terminal output concise by default and writes full build logs to evidence (packer.log).
For long runs, HyOps prints a log-watch hint and heartbeat lines.
Use hyops --verbose ... to mirror Packer output to terminal while still writing evidence logs.

Rebuild an existing template¶

If a template with the same name already exists, preflight fails fast.

To rebuild in place, set rebuild_if_exists: true:

In the overlay:
```
rebuild_if_exists: true
```

Or one-off:

HYOPS_INPUT_rebuild_if_exists=true hyops apply --env dev --module core/onprem/template-image --inputs <inputs.yml>

Verification¶

State (latest):

$HOME/.hybridops/envs/dev/state/modules/core__onprem__template-image/latest.json

Confirm:

status is ok
outputs.template_name
outputs.template_vm_id
evidence_dir exists and contains packer_* artifacts

Evidence directory:

$HOME/.hybridops/envs/dev/logs/module/core__onprem__template-image/<run_id>/

Common evidence artifacts:

packer_init.stdout.txt
packer_validate.stdout.txt
packer_build.stdout.txt
packer_build.stderr.txt
packer.log
template_smoke.json (automatic post-build smoke summary)
template_smoke.log (smoke step status stream)

Failure triage:

Recent HyOps builds include an open: <evidence>/packer.log hint in the error summary.
Start with packer.log, then review packer_build.stderr.txt if needed.

Downstream consumption (VM provisioning)¶

VM modules can consume this template via state:

template_state_ref: "core/onprem/template-image"
template_key: "ubuntu-24.04"

For example, platform/onprem/platform-vm preflight resolves template_vm_id from env state before provider calls.

Common issues¶

Missing Proxmox credentials¶

Symptom: preflight fails with missing required Proxmox credentials or missing tfvars keys.

Fix:

hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>

Template already exists¶

Fix: set rebuild_if_exists: true, or run hyops destroy then hyops apply with the same overlay.

Plugin or download failures¶

Fix: ensure workstation outbound access for packer init (Packer plugins) and ISO downloads.

Post-actions and clean-up¶

Record run_id, evidence_dir, template_key, and template_vm_id in the change record.
If this was a test build, remove or rebuild the template with controlled inputs before production use.
Confirm downstream VM overlays reference the intended template_key.
Archive build evidence from:
$HOME/.hybridops/envs/<env>/logs/module/core__onprem__template-image/<run_id>/

References¶

Maintainer: HybridOps.Studio