This commit is contained in:
@@ -1,125 +1,147 @@
|
||||
# PVE Exporter
|
||||
|
||||
Proxmox Virtual Environment Prometheus metrics 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.
|
||||
|
||||
## Overview
|
||||
|
||||
PVE Exporter is a tool that collects metrics from a Proxmox Virtual Environment cluster and exposes them for Prometheus to scrape. This exporter supports gathering metrics for cluster state, LXC containers, QEMU virtual machines, physical disks, ZFS pools, node storage, node status, node subscription details, and software-defined networking (SDN).
|
||||
The exporter supports standalone nodes and multi-node clusters. Multiple API
|
||||
hosts can be configured for endpoint failover within one Proxmox cluster.
|
||||
|
||||
## Features
|
||||
|
||||
- Collects various metrics from Proxmox VE to monitor the health and performance of your virtual environment.
|
||||
- Supports multi-node clusters for high availability.
|
||||
- Securely uses Proxmox API tokens with minimal permissions.
|
||||
- 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.
|
||||
|
||||
## Prerequisites
|
||||
## Quick start
|
||||
|
||||
- Docker installed on your machine.
|
||||
- Access to a Proxmox VE instance with API tokens configured.
|
||||
Copy the example configuration and set the Proxmox API hosts and token:
|
||||
|
||||
## Configuration
|
||||
|
||||
### Proxmox API Token
|
||||
|
||||
When generating the token, make sure to assign the 'PVEAuditor' permission to both the user and the API token. For security reasons, assign only the 'PVEAuditor' role to limit permissions appropriately.
|
||||
|
||||
```yaml
|
||||
# Proxmox API token configuration.
|
||||
token:
|
||||
tokenId: "your-token-id"
|
||||
secret: "your-secret"
|
||||
```sh
|
||||
cp config.example.yaml config.yaml
|
||||
```
|
||||
|
||||
### Proxmox API Hosts
|
||||
|
||||
If you are running a multi-node cluster, add multiple API hosts to ensure high availability of metrics. Note that this configuration is not intended for gathering metrics from multiple PVE clusters. For multiple PVE clusters, deploy a separate exporter instance for each cluster.
|
||||
|
||||
```yaml
|
||||
# Proxmox API hosts.
|
||||
hosts:
|
||||
- "https://host1.example.com"
|
||||
- "https://host2.example.com"
|
||||
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
|
||||
```
|
||||
|
||||
### Metrics Configuration
|
||||
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.
|
||||
|
||||
Configure which metrics to collect by enabling or disabling specific metric types.
|
||||
Build and start the exporter:
|
||||
|
||||
```yaml
|
||||
# Proxmox metrics configuration.
|
||||
metrics:
|
||||
clusterState: true # Enable collection of cluster state metrics.
|
||||
ltc: true # Enable collection of LXC container metrics.
|
||||
qemu: true # Enable collection of QEMU virtual machine metrics.
|
||||
disk: true # Enable collection of physical disk metrics.
|
||||
zfs: true # Enable collection of ZFS pool metrics.
|
||||
storage: true # Enable collection of node storage metrics.
|
||||
nodeStatus: true # Enable collection of node status metrics.
|
||||
subscription: true # Enable collection of node subscription details.
|
||||
sdn: true # Enable collection of software-defined network (SDN) metrics.
|
||||
```sh
|
||||
go build -o pve-exporter .
|
||||
./pve-exporter -config config.yaml
|
||||
```
|
||||
|
||||
The cluster state collector exposes `pve_cluster_mode`, where `1` means that
|
||||
Proxmox VE is configured as a cluster and `0` means that it is a standalone node.
|
||||
The exporter exposes Prometheus metrics at:
|
||||
|
||||
The `pve_node_subscription_status` metric uses `0` when no subscription is
|
||||
configured, `1` for an active subscription, and `2` for an expired or otherwise
|
||||
unusable subscription.
|
||||
```text
|
||||
http://localhost:9090/metrics
|
||||
```
|
||||
|
||||
The ZFS collector discovers all pools on every node and exports their recursive
|
||||
topology with `cluster`, `node`, `pool`, `component`, `path`, and `leaf` labels:
|
||||
## Documentation
|
||||
|
||||
- `pve_node_zfs_state` (`0=UNKNOWN`, `1=ONLINE`, `2=DEGRADED`, `3=FAULTED`,
|
||||
`4=OFFLINE`, `5=REMOVED`, `6=UNAVAIL`)
|
||||
- `pve_node_zfs_read_errors`
|
||||
- `pve_node_zfs_write_errors`
|
||||
- `pve_node_zfs_checksum_errors`
|
||||
- [Documentation index](docs/README.md)
|
||||
- [Configuration reference](docs/configuration.md)
|
||||
- [Metrics reference](docs/metrics.md)
|
||||
- [Operations and troubleshooting](docs/operations.md)
|
||||
- [Architecture and adding collectors](docs/architecture.md)
|
||||
|
||||
## Pull the Latest Image
|
||||
## Prometheus configuration
|
||||
|
||||
The latest published version can be downloaded from the Gitea container registry:
|
||||
```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.
|
||||
|
||||
## Docker
|
||||
|
||||
Pull the latest published image from the Gitea container registry:
|
||||
|
||||
```sh
|
||||
docker pull gitea.lostak.dev/lostakj/pve-exporter:latest
|
||||
```
|
||||
|
||||
## Build Locally
|
||||
|
||||
To build the Docker image for PVE Exporter, use the following command:
|
||||
Or build it locally:
|
||||
|
||||
```sh
|
||||
docker build --rm -t gitea.lostak.dev/lostakj/pve-exporter:latest .
|
||||
docker build --rm -t pve-exporter:latest .
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
To run the downloaded or locally built image, use the following command:
|
||||
Run the published image with a local configuration file:
|
||||
|
||||
```sh
|
||||
docker run --rm -d -p 9090:9090 --name pve-exporter gitea.lostak.dev/lostakj/pve-exporter:latest
|
||||
docker run --rm -p 9090:9090 \
|
||||
-v "$PWD/config.yaml:/opt/config.yaml:ro" \
|
||||
gitea.lostak.dev/lostakj/pve-exporter:latest
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Once the Docker container is running, the exporter will be available on port `9090`. You can configure Prometheus to scrape metrics from the exporter by adding a new scrape configuration to your Prometheus configuration file.
|
||||
|
||||
Example Prometheus scrape configuration:
|
||||
Example with Docker Compose:
|
||||
|
||||
```yaml
|
||||
scrape_configs:
|
||||
- job_name: 'pve-exporter'
|
||||
static_configs:
|
||||
- targets: ['localhost:9090']
|
||||
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. See the LICENSE.txt file for details.
|
||||
This project is licensed under the [MIT License](LICENSE).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please open an issue or submit a pull request if you have any improvements or bug fixes.
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter any issues or have questions, please open an issue on the project's GitHub repository.
|
||||
Contributions and bug reports are welcome through the project issue tracker.
|
||||
|
||||
Reference in New Issue
Block a user