PVE Exporter

Prometheus exporter for Proxmox Virtual Environment. It periodically reads the Proxmox VE HTTP API and exposes cluster, node, guest, storage, disk, ZFS, subscription, and SDN metrics through a single /metrics endpoint.

The exporter supports standalone nodes and multi-node clusters. Multiple API hosts can be configured for endpoint failover within one Proxmox cluster.

Features

• Standalone-node and cluster mode detection, node count, and quorum state.
• Node CPU, memory, load, root filesystem, uptime, time, and system information.
• QEMU virtual machine and LXC container state and resource metrics.
• Physical disk health, wearout, and size metrics.
• Recursive ZFS pool, vdev, cache, and leaf-device state and error metrics.
• Storage capacity and availability, subscription, and SDN state metrics.
• Selectively enabled collectors with automatic cleanup of stale label sets.
• Multiple API endpoints with periodic liveness checks and round-robin requests.
• Proxmox API token authentication using the read-only PVEAuditor role.

Quick start

Copy the example configuration and set the Proxmox API hosts and token:

cp config.example.yaml config.yaml

host: 0.0.0.0
port: 9090
logLevel: 4

proxmox:
  token:
    tokenId: monitoring@pve!exporter
    secret: change-me

  hosts:
    - https://pve01.example.com:8006
    - https://pve02.example.com:8006

  interval: 15

  metrics:
    clusterState: true
    nodeStatus: true
    qemu: true
    lxc: true
    disk: true
    zfs: true
    storage: true
    subscription: true
    sdn: true

Assign the PVEAuditor role to both the Proxmox user and API token. All entries under hosts must belong to the same cluster. IP addresses and DNS names are supported, with or without a trailing slash.

Build and start the exporter:

go build -o pve-exporter .
./pve-exporter -config config.yaml

The exporter exposes Prometheus metrics at:

http://localhost:9090/metrics

Documentation

• Documentation index
• Configuration reference
• Metrics reference
• Prometheus alerting rules
• Operations and troubleshooting
• Architecture and adding collectors

Prometheus configuration

scrape_configs:
  - job_name: pve-exporter
    static_configs:
      - targets: [pve-exporter:9090]

Metrics are collected in the background according to proxmox.interval. Prometheus scrapes the most recently collected values and does not trigger a new request to Proxmox VE.

An example alert group for node, guest, storage, subscription, disk, ZFS, SDN, and capacity conditions is available in examples/pve-exporter.rules.yml. See the alerting guide for the rule_files configuration and collector requirements.

Docker

Pull the latest published image from the Gitea container registry:

docker pull gitea.lostak.dev/lostakj/pve-exporter:latest

Or build it locally:

docker build --rm -t pve-exporter:latest .

Run the published image with a local configuration file:

docker run --rm -p 9090:9090 \
  -v "$PWD/config.yaml:/opt/config.yaml:ro" \
  gitea.lostak.dev/lostakj/pve-exporter:latest

Example with Docker Compose:

services:
  pve-exporter:
    image: gitea.lostak.dev/lostakj/pve-exporter:latest
    ports:
      - "9090:9090"
    volumes:
      - ./config.yaml:/opt/config.yaml:ro
    restart: unless-stopped

Scope

One exporter instance monitors one standalone Proxmox VE installation or one cluster. Configure multiple hosts only for redundant access to that same cluster. Deploy a separate exporter instance for every additional cluster.

The published workflow currently builds the container image for linux/amd64. The API client accepts self-signed Proxmox certificates because TLS certificate verification is disabled; use trusted networks and protect the API token.

License

This project is licensed under the MIT License.

Contributing

Contributions and bug reports are welcome through the project issue tracker.