Ansible Role: Proxmox VM → Template → Clones (Cloud-Init)

This role automates the full lifecycle of deploying a Debian GenericCloud VM on Proxmox, converting it into a template, and optionally creating multiple Cloud-Init clones with static or dynamic networking.

It supports:

Downloading Debian GenericCloud image (qcow2)

Creating and configuring a base VM

UEFI + Secure Boot + TPM 2.0 (optional)

PCI or VirtIO GPU passthrough (optional)

Disk import + optional resize

Cloud-Init user and vendor templates

Template conversion

Automatic clone deployment with per-VM networking and hostname settings

Features

✔ Automatically downloads Debian Bookworm GenericCloud image
✔ Creates VM with CPU, RAM, networking, and storage settings
✔ Supports DHCP or static IPs
✔ Cloud-Init support:
– Users, SSH keys, passwords
– Timezone
– Packages
✔ Optional TPM 2.0 + SecureBoot (OVMF)
✔ Optional real GPU passthrough and VirtIO GPU
✔ Optional disk resize
✔ Convert base VM into a template
✔ Create any number of clones from template
✔ Start clones after creation

Folder Structure
ANSIBLE_PROXMOX_VM/
  defaults/
    main.yml
  tasks/
    main.yml
  templates/
    cloudinit_userdata.yaml.j2
    cloudinit_vendor.yaml.j2
  README.md

Requirements
Proxmox API / Environment

This role runs on the Proxmox host via localhost, using qm CLI commands.
Therefore:

Ansible must have SSH access to the Proxmox node.

The user must have permission to run qm commands (root recommended).

Proxmox must have a storage pool such as local-lvm.

Debian Cloud Image

Downloaded automatically if not present:

/var/lib/vz/template/qemu/debian-genericcloud-amd64.qcow2

Variables (defaults/main.yml)
Base VM settings
vm_id: 150
hostname: debian-template-base
memory: 4096
cores: 4
bridge: vmbr0
storage: local-lvm
mac_address: "DE:AD:BE:EF:44:55"
cpu_type: host

Networking

Choose DHCP:

ip_mode: dhcp
ipconfig0: "ip=dhcp"


Or static:

ip_mode: static
ip_address: "192.168.1.60/24"
gateway: "192.168.1.1"
dns:
  - "1.1.1.1"
  - "8.8.8.8"

ipconfig0: "{{ 'ip=dhcp' if ip_mode == 'dhcp' else 'ip=' + ip_address + ',gw=' + gateway }}"

Cloud-Init user
ci_user: debian
ci_password: "SecurePass123"
ssh_key_path: "~/.ssh/id_rsa.pub"
timezone: "Europe/Berlin"

Disk
resize_disk: true
resize_size: "16G"

GPU passthrough
gpu_passthrough: false
gpu_device: "0000:01:00.0"
virtio_gpu: false

UEFI + TPM
enable_tpm: false

Templates + Clones
make_template: true
create_clones: true
clones:
  - id: 301
    hostname: app01
    ip: "192.168.1.81/24"
    gateway: "192.168.1.1"

How to Use
1. Include the role in your playbook
- hosts: proxmox
  become: true
  roles:
    - ANSIBLE_PROXMOX_VM


Or run directly:

ansible-playbook tasks/main.yml -i inventory

Clone Creation Flow

For each clone you define:

clones:
  - id: 301
    hostname: app01
    ip: "192.168.1.81/24"
    gateway: "192.168.1.1"


The role will:

Clone VM from template → qm clone 150 301

Set hostname + Cloud-Init netplan

Start VM

Cloud-Init Templates
User Data

templates/cloudinit_userdata.yaml.j2

Defines:

users

SSH key

password

timezone

package updates

custom command execution

Vendor Data

templates/cloudinit_vendor.yaml.j2

Defines:

default packages

DNS (optional)

Notes & Best Practices

Ensure Proxmox has snippets storage enabled under Datacenter → Storage.

If cloning fails with invalid IP, check formatting: "192.168.1.81/24".

Using both SSH keys + password login is possible (ssh_pwauth: true).

If GPU passthrough is enabled, ensure the host kernel is configured for IOMMU.

Future Improvements (optional)

Add API-based module support (community.general.proxmox) instead of CLI

Add validation for clone IDs

Automated post-deployment provisioning (Ansible SSH into clones)

Create a Galaxy-ready role