banshee/storage-collection/storage/truenas/https/api-v2.0/pools

Pools of a TrueNAS, by its REST API

Returns, for each ZFS pool of a TrueNAS, its health, its used space, its free space and its size, read from its REST API behind an API key. Five watches are offered, each one set on the probe.

Versions

Written for the REST API v2.0, which answers on TrueNAS CORE 12 and 13 and on TrueNAS SCALE up to 25.10. TrueNAS deprecated it in 25.04 and removed it in 26, for a JSON-RPC API over WebSocket that Keen does not speak. Hence the folder api-v2.0.

How it works

One GET https://<host:address>/api/v2.0/pool, the key in the header Authorization: Bearer. The API answers a list of pools:

[{"name": "tank", "status": "ONLINE", "healthy": true, "size": 3985729650688, "allocated": 1052266987520, "free": 2933462663168, ...}]

The health is status, in lower case: online, degraded, faulted, offline, unavail, removed, suspended.
The used space is allocated over size, as zpool list shows its capacity; sizes are in bytes, returned in GiB.
Only an online or degraded pool's space is read: an exported or failed pool may have none.
A code 401 or 403 stops the collector misconfigured (the key is refused); any other code but 200 stops it unreachable.

The key comes from protocol:http:token, a secret variable: it only goes in the header, never in a value returned. The answer is not secret, its body having carried none.

Prerequisites

The web interface of TrueNAS reachable from the poller in HTTPS, on port 443 of the host's address. Its certificate follows the TLS profile of the probe: the self-signed certificate TrueNAS makes at install is trusted by pinning its fingerprint (protocol:http:fingerprint) or by adding it under protocol:tls:authorities.
An API key in protocol:http:token. On a recent SCALE, a key belongs to a user: make it for a user of the read-only administrator role.

Outputs

Name	Label	Unit	Per instance
`health`	Health	—	yes, per pool
`used`	Used space	%	yes, per pool
`free`	Free space	GiB	yes, per pool
`size`	Size	GiB	yes, per pool

Watches

Name	Title	Kind	Defaults	Checked by default
`unhealthy`	Pool not online	expected value, on `health`	warning when the health is anything but `online`	yes
`failed`	Pool failed	state to avoid, on `health`	critical on `faulted`, `unavail`, `removed`, `suspended`	yes
`used`	Used space	above a threshold, on `used`	warning above 80 %, critical above 90 %	yes
`full-soon`	Full within a week	above a threshold, on `used`	warning above 99 %, trend 7 d	yes
`missing`	Pool missing	expected instances, on `health`	no pool named: it raises nothing until names are set on the probe	no

Limits

From TrueNAS 25.10.1, each call to the REST API raises a TrueNAS alert that a deprecated endpoint is used; storage/truenas/https/api-v2.0/alerts sees it too.
The address is written into the URL as is: an IPv6 address must be given as a name.
What a JSON null reads as in Keen is not settled yet: a pool whose size is null while online or degraded would stop the collector.
Not checked against a TrueNAS: the fields are those of pool.query in the API documentation of TrueNAS 25.10, which the REST GET /pool returns.