proxmox

An Ansible role for managing Proxmox host deployments.

Cloud Image Templates

The role can create VM templates from cloud images that have already been uploaded to a Proxmox host.

proxmox_api_host: pve.example.com
proxmox_api_user: root@pam
proxmox_api_token_id: ansible
proxmox_api_token_secret: "{{ vault_proxmox_api_token_secret }}"
proxmox_node: pve

proxmox_iso_dir: /var/lib/vz/template/iso
proxmox_iso_upload: true
proxmox_template_storage: local-zfs
proxmox_template_cloudinit_drive: scsi1

proxmox_templates:
  - name: fedora-base-cloud
    id: 1021
    image: Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2
    memory: 4096
    cpu: host
    numa: true
    cores: 2
    sockets: 2
    net0: virtio,bridge=vmbr0
    scsihw: virtio-scsi-pci

The Proxmox API settings can also be supplied from the controller environment, which keeps credentials out of playbooks:

export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_ID=ansible
export PROXMOX_TOKEN_SECRET='...'

The role omits unset API credential parameters, allowing community.proxmox.proxmox_kvm to read its supported PROXMOX_* environment variables directly. proxmox_api_host defaults to inventory_hostname, and proxmox_api_port defaults to 8006; override them through inventory or play variables when needed. API tokens are preferred over passwords for operator-local credentials.

The image value can be either a filename under proxmox_iso_dir or an absolute path. When proxmox_iso_upload is enabled, the role uploads the image from files/proxmox/iso in the role or from <inventory-root>/files/proxmox/iso before creating the template. Upload tasks inherit privilege escalation from the play. Configure become, become_method, and related settings at the playbook or inventory level when proxmox_iso_dir requires elevated access. Template defaults are stored as flat proxmox_template_* variables. Values in each proxmox_templates item override those defaults for that template.

Templates are managed with community.proxmox.proxmox_kvm. The role uses update: true and update_unsafe: true by default so disk and network settings can be reconciled by the module. The primary disk and cloud-init drive currently need to be SCSI-backed, matching the default scsi0 and scsi1 layout.

If the VMID already exists, the module attempts to update it to the requested configuration and then ensure it is a template.