banshee/virtualization-collection/virtualization/proxmox/https/cluster

Cluster of Proxmox VE, by its API

Returns whether a Proxmox VE cluster has quorum, how many of its nodes are online out of how many, and whether each node is online, read from the Proxmox VE API behind an API token. A single Proxmox VE server, without cluster, reads standalone. Three watches are offered, each one set on the probe.

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/status, the token in the header Authorization: PVEAPIToken=<token>:

{"data": [{"type": "cluster", "id": "cluster", "name": "prod", "quorate": 1, "nodes": 3, "version": 7}, {"type": "node", "id": "node/pve1", "name": "pve1", "online": 1, "local": 1, "nodeid": 1, "ip": "192.0.2.11"}]}

The quorum is yes when the cluster entry says quorate 1, no otherwise, and standalone when there is no cluster entry (a server without cluster).
A node is named as the cluster names it; its state is online when its entry says online 1, offline otherwise.
"Nodes online" and "Nodes" count the node entries.
No node at all stops the collector misconfigured. A code 401 (the token refused) or 403 (a privilege missing: Sys.Audit on /) stops it 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.

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.

Variables

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

Outputs

Name	Label	Unit	Per instance
`quorum`	Quorum	—	no
`online`	Nodes online	—	no
`nodes`	Nodes	—	no
`state`	State	—	yes, per node

Watches

Name	Title	Kind	Defaults	Checked by default
`no-quorum`	Cluster without quorum	state to avoid, on `quorum`	critical on `no`	yes
`offline`	Node offline	state to avoid, on `state`	critical on `offline`	yes
`missing`	Node missing	expected instances, on `state`	no node named: it raises nothing until names are set on the probe	no

Limits

The cluster is seen by the node the probe is set on: a node cut from the others sees itself without quorum, and the others offline, which is what the probe then says. That node down, the collector stops unreachable.
The node removed from the cluster leaves the list: only "Node missing" sees it.
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/API2/Cluster.pm). The schema says quorate and online are booleans; the collector reads them as the 1 and 0 the cluster file system gives, which is not verified on a cluster.