banshee/virtualization-collection/virtualization/proxmox/https/nodes

Nodes of a Proxmox VE cluster, by its API

Returns, for each node of a Proxmox VE cluster, or for a single Proxmox VE server, its state, its processor and memory in use, and its load over one minute, read from the Proxmox VE API behind an API token. Five watches are offered, each one set on the probe.

Versions

Proxmox VE from 6.2, the first to give API tokens; the routes read have kept their form since. Generic: no folder of version.

How it works

GET https://<host:address>:8006/api2/json/nodes, the token in the header Authorization: PVEAPIToken=<token>:

{"data": [{"node": "pve1", "status": "online", "cpu": 0.0832, "maxcpu": 16, "mem": 27596369920, "maxmem": 67350208512, "uptime": 2312890}]}

GET https://<host:address>:8006/api2/json/nodes/<node>/status for each node online, for its load:

{"data": {"loadavg": ["0.52", "0.61", "0.58"], "cpu": 0.0832, "memory": {...}, ...}}

A node is named as the cluster names it.
The state is Proxmox VE's: online, offline, unknown. A node that is not online returns its state alone.
The processor in use is cpu, a fraction of all the node's processors, in %; the memory in use is mem over maxmem.
The load is the first of loadavg, over one minute. A node that answers its status with another code than 200, gone offline between the two readings, returns no load.
No node at all stops the collector misconfigured. A code 401 (the token refused) or 403 (a privilege missing) stops it misconfigured; any other code but 200 on the list stops it unreachable.

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

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> (monitoring@pve!banshee= and the secret Proxmox VE shows once), of a user given the role PVEAuditor, read-only, on /. On a node: - pveum user add monitoring@pve - pveum acl modify / --roles PVEAuditor --users monitoring@pve - pveum user token add monitoring@pve banshee --privsep 0, the token taking the rights of its user; a token with privilege separation (--privsep 1) needs the role on itself too: pveum acl modify / --roles PVEAuditor --tokens 'monitoring@pve!banshee'.

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 node
`cpu-busy`	Overall processor usage	%	yes, per node
`memory-used-percent`	Used memory	%	yes, per node
`load-1`	Load, 1 minute	—	yes, per node

Watches

Name	Title	Kind	Defaults	Checked by default
`not-online`	Node not online	expected value, on `state`	critical when the state is anything but `online`	yes
`cpu-high`	Processor saturated	above a threshold, on `cpu-busy`	warning above 85 %, critical above 95 %, for 3 runs	yes
`memory-high`	Memory saturated	above a threshold, on `memory-used-percent`	warning above 90 %, critical above 95 %, for 3 runs	yes
`load-high`	High load	above a threshold, on `load-1`	none: the load that counts depends on the number of processors of the node	no
`missing`	Node missing	expected instances, on `state`	no node named: it raises nothing until names are set on the probe	no

Limits

The probe reads the cluster through the node it is set on: that node down, the collector stops unreachable, and the other nodes are not seen. A second probe on another node covers it.
The memory in use counts the ZFS cache (ARC), which Linux gives back on demand: a node with ZFS runs high by design.
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 routes and fields are those of the API viewer of Proxmox VE (pve-docs/api-viewer) and of its source (PVE/API2Tools.pm, which writes the list of the nodes).