proxmox

An Ansible role for managing Proxmox host deployments.

Cloud Image VMs

The role can create VMs and 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_vm_storage: local-zfs

proxmox_vms:
  - name: fedora-base-cloud
    id: 1021
    type: template
    image: Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2

  - name: fedora-builder
    id: 1022
    type: vm
    image: Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2

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

export PROXMOX_HOST=pve.example.com
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_ID=ansible
export PROXMOX_TOKEN_SECRET='...'

You can smoke-test API token access from the controller with the same environment variables:

curl -k \
  -H "Authorization: PVEAPIToken=${PROXMOX_USER}\!${PROXMOX_TOKEN_ID}=${PROXMOX_TOKEN_SECRET}" \
  "https://${PROXMOX_HOST}:8006/api2/json/version"

curl -k \
  -H "Authorization: PVEAPIToken=${PROXMOX_USER}\!${PROXMOX_TOKEN_ID}=${PROXMOX_TOKEN_SECRET}" \
  "https://${PROXMOX_HOST}:8006/api2/json/access/users"

The role delegates Proxmox API calls to localhost by default, so proxmoxer and requests must be available to the Ansible controller Python. Override proxmox_api_delegate_to when the API module should execute somewhere else.

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.

Access Management

The role can create OpenID realms, users, API tokens, and ACL entries before VM tasks run.

proxmox_openid_realms:
  - realm: oidc
    issuer_url: https://id.example.com/application/o/proxmox/
    client_id: proxmox
    client_key: "{{ vault_proxmox_oidc_client_secret }}"
    autocreate: true
    username_claim: username

proxmox_users:
  - userid: ansible@pve
    enable: true

proxmox_api_tokens:
  - userid: ansible@pve
    tokenid: automation
    privsep: true

proxmox_acls:
  - path: /
    type: token
    ugid: ansible@pve!automation
    roleid: Administrator

OpenID realms and API tokens are managed through direct Proxmox API calls because community.proxmox does not currently provide dedicated modules for them. These direct API tasks require token authentication through proxmox_api_user, proxmox_api_token_id, and proxmox_api_token_secret, or their matching PROXMOX_* environment variables. API token secrets are only returned by Proxmox when a token is created, so store created secrets immediately in a vault or secret store.

The initial Proxmox API token is a bootstrap credential and must be created manually before running this role. Give that token only the privileges needed to create the configured realms, users, tokens, ACLs, and VMs; after the role creates a narrower automation token, prefer using that narrower token for normal runs.

Authentik Provider

Redirect RegEx ^https://[^.]+\.somehost\.sh:8006/?$

VM Management

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 VM. 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. VM defaults are stored as flat proxmox_vm_* variables. Values in each proxmox_vms item override those defaults for that VM.

VMs are managed with community.proxmox.proxmox_kvm. Each proxmox_vms item supports type: template or type: vm. The default is template, which creates the VM and then converts it to a Proxmox template. Set type: vm to leave it as a normal VM.

The role creates missing VMIDs by default and leaves module updates disabled unless explicitly enabled. This avoids reconciling disk and network settings on existing VMIDs unless the operator opts in with update: true, and keeps update_unsafe disabled unless explicitly enabled.

The primary disk and cloud-init drive currently need to be SCSI-backed, matching the default scsi0 and scsi1 layout. The cloud-init drive must use a different SCSI slot from the primary disk. Boot order defaults to the selected primary disk, so overriding disk does not require a matching boot_order override.

If the VMID already exists, the module leaves the VM configuration unchanged by default. Template items still ensure the VM is converted to a template. Set update: true on an item to update existing VM configuration.