banshee/virtualization-collection/virtualization/proxmox/https/replication

Storage replication of a Proxmox VE cluster, by its API

Returns, for each storage replication job of a Proxmox VE cluster (the ZFS replication of a guest to another node), its state, its failures in a row and the time since its last good run, read from the Proxmox VE API behind an API token. Three 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

The token goes in the header Authorization: PVEAPIToken=<token> of each request.

GET https://<host:address>:8006/api2/json/nodes: the nodes and their state.
GET https://<host:address>:8006/api2/json/nodes/<node>/replication for each node online: the jobs of the guests that node holds.

{"data": [{"id": "101-0", "guest": 101, "jobnum": 0, "target": "pve2", "schedule": "*/15", "last_sync": 1793062800, "last_try": 1793062800, "fail_count": 0, "duration": 4.2}]}

A job is named by its id, <guest id>-<job number> (101-0), as Proxmox VE names it.
The state is ok, failing when its failures in a row (fail_count) are above 0 (the job then also carries its error), or disabled for a job disabled in Proxmox VE, which returns its state alone and raises nothing.
The time since the last good run is the time since last_sync, in minutes; a job that never ran well has none.
A cluster without replication returns no value, and raises nothing.
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 stops it unreachable, a node that does not answer its jobs included, rather than leaving its jobs out.

The token comes from protocol:http:token, a secret variable: it only goes in the header. The answers are 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. A job is listed when the token may audit its guest (VM.Audit).

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 job
`failures`	Failures in a row	—	yes, per job
`lag`	Time since the last good run	min	yes, per job

Watches

Name	Title	Kind	Defaults	Checked by default
`failing`	Replication failing	state to avoid, on `state`	critical on `failing`, for 2 runs	yes
`late`	Replication late	above a threshold, on `lag`	warning above 60 min, critical above 240 min	yes
`missing`	Replication job missing	expected instances, on `state`	no job named: it raises nothing until names are set on the probe	no

Limits

The jobs of the guests of a node that is not online are not listed: "Node not online" of proxmox/https/nodes says it, and "Replication job missing" sees them gone.
"Replication late" counts from the last good run, whatever the schedule of the job: a job set to run once a day needs its own probe, with its own thresholds.
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 schema of the API viewer gives no field for this route; the fields are those its source writes (PVE/API2/Replication.pm, PVE/ReplicationState.pm) and its web interface reads (www/manager6/grid/Replication.js).