Zum Inhalt

Proxmox VE über die API überwachen

Vesana überwacht einen Proxmox-VE-Node über dessen REST-API auf Port 8006 mit einem API-Token. Auf dem Proxmox-Host läuft dabei kein Agent — die Checks laufen im Modus active (der Vesana-Server fragt die API selbst ab; ohne Aktiven Collector übernimmt der Python-Fallback, der http_json-Checks ausführen kann).

Überwacht werden u. a.: API-Erreichbarkeit, Cluster-Quorum, Node-CPU/-RAM/-Disk, Anzahl laufender VMs und LXC-Container sowie Storages.

1. API-Token in Proxmox anlegen

Im Proxmox-Web-UI:

  1. Datacenter → Permissions → API Tokens → Add.
  2. Einen Benutzer wählen (z. B. monitoring@pve oder root@pam) und dem Token eine ID geben (z. B. vesana). Der vollständige Token-Bezeichner hat damit die Form benutzer@realm!tokenid, also z. B. monitoring@pve!vesana.
  3. Das einmalig angezeigte Secret kopieren und sicher ablegen — es wird danach nicht wieder angezeigt.

Der Token braucht Lese-Rechte. Weise ihm eine Rolle wie PVEAuditor am Pfad / zu:

  • Datacenter → Permissions → Add → API Token Permission, Pfad /, dein Token, Rolle PVEAuditor.

Privilege Separation

Ist beim Token „Privilege Separation" aktiv (Standard), braucht der Token einen eigenen Permission-Eintrag wie oben. Ist sie deaktiviert, erbt der Token die Rechte seines Benutzers.

2. Proxmox-Profil in Vesana holen

Das fertige Profil „Proxmox VE (API)" liegt im Community Hub. Öffne Profile, durchsuche den Hub nach „Proxmox" und importiere das Profil. Es bringt die API-Checks bereits mit (API erreichbar, Quorum, Node-CPU/-RAM/-Disk, laufende VMs/LXC, Storages).

3. Host anlegen und API-Zugang hinterlegen

Lege einen Host an:

  1. Als Ziel die IP-Adresse oder den DNS-Namen des Proxmox-Node eintragen. Damit füllt Vesana das {host} in den Check-URLs (z. B. https://{host}:8006/api2/json/version).
  2. Als Profil „Proxmox VE (API)" wählen.
  3. Im Abschnitt Zugangsdaten den Bereich API-Zugang öffnen und in die zwei Felder eintragen:
  4. Benutzer: die Token-ID, benutzer@realm!tokenid (z. B. monitoring@pve!vesana)
  5. Passwort / Geheimnis: das Token-Secret aus Schritt 1

Vesana setzt daraus den Proxmox-Auth-Header (PVEAPIToken=…) selbst zusammen und sendet ihn bei jedem API-Check. Der Zugang wird verschlüsselt gespeichert. Dieselbe Karte „API-Zugang" nimmt bei anderen Geräten (z. B. ESXi) statt eines Tokens einen Benutzernamen mit Passwort auf — es ist derselbe Zugangsweg, nur mit anderem Inhalt.

Bestandskunden

War an einem Host bereits ein Proxmox-Token hinterlegt, ist er nach dem Update automatisch in die Felder Benutzer/Passwort der Karte „API-Zugang" übernommen worden — nichts weiter zu tun.

Hinweise & Troubleshooting

  • Self-signed-Zertifikat: Proxmox nutzt standardmäßig ein selbst signiertes Zertifikat. Die Checks des Profils akzeptieren das bewusst.
  • „API erreichbar" ist CRITICAL mit 401/403 → Token oder Rolle stimmen nicht. Prüfe Token-ID (inkl. !tokenid), Secret und die zugewiesene Rolle (PVEAuditor am Pfad /).
  • 5xx bei „API erreichbar" → die Proxmox-API selbst ist gerade nicht gesund, nicht die Vesana-Konfiguration.
  • Multi-Node-Cluster: Die Node-Gesundheits-Checks lesen standardmäßig den ersten Node. Zeige den Host auf den konkreten Node, den du überwachen willst, oder lege pro Node einen eigenen Host (mit demselben Token) an.
  • Erreichbarkeit: Der Vesana-Server (bzw. der Aktive Collector) muss den Node auf Port 8006 erreichen — ggf. Firewall prüfen.

Backup-Überwachung

Das Profil enthält vier Backup-Checks (ab Bundle-Version mit Backup-Support):

  • Backup failures (recent tasks) — zählt fehlgeschlagene vzdump-Backups in der jüngeren Task-Historie (clusterweit). Ein laufendes Backup zählt nie als Fehlschlag. Der Zähler sinkt erst, wenn der fehlgeschlagene Task aus der Proxmox-Task-Liste rotiert — bis dahin bleibt der Check WARNING.
  • Backup warnings (recent tasks) — Läufe, die MIT Warnungen fertig wurden. Startet im Info-Modus: sichtbar, aber ohne Alarm.
  • Guests without backup job — Gäste, die von keinem vzdump-Job erfasst sind. Sicherst du extern (z. B. Proxmox Backup Server im Pull-Modus oder Storage-Snapshots), passe die Schwelle an oder deaktiviere den Check.
  • Backup jobs configured — reine Anzeige: Anzahl der angelegten vzdump-Jobs (inklusive deaktivierter). 0 heißt, es ist gar kein Backup eingerichtet.

Warum „mit Warnungen" kein Fehlschlag ist

Proxmox schließt einen Backup-Task mit OK, mit WARNINGS: n oder mit einem Fehlertext ab. Als Fehler zählt Proxmox nur das Dritte — ein Lauf mit Warnungen steht in der Task-Liste orange als „Warning: n", nicht rot. Vesana zieht dieselbe Grenze: Warnungen landen im eigenen Info-Modus-Zähler, nicht bei den Fehlschlägen. Typische Warnungs-Ursachen sind ein nicht antwortender Gast-Agent, ein übersprungenes Volume oder ein Hook-Script, das etwas meldet — das Backup selbst ist gelaufen.

Alle vier sind normale Profil-Checks — Schwellwerte, Intervalle und Aktiv-Schalter lassen sich pro Profil oder pro Host anpassen. Ein zeitbasierter Check („letztes Backup älter als X") ist über die REST-API nicht zuverlässig abbildbar und fehlt bewusst.