community.proxmox.proxmox_qemu_api connection – Connect to QEMU VMs via the Proxmox guest agent API

Note

This connection plugin is part of the community.proxmox collection (version 2.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.proxmox. You need further requirements to be able to use this connection plugin, see Requirements for details.

To use it in a playbook, specify: community.proxmox.proxmox_qemu_api.

New in community.proxmox 2.0.0

Synopsis

  • Execute commands and transfer files through the Proxmox VE QEMU Guest Agent API.

  • Does not require SSH or network connectivity to the VM.

  • Requires the QEMU Guest Agent (qemu-guest-agent) to be installed and running inside the target VM.

  • Talks directly to the Proxmox REST API using proxmoxer, avoiding the overhead and limitations of shelling out to qm guest exec over SSH.

  • Linux guests only. Windows guest support is not implemented.

Requirements

The below requirements are needed on the local controller node that executes this connection.

  • proxmoxer >= 2.3.0

  • requests

Parameters

Parameter

Comments

api_host

string / required

Proxmox VE API hostname or IP address.

Configuration:

  • Environment variable: PROXMOX_HOST

  • Variable: proxmox_api_host

api_password

string

Password for api_user.

Required when api_user is set.

Configuration:

api_port

integer

Proxmox VE API port.

Default: 8006

Configuration:

  • Environment variable: PROXMOX_PORT

  • Variable: proxmox_api_port

api_token_id

string

API token ID (for example user@pam!token_name).

Used with api_token_secret.

Mutually exclusive with api_user.

Configuration:

api_token_secret

string

API token secret UUID.

Required when api_token_id is set.

Configuration:

api_user

string

Proxmox VE API user (for example root@pam).

Used with api_password to obtain an authentication ticket.

Mutually exclusive with api_token_id.

Configuration:

  • Environment variable: PROXMOX_USER

  • Variable: proxmox_api_user

connect_timeout

integer

Maximum number of seconds to wait for the guest agent to become responsive.

The plugin polls the agent every 5 seconds during connection.

Default: 60

Configuration:

  • Variable: proxmox_connect_timeout

executable

string

Shell executable for command execution on the guest.

Default: "/bin/sh"

Configuration:

  • Variable: ansible_executable

node

string / required

Proxmox node name where the VM resides.

Configuration:

remote_tmp

string

Temporary directory on the guest for staging chunked file transfers.

Must be writable by the guest agent process (typically root).

Only used when transferring files larger than 45000 bytes.

Default: "/tmp"

Configuration:

  • Variable: proxmox_remote_tmp

validate_certs

boolean

Validate PVE API TLS certificates.

Choices:

  • false

  • true ← (default)

Configuration:

vmid

integer / required

Target QEMU VM ID.

Configuration:

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Notes

Note

  • The API user or token requires guest agent privileges on the target VM. On PVE 8, this is VM.Monitor. On PVE 9+, VM.Monitor was replaced with fine-grained privileges -- VM.GuestAgent.Unrestricted covers command execution, VM.GuestAgent.FileRead and VM.GuestAgent.FileWrite cover file transfers. Alternatively, VM.GuestAgent.Unrestricted alone grants access to all guest agent operations.

  • This plugin requires the QEMU Guest Agent to be installed and running inside the VM. If the agent is not responsive, the connection will fail after connect_timeout seconds.

  • File transfers use the PVE guest agent file-read/file-write API, which has a per-call size limit of approximately 45000 bytes. Files larger than this are automatically split into chunks using split on the guest and reassembled on the controller or guest.

  • Guest requirements: qemu-guest-agent must be running. File transfers additionally require cat, split, ls, and rm (coreutils).

  • Works with the community.proxmox.proxmox inventory plugin. Set ansible_connection=community.proxmox.proxmox_qemu_api on discovered hosts.

Examples

- name: Static inventory example
  # inventory.yml
  # all:
  #   hosts:
  #     my-vm:
  #       ansible_connection: community.proxmox.proxmox_qemu_api
  #       proxmox_vmid: 100
  #       ansible_host: my-vm.example.com
  #   vars:
  #     proxmox_api_host: pve-1.example.com
  #     proxmox_api_port: 8006
  #     proxmox_api_token_id: automation@pve!ansible
  #     proxmox_api_token_secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  #     proxmox_node: pve-1
  hosts: my-vm
  gather_facts: true
  tasks:
    - name: Install a package
      ansible.builtin.apt:
        name: curl
        state: present

    - name: Copy a configuration file
      ansible.builtin.copy:
        src: app.conf
        dest: /etc/app/app.conf

    - name: Run a command
      ansible.builtin.command:
        cmd: systemctl restart app

Authors

  • Ian Williams (@aph3rson)