Updated docs

2026-08-18 01:13:27 +02:00
parent 2d634470d9
commit b69e10d52f
7 changed files with 654 additions and 81 deletions
@@ -0,0 +1,113 @@
+# Configuration Reference
+
+The exporter reads `config.yaml` from the current working directory by default.
+Use `-config` to select a different file:
+
+```sh
+./pve-exporter -config /etc/pve-exporter/config.yaml
+```
+
+## Complete example
+
+```yaml
+host: 0.0.0.0
+port: 9090
+logLevel: 4
+
+proxmox:
+  token:
+    tokenId: monitoring@pve!exporter
+    secret: change-me
+
+  hosts:
+    - https://192.168.0.10: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
+```
+
+## Server settings
+
+| Setting | Type | Description |
+| --- | --- | --- |
+| `host` | IP address | Address on which the exporter HTTP server listens, for example `0.0.0.0` or `127.0.0.1`. DNS names are not accepted here. |
+| `port` | integer | Exporter HTTP port. Prometheus metrics are served at `/metrics`. |
+| `logLevel` | integer | Logrus level: `0=Panic`, `1=Fatal`, `2=Error`, `3=Warn`, `4=Info`, `5=Debug`, `6=Trace`. |
+
+## Proxmox token
+
+| Setting | Type | Description |
+| --- | --- | --- |
+| `proxmox.token.tokenId` | string | Full Proxmox API token ID, normally `user@realm!token-name`. |
+| `proxmox.token.secret` | string | API token secret. Treat the configuration file as sensitive. |
+
+Create a dedicated monitoring user and token, then assign the read-only
+`PVEAuditor` role to both the user and the token. The role supplies the audit
+permissions used by cluster, node, storage, disk, ZFS, guest, and subscription
+API calls.
+
+## API hosts and failover
+
+`proxmox.hosts` is a non-empty list of Proxmox API base URLs. Both IP addresses
+and DNS names are supported:
+
+```yaml
+proxmox:
+  hosts:
+    - https://192.168.0.10:8006
+    - https://pve02.example.com:8006/
+```
+
+A trailing slash is optional and normalized automatically. Every host must use
+`http` or `https` and must belong to the same PVE cluster. The exporter checks
+endpoint liveness every five seconds and distributes API requests across the
+currently reachable endpoints.
+
+Do not combine unrelated clusters in one list. Their API responses share the
+same short-lived client cache and Prometheus registry. Run a separate exporter
+for each cluster.
+
+## Collection interval
+
+`proxmox.interval` is the positive number of seconds between collection cycles.
+The first cycle runs during application startup. Prometheus scrapes only the
+values already present in the registry, so its scrape interval does not control
+the PVE API request rate.
+
+## Collector switches
+
+All switches are booleans. Omitted switches default to `false`.
+
+| Setting | Collector | Main metric prefix |
+| --- | --- | --- |
+| `clusterState` | Cluster mode, node count, and quorum | `pve_cluster_` |
+| `nodeStatus` | Node health and resource usage | `pve_node_` |
+| `qemu` | QEMU virtual machines | `pve_vm_` |
+| `lxc` | LXC containers | `pve_ct_` |
+| `disk` | Physical disk health and metadata | `pve_node_disk_` |
+| `zfs` | ZFS pool topology, state, and errors | `pve_node_zfs_` |
+| `storage` | Enabled PVE storage status and capacity | `pve_storage_` |
+| `subscription` | Node subscription information | `pve_node_subscription_` |
+| `sdn` | Software-defined network state | `pve_sdn_` |
+
+The exporter-level `pve_metrics_collection_latency_ms` summary is always
+registered.
+
+## Validation notes
+
+- `host` must be a literal IP address.
+- At least one Proxmox API host is required.
+- API host URLs require an `http` or `https` scheme and an IP or DNS hostname.
+- Token ID and secret cannot be empty.
+- Keep `proxmox.interval` greater than zero and `logLevel` between `0` and `6`.