Permissions

cv4pve-metrics-exporter reads the cluster through the API, so what it exports is exactly what its account is allowed to see. Use a dedicated user with an API token rather than root@pam.

User and token

Create a user or an API token and assign it the privileges below, on /. The built-in PVEAuditor role covers all of them.

Tokens with privilege separation

A token with privilege separation (the default in the web UI) does not inherit the user’s permissions: grant the role to the token too, or cv4pve-metrics-exporter sees an empty cluster.

Privileges

Privilege	On	Used for	Without it
Sys.Audit	/	Cluster status, HA, backup coverage, node status and version, SMART, QEMU balloon	No cluster and node metrics and no per-node calls; HA, backup coverage and SMART fail
VM.Audit	/vms	VMs, containers and their replication jobs	Guests and their replication jobs are missing
Datastore.Audit	/storage	Storages	Storages are missing

All three are read-only, unlike the backup and update privileges cv4pve-report and cv4pve-diag can use: the exporter needs nothing more than PVEAuditor. The balloon is read with info balloon on the QEMU monitor, a POST that Proxmox VE allows with Sys.Audit: it requires Sys.Modify only for the monitor commands that change the VM.

How missing privileges are reported

Proxmox VE answers a request the caller is only partly entitled to by filtering the response, not by failing it. /cluster/resources drops the guests and storages you cannot audit, and returns 200 OK: a guest without VM.Audit has no metrics at all, and nothing tells you it is missing. If the numbers look too small, check the privileges first.

A call that fails outright, such as the node status without Sys.Audit, is counted in cv4pve_scrape_errors_total and, with ApiInstrumentation on, in cv4pve_api_request_errors_total with its endpoint, see Exporter metrics. The other metrics are still exported.