ntbops-ansible/docs/proxmox-template.md

Proxmox Debian 13 GenericCloud Template

Expected VM defaults:

• Debian 13 Trixie GenericCloud image
• Q35 machine type
• UEFI / OVMF
• VirtIO SCSI controller
• VirtIO network device
• CPU type host
• QEMU Guest Agent enabled
• Cloud-Init drive attached
• Serial console attached as serial0: socket
• Display set to vga: serial0 for Proxmox xterm.js console access
• 2 vCPU, 2 GB RAM, 32 GB disk unless a service needs more

Use the helper script on a Proxmox node to create the base template:

scripts/create-proxmox-template.sh

The script prompts for VMID, name, storage, bridge, CPU, memory, disk size, and image source. Press Enter to accept the displayed defaults. It downloads the Debian 13 GenericCloud qcow2 image unless a local --image-file is provided, imports it into Proxmox storage, attaches a Cloud-Init drive, configures serial console support, and converts the VM to a template.

For automation or previews:

scripts/create-proxmox-template.sh --dry-run --yes
scripts/create-proxmox-template.sh --non-interactive --vmid 9000 --storage local-lvm --bridge vmbr0

If a PBS storage/datastore ID is supplied, the template's main disk is created with the Proxmox disk backup=1 flag. Leaving it empty keeps the main disk at backup=0.

scripts/create-proxmox-template.sh --pbs-storage pbs-main

To initialise all VMs declared in host_vars/*.yml, run:

scripts/init-proxmox-vms.sh

The VM initialiser checks whether the template VMID exists. If it does not, it runs scripts/create-proxmox-template.sh first. Each host var file with a proxmox_vmid is cloned from the template and configured from its proxmox_* hardware settings.

Cloud-Init is only responsible for Day 0 bootstrap: user creation, SSH hardening, Docker installation, baseline packages, firewall defaults, directory layout, PKI directory preparation, enabling serial-getty@ttyS0.service, and ansible-pull.

Proxmox hardware settings must be applied outside Cloud-Init. For a VM or template, set:

qm set <vmid> --serial0 socket --vga serial0

The Cloud-Init template enables serial-getty@ttyS0.service by default and sets TERM=xterm-256color for that getty. Override these variables if needed:

cloud_init_serial_console_enabled: true
cloud_init_serial_console_tty: ttyS0
cloud_init_serial_console_term: xterm-256color

Applications and durable service configuration belong in Ansible roles.