# 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)
- [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.

## 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.