Ansible and Proxmox VE: drawing the line · Ansible

Proxmox VE is a full platform. It has a cluster, a storage model, a scheduler, a backup system, a permission system with tokens and roles, an HA manager and a REST API that exposes all of it. It is not a thing Ansible manages; it is a peer system Ansible talks to.

Which makes the boundary question sharp and answerable:

Proxmox owns the virtualisation platform. Ansible owns what runs inside the guests.

The platform decides which node a VM lives on, which storage backs its disk, when it is backed up, and whether HA restarts it elsewhere. Ansible decides that the guest has nginx, the right users, the right certificates and the right firewall rules — and does so identically whether that guest is on Proxmox, on a cloud provider, or on hardware.

That last clause is the load-bearing one, and this lesson keeps coming back to it.

The collection moved, and the module names are not what you would guess

community.proxmox is its own collection. Content that people remember living under community.general now has its own namespace, and a play copied from an old blog post will fail to resolve.

The two lifecycle modules are named asymmetrically and this catches everybody:

Guest type	Module
QEMU/KVM virtual machines	`community.proxmox.proxmox_kvm`
LXC containers	`community.proxmox.proxmox`

There is no proxmox_lxc. The container module is simply community.proxmox.proxmox, which reads like a collection-level catch-all and is not. Verified against the collection index: the LXC module page is proxmox_module.html and there is no proxmox_lxc_module.html.

Around them sit the operations you would expect — community.proxmox.proxmox_snap for snapshots, community.proxmox.proxmox_backup for backup jobs, community.proxmox.proxmox_vm_info for read-only queries — plus an inventory plugin and two connection plugins, community.proxmox.proxmox_pct_remote and community.proxmox.proxmox_qemu_api.

Read-only / Safeconfirm what your controller actually has— A play written against a collection that is not installed fails at module resolution, not at the API.

ansible-galaxy collection list community.proxmox
ansible-doc -t inventory community.proxmox.proxmox

Authenticate with a token, and scope it

Every module in the collection takes the same authentication parameters, and the choice you make here is the single most consequential security decision in a Proxmox play:

- name: Query the cluster, changing nothing
  hosts: localhost
  connection: local
  gather_facts: false
  vars:
    proxmox_auth:
      api_host: pve-01.example.com
      api_user: automation@pve
      api_token_id: ansible-readonly
      api_token_secret: "{{ vault_proxmox_token_secret }}"
      validate_certs: true
  tasks:
    - name: List virtual machines
      community.proxmox.proxmox_vm_info:
        <<: "{{ proxmox_auth }}"
      register: vms
      no_log: true

api_password also exists, and using it means putting a real login credential — usually one that a human also uses — into automation. A token is better in four specific ways, all of which matter during an incident:

It can be scoped by role and path, so an inventory token can be permitted to read guest configuration and nothing else.
It can be revoked independently of the account, without locking a person out.
It appears distinctly in the cluster’s task log, so “who created this VM” has an answer that is not “the shared automation account”.
It does not expire when a human changes their password, which is how automation breaks at the worst possible moment.

The Proxmox course covers token creation and rotation properly in REST API automation and API security and rotation, and the Ansible-facing view in Ansible on Proxmox. This lesson does not reteach them.

validate_certs and the cluster certificate

A fresh Proxmox cluster presents a self-signed certificate, and the first thing that happens when someone points automation at it is a TLS verification failure. The fast fix — validate_certs: false — is a permanent decision made in ten seconds.

It means the automation account’s token is sent to whatever answers on that address. On a management network that feels acceptable until the day it is not, and there is no alert when it stops being acceptable.

The correct fix is to give the cluster a certificate the controller trusts, which the Proxmox course covers under certificate installation and rotation. Where that genuinely cannot happen yet, pin the CA explicitly rather than disabling verification, and record the exception where your team records exceptions — the intentional drift exceptions lesson is about exactly this kind of documented deviation.

Inventory from the cluster

The inventory plugin turns the cluster into a host list, which is the single most valuable integration in the collection because it removes the hand-maintained file that inventory as the blast radius map identifies as the thing everyone forgets to update.

# inventory/proxmox.yml
plugin: community.proxmox.proxmox
url: https://pve-01.example.com:8006
user: automation@pve
token_id: ansible-inventory
token_secret: "{{ lookup('ansible.builtin.env', 'PROXMOX_TOKEN_SECRET') }}"
validate_certs: true
want_facts: true
group_prefix: proxmox_
keyed_groups:
  - key: proxmox_tags_parsed
    prefix: tag

Then inspect it before you ever run a play against it:

Read-only / Safethe mandatory first step with any dynamic inventory— Both commands query the source and print the result. Neither runs a task against anything.

ansible-inventory -i inventory/proxmox.yml --graph
ansible-inventory -i inventory/proxmox.yml --list | head -50

Three properties of this inventory deserve conscious handling, and Part XXIX treats each generally:

It is volatile. A VM created five minutes ago is in your host list now. A play with hosts: all and no --limit reaches machines that did not exist when the change was reviewed. The unexpected hosts lesson is the one to reread before running anything broad against a cluster inventory.

It has a dependency. If the API is unreachable, the inventory is empty, and an empty inventory is not an error by default — it is a run that targets nothing and reports success. The empty target versus error distinction is the guard.

want_facts: true costs API calls. It fetches configuration for every guest at inventory time, before any task runs, which on a large cluster is the slowest part of a short play. Turn it on when you group on guest configuration, and leave it off when you do not.

Guest lifecycle is a severity conversation

The lifecycle modules do exactly what they say, and the severity of the same module varies enormously with one parameter:

Operation	Severity	Note
`proxmox_vm_info`	`READ-ONLY`	Query only
`proxmox_kvm` with `state: present`	`CONFIGURATION`	Creates or updates a definition
`proxmox_kvm` with `state: stopped`	`SERVICE-IMPACT`	The guest goes away
`proxmox_snap`	`CONFIGURATION`	Consumes storage; check free space first
`proxmox_kvm` with `state: absent`	`DATA-LOSS-RISK`	Removes the guest and its referenced volumes

That last row is the one to internalise. Per the module documentation, volumes referenced in the guest configuration are always removed when the guest is destroyed; a separate destroy_unreferenced_disks option, which defaults to false, governs the disks that are not referenced.

So the safe-sounding reading — “it removes the VM definition, the disks stick around” — is wrong for exactly the disks that matter. A play that loops over a list of vmid values with state: absent and a variable that resolved to the wrong list is not recoverable from the cluster; it is recoverable from backups, if there are any, which is the entire subject of the Proxmox course’s disaster-recovery part.

Read-only / Safewhat any destroy play must be preceded by— Prints the resolved host list and the tasks that would run. Executes nothing.

ansible-playbook -i inventory/proxmox.yml decommission.yml --list-hosts
ansible-playbook -i inventory/proxmox.yml decommission.yml --list-tasks

The rule that the boundary exists to protect

Here is the failure the boundary prevents, in one sentence: a guest whose configuration depends on which hypervisor it landed on cannot be rebuilt anywhere else.

It happens gradually and always for a good reason at the time. A role reads proxmox_node from the inventory facts and picks a different NTP server per node. A template branches on the storage backend because one node has faster disks. A firewall rule is written against the bridge name that happens to exist on the node where the guest was created.

Each of those is defensible in isolation. Together they mean the guest is not reproducible: migrate it, and it is subtly misconfigured; rebuild it on another cluster during a disaster, and it does not come up.

The discipline is to keep hypervisor facts out of guest roles entirely. Where a guest genuinely needs to differ — a database that must not share a node with its replica — express that as a property of the guest in inventory (a group, a variable, a tag), not as a lookup of where the hypervisor put it. The conditional logic that belongs in inventory lesson is the general form of this argument; Proxmox is where it bites hardest, because the platform is so willing to tell you where things are.

Under the hood

Why do the Proxmox modules run on the controller rather than on the hypervisor?

Because they are API clients. Every one of them takes api_host and speaks HTTPS to the cluster’s REST endpoint. There is nothing to copy to a managed node, and the “host” a proxmox_kvm task is associated with is essentially a label — which is why these plays are written with connection: local, hosts: localhost, or delegate_to: localhost, exactly as the API lesson earlier in this part describes.

Two consequences follow, and both are the ones from that lesson:

The host loop multiplies API calls. A proxmox_snap task inside a play over 200 guests issues 200 API calls to one cluster, in parallel up to forks. Proxmox schedules tasks per node and a burst of concurrent operations will queue, time out, or fail in a way that looks like a module defect. throttle on the task, sized to the cluster rather than to the inventory, is the control.

The cluster is the blast radius, not the host list. A token with sufficient rights can destroy a guest that is not in your inventory at all. --limit does not constrain an API call.

The connection plugins are the exception that proves the shape. community.proxmox.proxmox_pct_remote executes tasks inside an LXC container by way of the hypervisor’s own container tooling, over an SSH session to the node. That is genuinely useful for bootstrapping a container that has no network configuration yet — the raw module and bootstrapping problem, solved through the platform instead of around it. It is a bootstrap path, not a steady-state one: once the guest has SSH, address it as a host like any other, because that is what keeps the role portable.

What happens if the API token has fewer rights than the play needs?

You get a failure that looks like a bug in the collection, and the search results will send you the wrong way.

The module returns the API’s error, which is typically a permission denial naming an internal path rather than an operation you recognise. The task name says “Create the application VM”; the error says something about a path under /nodes/ and a privilege you have never heard of. The natural next move is to search the module name plus the error string, which finds issue reports from people with unrelated problems.

The diagnosis is quicker from the other end:

Reproduce the smallest read. A proxmox_vm_info task with the same token. If that fails too, it is authentication, not privileges.
Check the token’s role assignment and path in the cluster, not in the playbook. Proxmox permissions are path-scoped, so a token can be able to create a VM on one node and not another, and a play that works today fails when the scheduler picks a different node.
Check validate_certs and the actual TLS error separately. A certificate failure and a permission failure both surface as “the module did not work” at first glance.

The general lesson is the one from the API lesson: with an API target, the permission model of the remote system is part of your automation’s configuration, and it lives somewhere your repository does not. Recording which token, which role and which path a play requires — in the play, as a comment or in the role’s documentation — turns a thirty-minute diagnosis into a thirty-second one.

Knowledge check

Why this matters

Proxmox is the friendliest system in this part to automate, and that is precisely the risk. The API is coherent, the collection is good, and the inventory plugin removes a real chore. Nothing pushes back when you keep going.

So the boundary has to be chosen rather than discovered. Left to drift, an Ansible repository gradually absorbs the platform: it creates guests, schedules their backups, manages their snapshots, decides which node they live on — and every one of those decisions is now expressed twice, once in the cluster and once in a playbook, with no mechanism to notice when the two disagree.

The version of this that ends badly is not dramatic. It is a Tuesday afternoon during a hardware failure, when a guest is migrated by the HA manager to a node the automation did not expect, and the next convergence run “corrects” the placement by moving it back. Neither system is broken. Nobody wrote a bug. There are simply two owners for one fact.

The next lesson takes that same question — who owns the existence and placement of a resource — and asks it about the tool that was designed specifically to answer it.