Proxmox VE data source for Grafana

Query your Proxmox Virtual Environment cluster directly from Grafana. Chart CPU, memory, disk and network for nodes, virtual machines, containers and storage, and pull a live table of every resource in the cluster.

Built and maintained by Ridgeline Technologies, LLC.

What you get

• Node metrics — CPU, IO wait, load average, memory, swap, root filesystem and network throughput.
• VM and container metrics — CPU, memory, disk usage, disk read/write and network throughput for both QEMU guests and LXC containers.
• Storage metrics — used and total capacity per storage backend.
• Cluster resource table — the current state of every node, guest and storage in one table, ready for a stat or table panel.
• Dropdowns that populate themselves — nodes, guests and storages are read from your cluster as you build the query.
• Sensible units out of the box — CPU renders as a percentage, memory and disk as bytes, network as bytes per second, with no per-panel configuration.
• Dashboard variable support — the node, guest and storage fields accept $variable syntax, and query variables can list your nodes, guests and storages. The bundled dashboards use them and work on any cluster.

Credentials are held encrypted by Grafana and used only by the plugin's backend. They are never exposed to the browser, and the plugin makes read-only calls.

Requirements

• Grafana 12.3 or later.
• Network access from the Grafana server to your Proxmox VE API (TCP 8006 by default).
• A Proxmox API token with at least the PVEAuditor role.

Setup

1. Create a read-only API token in Proxmox

In the Proxmox web UI:

1. Datacenter → Permissions → Users → Add. Create a user such as grafana, realm Proxmox VE authentication server (pve). No password is needed for token access.
2. Datacenter → Permissions → Add → User Permission. Set Path to /, User to grafana@pve, Role to PVEAuditor, and leave Propagate checked.
3. Datacenter → Permissions → API Tokens → Add. Pick the grafana@pve user, give the token an ID such as readonly, and uncheck Privilege Separation so the token inherits the user's PVEAuditor role. (If you prefer to leave privilege separation on, grant the token its own PVEAuditor permission on / instead.)
4. Copy the secret shown in the confirmation dialog. Proxmox displays it exactly once.

You now have two values: a token ID like grafana@pve!readonly and a secret UUID.

2. Add the data source in Grafana

Connections → Data sources → Add new data source → Proxmox VE, then fill in:

Field	Value
Proxmox URL	https://pve.example.com:8006
API token ID	grafana@pve!readonly
API token secret	the UUID from step 1
Skip TLS verification	enable only if Proxmox still uses its default self-signed certificate
Timeout	optional; defaults to 30 seconds

Click Save & test. A healthy connection reports the Proxmox version and the number of nodes it can see.

On skipping TLS verification: Proxmox ships a self-signed certificate, so a new cluster will fail verification until you install a trusted one. Skipping verification protects the connection from eavesdropping but not from an active man-in-the-middle. Installing a certificate your Grafana server trusts, then leaving this off, is the better setup.

Building queries

Pick a Query type:

• Time series reads Proxmox's built-in RRD store. Choose a target (Node, VM, Container or Storage), pick the node, then the specific guest or storage, and select which metrics to chart. Leave Metrics empty to return everything available for that target.
• Resource table returns the current state of the cluster from /cluster/resources, optionally narrowed to VMs, storage or nodes.

Resolution

Proxmox does not serve arbitrary time ranges. It stores five fixed RRD windows: hour, day, week, month and year, each at its own sample interval. Auto picks the smallest window that covers your dashboard's time range, which is usually what you want. Choose a window explicitly when you want a specific sample interval regardless of the range.

Because of this, a very short dashboard range still returns whole-window data trimmed to your range, and ranges longer than a year return year-resolution samples.

Consolidation

Average smooths each RRD bucket; Max keeps the peak. Use Max when you are hunting for spikes that averaging would hide.

Troubleshooting

Message	What to do
authentication failed (401)	The token ID or secret is wrong, or the token has expired. Re-check both; the ID must include the realm and the !.
permission denied (403)	The token authenticated but lacks permission. Grant PVEAuditor on / and either uncheck Privilege Separation or give the token its own ACL.
the Proxmox API returned a non-JSON response	The URL is not pointing at the Proxmox API. Confirm the host and that you included port 8006.
TLS certificate errors	Either install a certificate your Grafana server trusts, or enable Skip TLS verification.
Empty graphs with no error	The guest may be stopped. Proxmox keeps RRD history for stopped guests, but recent buckets will be empty.

Support

Email support@ridgelinetechnologies.co.

• End User License Agreement
• Privacy Policy

Proxmox and Proxmox VE are trademarks of Proxmox Server Solutions GmbH. This plugin is an independent product and is not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH.