banshee/virtualization-collection/virtualization/proxmox/https/storage

Storage of a Proxmox VE cluster, by its API

Returns, for each storage of a Proxmox VE cluster, or of a single Proxmox VE server, as each node sees it, whether it is available, its used space, its free space and its size, read from the Proxmox VE API behind an API token. Four 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/resources?type=storage, the token in the header Authorization: PVEAPIToken=<token>:

{"data": [{"id": "storage/pve1/local-zfs", "storage": "local-zfs", "node": "pve1", "type": "storage", "status": "available", "disk": 107374182400, "maxdisk": 429496729600, "shared": 0, "content": "images,rootdir", "plugintype": "zfspool"}]}

A storage is seen from each node that has it enabled, a shared one (NFS, Ceph, Proxmox Backup Server) as well: it is named <node>/<storage> (pve1/local-zfs, pve2/nfs-backup), so that a share one node no longer mounts is seen.
The state is available when the node reports the storage, unknown otherwise: inactive, unreachable, or the node itself down. A storage that is not available returns its state alone.
The used space is disk over maxdisk; sizes are in bytes, returned in GiB.
No storage 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.

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. A storage the token may not audit (Datastore.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 storage and node
`used`	Used space	%	yes, per storage and node
`free`	Free space	GiB	yes, per storage and node
`size`	Size	GiB	yes, per storage and node

Watches

Name	Title	Kind	Defaults	Checked by default
`not-available`	Storage not available	expected value, on `state`	critical when the state is anything but `available`	yes
`used`	Used space	above a threshold, on `used`	warning above 85 %, critical above 95 %	yes
`full-soon`	Full within a week	above a threshold, on `used`	warning above 99 %, trend 7 d	yes
`missing`	Storage missing	expected instances, on `state`	no storage named: it raises nothing until names are set on the probe	no

Limits

A storage disabled on a node is not listed for it, and raises nothing.
A node down makes each of its storages unknown: "Storage not available" raises with "Node not online" of proxmox/https/nodes.
A shared storage is counted once per node: its space is the same in each.
The space of a thin pool (LVM-thin, ZFS) is the space written, not the space promised to the disks of the guests.
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 storage and its status).