155 lines
4.1 KiB
Markdown
155 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
cp config.example.yaml config.yaml
|
|
```
|
|
|
|
```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:
|
|
|
|
```sh
|
|
go build -o pve-exporter .
|
|
./pve-exporter -config config.yaml
|
|
```
|
|
|
|
The exporter exposes Prometheus metrics at:
|
|
|
|
```text
|
|
http://localhost:9090/metrics
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Documentation index](docs/README.md)
|
|
- [Configuration reference](docs/configuration.md)
|
|
- [Metrics reference](docs/metrics.md)
|
|
- [Prometheus alerting rules](docs/alerting.md)
|
|
- [Operations and troubleshooting](docs/operations.md)
|
|
- [Architecture and adding collectors](docs/architecture.md)
|
|
|
|
## Prometheus configuration
|
|
|
|
```yaml
|
|
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`](examples/pve-exporter.rules.yml). See the
|
|
[alerting guide](docs/alerting.md) for the `rule_files` configuration and
|
|
collector requirements.
|
|
|
|
## Docker
|
|
|
|
Pull the latest published image from the Gitea container registry:
|
|
|
|
```sh
|
|
docker pull gitea.lostak.dev/lostakj/pve-exporter:latest
|
|
```
|
|
|
|
Or build it locally:
|
|
|
|
```sh
|
|
docker build --rm -t pve-exporter:latest .
|
|
```
|
|
|
|
Run the published image with a local configuration file:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```yaml
|
|
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](LICENSE).
|
|
|
|
## Contributing
|
|
|
|
Contributions and bug reports are welcome through the project issue tracker.
|