Ansible Proxmox Authentication

API Token Setup

Create a dedicated Ansible user and API token on Proxmox:

# On Proxmox node
pveum user add ansible@pve
pveum aclmod / -user ansible@pve -role PVEAdmin
pveum user token add ansible@pve mytoken --privsep 0

Note: --privsep 0 gives the token the same permissions as the user.

Playbook Variables

Direct in playbook (NOT recommended)

vars:
  proxmox_api_host: proxmox.example.com
  proxmox_api_user: ansible@pve
  proxmox_api_token_id: mytoken
  proxmox_api_token_secret: "{{ vault_proxmox_token }}"

Group vars with vault

# group_vars/all.yml
proxmox_api_host: proxmox.example.com
proxmox_api_user: ansible@pve
proxmox_api_token_id: mytoken

# group_vars/secrets.yml (ansible-vault encrypted)
proxmox_api_token_secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Environment variables

export PROXMOX_HOST=proxmox.example.com
export PROXMOX_USER=ansible@pve
export PROXMOX_TOKEN_ID=mytoken
export PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# In playbook
vars:
  proxmox_api_host: "{{ lookup('env', 'PROXMOX_HOST') }}"
  proxmox_api_user: "{{ lookup('env', 'PROXMOX_USER') }}"
  proxmox_api_token_id: "{{ lookup('env', 'PROXMOX_TOKEN_ID') }}"
  proxmox_api_token_secret: "{{ lookup('env', 'PROXMOX_TOKEN_SECRET') }}"

Reusable Auth Block

Define once, reuse across tasks:

vars:
  proxmox_auth: &proxmox_auth
    api_host: "{{ proxmox_api_host }}"
    api_user: "{{ proxmox_api_user }}"
    api_token_id: "{{ proxmox_api_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    validate_certs: false  # For self-signed certs

tasks:
  - name: Create VM
    community.general.proxmox_kvm:
      <<: *proxmox_auth
      node: joseph
      vmid: 300
      name: myvm
      state: present

  - name: Start VM
    community.general.proxmox_kvm:
      <<: *proxmox_auth
      vmid: 300
      state: started

TLS Certificate Handling

Self-signed certificates

community.general.proxmox_kvm:
  # ... auth params ...
  validate_certs: false

Custom CA

export SSL_CERT_FILE=/path/to/ca-bundle.crt

Or in ansible.cfg:

[defaults]
# For urllib3/requests
ca_cert = /path/to/ca-bundle.crt

Minimum Required Permissions

For full VM/container management:

Permission	Path	Purpose
VM.Allocate	/	Create VMs
VM.Clone	/	Clone templates
VM.Config.*	/	Modify VM config
VM.PowerMgmt	/	Start/stop VMs
VM.Snapshot	/	Create snapshots
Datastore.AllocateSpace	/	Allocate disk space
Datastore.Audit	/	List storage

Or use the built-in PVEAdmin role for full access.

Troubleshooting Auth Issues

# Debug task to test connection
- name: Test Proxmox API connection
  community.general.proxmox_kvm:
    api_host: "{{ proxmox_api_host }}"
    api_user: "{{ proxmox_api_user }}"
    api_token_id: "{{ proxmox_api_token_id }}"
    api_token_secret: "{{ proxmox_api_token_secret }}"
    validate_certs: false
    vmid: 100
    state: current
  register: result
  ignore_errors: true

- name: Show result
  ansible.builtin.debug:
    var: result

Common errors:

Error	Cause	Fix
401 Unauthorized	Bad token	Verify token ID format: `user@realm!tokenname`
403 Forbidden	Insufficient permissions	Check user ACLs with `pveum user permissions ansible@pve`
SSL certificate problem	Self-signed cert	Set `validate_certs: false`
Connection refused	Wrong host/port	Verify API URL (port 8006)

3.6 KiB Raw Permalink Blame History