banshee/virtualization-collection/virtualization/proxmox/https/guests

Guests of a Proxmox VE cluster, by its API

Returns, for each virtual machine and container of a Proxmox VE cluster, or of a single Proxmox VE server, its state, its name, the node it runs on and its high-availability state, read from the Proxmox VE API behind an API token. Four watches are offered; the two of the expected state are not checked by default: which guests must run and which must stay stopped, only the administrator knows.

Versions

Proxmox VE from 6.2, the first to give API tokens; the route read has kept its form since. Generic: no folder of version.

How it works

One GET https://<host:address>:8006/api2/json/cluster/resources?type=vm, the token in the header Authorization: PVEAPIToken=<token>:

{"data": [{"id": "qemu/101", "vmid": 101, "name": "web01", "type": "qemu", "node": "pve1", "status": "running", "template": 0, "hastate": "started", "cpu": 0.02, "mem": 2147483648, "maxmem": 4294967296}]}

A guest is named by its id (VMID: 101), unique in the cluster. Its name is an output: two guests may share a name, and Proxmox VE stops giving the name of a guest whose node is down, the moment it must still be seen under the same instance.
The state is Proxmox VE's: running, stopped, and unknown for the guest of a node down; a template reads template.
The node is the one the guest is on.
The high availability is Proxmox VE's state of the guest, given only for a guest under high availability: started, stopped, request_stop, freeze, migrate, relocate, fence, recovery, error, queued, disabled, ignored.
A cluster with no guest returns no value, and raises nothing. A code 401 (the token refused) or 403 (a privilege missing) stops the collector misconfigured; any other code but 200 stops it unreachable.

The token comes from protocol:http:token, a secret variable: it only goes in the header. The answer is not secret.

Use

The probe has one selection for all its watches. To watch both the guests that must run and those that must stay stopped, put two probes of this collector on the node:

one whose selection is "Only" the guests that must run (101, 2*), with "Guest not running" checked;
one whose selection is "Only" the guests that must stay stopped, with "Guest not stopped" checked.

A guest of a node down reads unknown, and raises "Guest not running".

Prerequisites

The address of any node of the cluster as the host's address, reachable from the poller in HTTPS on port 8006, or the port set in the variable proxmox:port when a proxy serves the API on another. The certificate of the node is issued by the cluster's own authority: trust it by that authority (/etc/pve/pve-root-ca.pem) under protocol:tls:authorities, by its pinned fingerprint in protocol:http:fingerprint, or by the first fingerprint trusted in the tab "Security".
An API token in protocol:http:token, written <user>@<realm>!<token id>=<secret>, of a user given the role PVEAuditor, read-only, on /: see the collector proxmox/https/nodes for the three pveum commands. A guest the token may not audit (VM.Audit) is not listed.

Variables

Name	Label	Says	Default
`proxmox:port`	API port	the port of the Proxmox VE API	`8006`

Outputs

Name	Label	Unit	Per instance
`state`	State	—	yes, per guest
`name`	Name	—	yes, per guest
`node`	Node	—	yes, per guest
`ha`	High availability	—	yes, per guest

Watches

Name	Title	Kind	Defaults	Checked by default
`not-running`	Guest not running	expected value, on `state`	critical when the state is anything but `running`	no
`not-stopped`	Guest not stopped	expected value, on `state`	warning when the state is anything but `stopped`	no
`ha-error`	High availability in error	state to avoid, on `ha`	warning on `fence`, `recovery`; critical on `error`	yes
`missing`	Guest missing	expected instances, on `state`	no guest named: it raises nothing until ids are set on the probe	no

Limits

A virtual machine paused reads running: the list does not tell them apart.
The address is written into the URL as is: an IPv6 address must be given as a name.
Not checked against a Proxmox VE: the route and fields are those of the API viewer of Proxmox VE (pve-docs/api-viewer) and of its source (PVE/API2Tools.pm, which writes each guest from the figures its node reports; PVE/API2/Cluster.pm, which adds the high-availability state). The states of high availability are those of the Proxmox VE HA manager, not verified one by one.