Skip to content

HOWTO - Build and Rebuild Proxmox Templates with HyOps

This HOWTO shows the current HyOps path for Proxmox template lifecycle operations. It covers environment bootstrap, strict preflight, build, purge, and rebuild semantics, then shows how downstream VM modules consume template state without hardcoded IDs.

Difficulty: Intermediate
Prerequisites: Proxmox API and SSH reachability, hyops CLI installed, vault password bootstrap completed.

Context

This flow uses module core/onprem/template-image with driver images/packer.

Supported template keys:

  • ubuntu-22.04
  • ubuntu-24.04
  • rocky-9
  • rocky-10
  • windows-server-2022
  • windows-server-2025
  • windows-11-enterprise

The module publishes template_vm_id and template_name to env state:

  • $HOME/.hybridops/envs/<env>/state/modules/core__onprem__template-image/latest.json

Steps

1. Bootstrap vault and initialise Proxmox target

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

Expected result:

  • Credentials written to $HOME/.hybridops/envs/dev/credentials/proxmox.credentials.tfvars
  • Readiness marker written to $HOME/.hybridops/envs/dev/meta/proxmox.ready.json

2. Prepare inputs overlays

For quick runs you can point --inputs at the shipped module example and override values via HYOPS_INPUT_* without copying any files:

export HYOPS_CORE_ROOT="${HYOPS_CORE_ROOT:-$HOME/.hybridops/core/app}"
INPUTS="$HYOPS_CORE_ROOT/modules/core/onprem/template-image/examples/inputs.min.yml"

# Example: build Windows 11 template without editing an inputs file
HYOPS_INPUT_template_key=windows-11-enterprise \
HYOPS_INPUT_name=dev-windows-11-enterprise-template \
hyops preflight --env dev --strict --module core/onprem/template-image --inputs "$INPUTS"

If you prefer an editable overlay file for repeatable runs, create one:

cat > /tmp/template-image.dev.yml <<'YAML'
template_key: windows-11-enterprise
name: dev-windows-11-enterprise-template
# Optional: set a deterministic VMID for shared Proxmox clusters.
# vmid: 9311
# Optional: fail the build if automatic post-build smoke validation fails.
# post_build_smoke:
#   required: true
YAML

Then reference /tmp/template-image.dev.yml in the commands below.

3. Run strict preflight

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

Expected result:

  • exit_code=0
  • module:core/onprem/template-image ok

4. Build template

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

Notes:

  • hyops apply runs an automatic post-build smoke validation by default (clone -> boot -> guest-agent IP -> cleanup).
  • Smoke failures are warning-only by default. Set post_build_smoke.required: true to make smoke validation fail the build.
  • Disable only when necessary (for constrained labs) with post_build_smoke.enabled: false.

Windows 11 one-off example without editing file:

HYOPS_INPUT_template_key=windows-11-enterprise \
hyops apply --env dev --module core/onprem/template-image \
  --inputs "$INPUTS"

5. Purge template

Use destroy with the same logical inputs used for build.

HYOPS_INPUT_template_key=windows-11-enterprise \
hyops destroy --env dev --module core/onprem/template-image \
  --inputs "$INPUTS"

6. Rebuild template

Set rebuild_if_exists: true when you want in-place replace semantics.

Overlay approach:

rebuild_if_exists: true

One-off command:

HYOPS_INPUT_template_key=windows-11-enterprise \
HYOPS_INPUT_rebuild_if_exists=true \
hyops apply --env dev --module core/onprem/template-image \
  --inputs "$INPUTS"

Validation

Check latest env state:

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

Confirm:

  • status is ok
  • outputs.template_key matches requested key
  • outputs.template_name is present
  • outputs.template_vm_id is a positive integer

Check evidence for the run:

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

Core artifacts:

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

Troubleshooting

Missing Proxmox credentials:

  • Symptom: preflight reports missing required tfvars keys.
  • Fix: rerun hyops init proxmox --env <env> --bootstrap --proxmox-ip <proxmox-ip>.

Template already exists:

  • Symptom: apply fails fast with template-name conflict.
  • Fix: set rebuild_if_exists: true, or run hyops destroy then hyops apply.

Plugin or ISO download failures:

  • Symptom: packer init or packer build fails in evidence logs.
  • Fix: restore outbound network access from runner for plugin and ISO fetch.

State consumption by VM module:

  • Use: 
    template_state_ref: "core/onprem/template-image"
template_key: "windows-11-enterprise"
  • Then run platform/onprem/platform-vm preflight/apply; it resolves template_vm_id from env state before provider calls.

References

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