Proxmox VE 9.2 Cloud-Init Template Audit Checklist

Run a Proxmox VE 9.2 cloud-init template audit to catch stale ISOs, wrong hostnames, missing SSH keys, and failed provisioning so new clones boot correctly.

Proxmox PulseProxmox Pulse
11 min read
Glass cubes on a server rack, one glowing amber, in dark data-center light.

After a Proxmox VE 9.2 upgrade, the template that used to create working VMs can start producing clones with the wrong hostname, missing SSH keys, or an IP address that never arrives. A cloud-init template audit is a short, repeatable pass over the template config, the dumped user, network, and vendor files, and one full-clone boot. The outcome is a template you can clone with confidence, instead of a golden image that quietly depends on old guest state.

Key Takeaways

  • Template config: confirm the cloudinit ISO, guest agent, user, password, SSH keys, and custom cloud-init settings are still attached before cloning anything.
  • Cloud-init files: dump user, network, and vendor data; stale or empty snippets are a common cause of surprise.
  • Full clone: audit with a full clone because linked clones can hide already-run cloud-init state.
  • Guest state: cloud-init may report done even when the clone never received the new template identity.
  • Upgrade drift: Proxmox VE 9.2 is usually not the culprit; the template and guest packages are.

What usually drifts after a Proxmox VE 9.2 upgrade?

Cloud-init templates are easy to forget because they sit idle until the next VM is created. The host upgrade may change storage, networking, QEMU behavior, or the node’s local files, but the template disk and the guest’s /var/lib/cloud directory do not automatically refresh themselves. If the template sat through a Proxmox VE 9.1 to 9.2 upgrade, the first thing to inspect is the template config, not the guest operating system.

The most common failures are boring but annoying:

  • the cloudinit ISO is no longer attached where the guest expects it
  • custom cloud-init snippets were moved, renamed, or never copied to a new node
  • the guest image no longer has the cloud-init package or the QEMU Guest Agent package
  • the template already ran cloud-init, so a clone starts with the old hostname and old SSH keys
  • the template config still points to a stale user, password, or SSH key path

A good audit takes about 15 minutes if you keep the checklist narrow. The goal is not to rebuild every template every time. The goal is to prove that one clone can boot, configure itself, and answer over SSH.

How to confirm the template is still a template?

Start with the Proxmox config for the template. Do not assume the GUI is showing everything useful, especially if the template was created months ago or migrated from another node.

pveversion -v | head -n 1
qm config 9000 | grep -E '^(template|ide2|agent|ciuser|cipassword|sshkeys|cicustom):'

A healthy cloud-init template often shows the template flag, a cloudinit ISO, an enabled guest agent, and cloud-init identity options.

template: 1
ide2: local:cloudinit,media=cdrom
agent: enabled=1
ciuser: admin
sshkeys: ssh-rsa AAAAB3Nza...

If the cloudinit ISO is missing, the guest may still boot, but it may not receive the cloud-init seed data. If the guest agent is disabled, Proxmox may not show useful IP information after boot, even when the VM is healthy.

Check the cloudinit ISO and template disk

The default local storage path for the cloudinit ISO is easy to inspect.

find /var/lib/vz/template/iso -maxdepth 1 -name cloudinit.iso -ls
qm config 9000 | grep -E '^(scsi0|virtio0|sata0|ide0):'

The ISO may be created or refreshed by Proxmox when a cloud-init VM starts, but you still want to see the attached disk configuration. If the template disk lives on a storage pool that changed during the upgrade, a clone can fail before cloud-init even gets a chance to run.

Inspect custom cloud-init snippets on the host

Custom cloud-init files are stored under the snippets directory for the VM ID.

ls -ld /var/lib/vz/snippets/9000/cloud-init/ 2>/dev/null
qm cloudinit dump 9000 user
qm cloudinit dump 9000 network
qm cloudinit dump 9000 vendor

The user file is where you normally define the user, hostname, timezone, package list, and cloud-config directives.

#cloud-config
hostname: cloudinit-audit
fqdn: cloudinit-audit.local
manage_etc_hosts: true
timezone: UTC
ssh_pwauth: true
users:
  - name: admin
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    lock_passwd: false

The network file controls interface behavior. For a simple DHCP template, it may be very short.

version: 2
ethernets:
  eth0:
    dhcp4: true

The vendor file is often empty in homelabs, but it can contain vendor-specific cloud-init directives. Do not ignore it just because it looks unused. If it was added once for a cloud provider image, it may still affect behavior.

How to clone and boot a disposable audit VM

The audit VM should be disposable. Use a VM ID that will not conflict with production, and expect to delete it after the test.

qm clone 9000 9999 --full --name cloudinit-audit
qm start 9999

Use a full clone for the audit. A full clone gives you a real first-boot path. On my NVMe homelab node, a 10 GiB Ubuntu 24.04 cloud image full clone took about 25 seconds, while the linked clone finished under 2 seconds. That speed difference is tempting, but the full clone is the one that proves the template is clean.

Audit method What it proves Cost Main risk
Full clone Clean first-boot provisioning 10 GiB copy, 20-30 seconds Storage used for the test
Linked clone Template config and attached cloudinit ISO Under 2 seconds Hidden cloud-init state
Template config dump Proxmox-side cloud-init options Instant No guest-side proof
In-place template edit Quick config fix Minimal Can break the next clone

The honest tradeoff is boring: full clones cost time and storage, but they are the only method that proves the guest will run cloud-init from scratch.

Use a linked clone only when you already trust the template

Linked clones are excellent for fast testing after the template has already passed a full-clone audit.

qm clone 9000 9998 --link --name cloudinit-link-test
qm start 9998

If the template came from a snapshot chain, run a snapshot rollback test before trusting linked clones. A linked clone is fast, but it inherits the snapshot relationship. If the snapshot chain is old, damaged, or tied to a storage path that changed during the upgrade, the clone can fail in ways that look like cloud-init problems but are really storage problems.

Which guest-side files prove cloud-init will run?

Once the audit VM is running, log in and check the guest state. If you are using the admin user from the template, SSH in with the expected key.

ssh -o StrictHostKeyChecking=accept-new [email protected]

Start with the cloud-init status.

sudo cloud-init status --wait
sudo cloud-init --version
systemctl status qemu-guest-agent --no-pager

If the guest agent is missing, the VM may boot fine but Proxmox may not know its IP address. If the agent is missing, my QEMU Guest Agent check covers the host-side and guest-side fixes in more detail.

The important directories are under /var/lib/cloud.

ls -l /var/lib/cloud/instance/
ls -l /var/lib/cloud/data/
ls -l /var/lib/cloud/seed/

A healthy first boot usually shows that cloud-init has received seed data and has created instance files. The seed directory may contain a nocloud or nocloud-net directory, depending on the image and cloud-init version.

ls -l /etc/cloud/cloud.cfg.d/
grep -R datasource /etc/cloud/ 2>/dev/null

The datasource is what connects the guest to the cloudinit ISO. If the datasource is wrong, the guest may boot without applying the template’s user data.

If cloud-init failed, the logs usually say so directly.

sudo tail -n 80 /var/log/cloud-init.log
sudo tail -n 40 /var/log/cloud-init-output.log

The output log is especially useful because it shows what the user data script printed. If you are installing packages, writing files, or running commands in the user data, that is where the failure often appears.

How to test the audit VM after Proxmox VE 9.2

The audit is not finished until the VM proves it can do the things you expect from cloud-init: report identity, get a network address, and accept SSH.

Check the guest agent and first-boot logs

From the Proxmox host, check that the guest agent is actually answering.

qm agent 9999 status
qm agent 9999 info

A running agent may return a status object like this:

{
  "status": "running"
}

If the agent does not answer, do not immediately blame cloud-init. The guest may still be booting, the agent package may be missing, or the agent service may not be enabled. The agent is the easiest false positive in the whole audit.

Verify the clone got the expected identity

Inside the audit VM, confirm that the hostname, network, DNS, and SSH keys came from the cloud-init template.

ip -br address
sudo cat /etc/resolv.conf
sudo cat /home/admin/.ssh/authorized_keys

If the hostname is still the template hostname, cloud-init may have run before the template was made. If the SSH key is missing, the template may not have received the SSH keys from Proxmox, or the cloud-init user data may have overridden the expected user.

A good audit VM should answer these questions without guessing:

  • Did the VM boot?
  • Did cloud-init finish?
  • Did the guest agent report the IP address?
  • Did the hostname change from the template?
  • Did the expected user exist?
  • Did the SSH key land in the expected home directory?
  • Did DNS resolve correctly?

If all of those pass, the template is probably safe for the next round of clones.

What should you change after the audit?

If the audit passes, leave the template alone and delete the disposable VM.

qm shutdown 9999
qm destroy 9999 --purge --force

If the audit fails, fix the template in a copy rather than editing the old template in place. This keeps the old template available while you test the fix.

qm clone 9000 9001 --full --name cloudinit-fixed
qm start 9001

Log into the fixed VM and clean the cloud-init state.

sudo cloud-init clean --logs
sync
shutdown -h now

After the VM is stopped, convert it into the new template.

qm template 9001
qm clone 9001 9999 --full --name cloudinit-retest
qm start 9999

If the problem is missing packages inside the guest, install them before converting the copy to a template.

sudo apt update
sudo apt install -y cloud-init qemu-guest-agent
sudo systemctl enable --now qemu-guest-agent

If the problem is stale Proxmox-side cloud-init data, update it on the fixed template.

qm cloudinit set 9001 user --file /tmp/user.yaml
qm cloudinit dump 9001 user

Then retest with another full clone. Do not skip the retest. A fixed template is only fixed after a clone proves it.

Gotchas that make cloud-init templates lie

The most frustrating gotcha I have hit is a template that reports cloud-init as done even though the clone never ran provisioning. The reason is simple: cloud-init ran once inside the template image. When the template was copied, the guest carried over /var/lib/cloud state. The clone started, saw that cloud-init had already completed, and did nothing new.

In that case, the VM may boot with:

  • the old template hostname
  • the old SSH keys
  • the old timezone
  • the old user configuration
  • no new cloud-init output log entries

The fix is to clean the cloud-init state before converting the image to a template, or to rebuild the template from a clean cloud image.

Another gotcha is assuming the cloudinit ISO is always present just because the GUI shows it. On a fresh node or after a storage change, the default local path may not contain the ISO yet. The template config may look correct, but the first boot can still be slower or fail if the ISO cannot be attached.

A third gotcha is treating the guest agent as proof that cloud-init worked. The guest agent can run while cloud-init fails. If the agent reports an IP but the hostname is wrong, the problem is still cloud-init, not QEMU Guest Agent.

The final gotcha is using a linked clone to prove a template is clean. It is faster, but it is not the same test. If the template has already run cloud-init, a linked clone can make the problem look intermittent while a full clone makes it obvious.

Conclusion

A Proxmox VE 9.2 cloud-init template audit is a small investment that prevents a fleet of half-provisioned VMs. Run the config check, dump the cloud-init files, boot one full clone, and verify the hostname, IP, SSH key, and cloud-init status. Your next step is to pick one template, clone it as a disposable test VM, and run the checklist before creating the next production VM.

Share
Proxmox Pulse

Written by

Proxmox Pulse

Sysadmin-driven guides for getting the most out of Proxmox VE in production and homelab environments.

Related Articles

View all →