banshee/virtualization-collection/virtualization/proxmox/https/backup-tasks

Last backup job of each node of a Proxmox VE cluster, by its API

Returns, for each node of a Proxmox VE cluster, or for a single Proxmox VE server, the result of its last backup job (vzdump) and the time since it ended, 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>/tasks?typefilter=vzdump&limit=1 for each node online. The node reads its task archive from the newest: the answer is its last backup job that ended, a running one left out:

{"data": [{"upid": "UPID:pve1:…", "type": "vzdump", "status": "OK", "starttime": 1793062800, "endtime": 1793066412, "user": "root@pam"}]}

A node is named as the cluster names it.
The result is ok for the status OK, warnings for WARNINGS: <n> (a guest backed up with warnings), and failed for anything else: the status is then the error that ended the job (job errors, interrupted by signal).
The time since the job ended is in hours.
A node that is not online, one that never ran a backup job, or one that answers its tasks with another code than 200 (gone offline between the two readings) returns no value.
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 of the nodes stops it unreachable.

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. The backup jobs run as root@pam: seeing the tasks of another account asks Sys.Audit on the node, which PVEAuditor gives; without it, the list is empty and the collector returns nothing.

Variables

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

Outputs

Name	Label	Unit	Per instance
`result`	Result of the last backup job	—	yes, per node
`age`	Time since the last backup job	h	yes, per node

Watches

Name	Title	Kind	Defaults	Checked by default
`failed`	Backup job failed	state to avoid, on `result`	warning on `warnings`, critical on `failed`	yes
`old`	No backup job lately	above a threshold, on `age`	warning above 30 h	no
`missing`	Node without backup job	expected instances, on `result`	no node named: it raises nothing until names are set on the probe	no

Limits

Only the last job of each node is judged: a job that failed, followed by one that succeeded, raises nothing. Which guest failed in a job is read in its log, in Proxmox VE.
A job run by hand counts like a scheduled one.
The age of each guest's newest backup is the collector proxmox/https/backups, which sees a guest left out of a job that itself succeeded.
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, fields and statuses are those of the API viewer of Proxmox VE (pve-docs/api-viewer) and of its source (PVE/API2/Tasks.pm, which reads the archive from the newest).