Proxmox VE — Integration
Diese Anleitung beschreibt die Schritte zur Integration von OpenVLE mit Proxmox VE (PVE), einschließlich der Einrichtung von Benutzern, Berechtigungen und API-Zugang.
Proxmox VE ist eine Kernabhängigkeit von OpenVLE. Ohne korrekte Proxmox-Konfiguration startet die Anwendung zwar, aber sämtliche Aktionen mit VMs und VM-Vorlagen (Erstellen, Klonen, Starten, Stoppen, Löschen) schlagen fehl.
Proxmox-Benutzer und Token einrichten
Für die Nutzung der Proxmox API müssen ein Pool, ein Benutzer, ein API-Token, Rollen und die entsprechenden Berechtigungen angelegt werden.
Pool erstellen
Erstelle einen Pool wie OpenVLE-VMs.
Dieser Pool wird für alle von OpenVLE verwalteten Templates und VMs verwendet. Nur VMs und Templates in diesem Pool sind für OpenVLE sichtbar.
CLI-Befehl
pvesh create /pools --poolid 'OpenVLE-VMs'
WebGUI
Datacenter -> Permissions -> Pools -> Add
Benutzerkonto erstellen
Erstelle einen Benutzer wie OpenVLE@pve — du kannst einen beliebigen Benutzernamen verwenden
(wir nutzen diesen als Referenz im Rest der Anleitung).
Dieser Benutzer wird für alle Interaktionen von OpenVLE mit Proxmox verwendet. Es kann ein @pve-, @pam-, @ldap- oder ein beliebiges anderes Konto sein.
Da OpenVLE sich über ein API-Token verbindet, spielt das Backend-Realm keine Rolle.
Das Konto benötigt kein Passwort (Hinweis: Konten ohne Passwort können nur über die PVE-CLI erstellt werden, nicht über die WebGUI).
Benutzerattribute wie Vorname / Nachname, E-Mail und Kommentar können beliebig gesetzt werden — sie sind für die Funktion von OpenVLE nicht relevant. Der Benutzer muss lediglich das Flag Enabled auf true gesetzt haben.
CLI-Befehl
pvesh create /access/users --userid 'OpenVLE@pve'
WebGUI
Datacenter -> Permissions -> Users -> Add
API-Token generieren
Generiere ein API-Token für den soeben erstellten Benutzer.
Als Token ID kannst du eine beliebige ID wählen — wir verwenden hier prod01.
Setze Privilege Separation auf true.
Notiere dir die Token-Details, da sie nur einmal angezeigt werden.
Ohne Privilege Separation erbt ein API-Token automatisch alle Berechtigungen seines Benutzers. Mit aktivierter Privilege Separation hingegen hat ein Token nur die Berechtigungen, die ihm explizit zugewiesen wurden.
Das ermöglicht es, mit einem einzigen Proxmox-Benutzer mehrere OpenVLE-Instanzen isoliert zu betreiben: Erstelle für jede Instanz (z. B. Produktion, Staging, Testing) ein eigenes API-Token und weise jedem Token nur den jeweiligen VM-Pool zu. So kann eine Staging-Instanz ausschließlich auf ihre eigenen VMs zugreifen, ohne die Produktions-VMs zu sehen oder zu beeinflussen.
Beispiel: Ein Benutzer OpenVLE@pve mit zwei Tokens:
OpenVLE@pve!prod01→ PoolOpenVLE-Prod(Produktionsumgebung)OpenVLE@pve!staging01→ PoolOpenVLE-Staging(Testumgebung)
CLI-Befehl
pvesh create /access/users/OpenVLE@pve/token/prod01
WebGUI
Datacenter -> Permissions -> API Tokens -> Add
Zwei Rollen auf dem PVE erstellen
Da der Benutzer und das API-Token unterschiedliche Berechtigungen auf verschiedenen Pfaden innerhalb von PVE benötigen, müssen zwei Rollen erstellt werden.
OpenVLE-Infra-Generalmit folgenden Privilegien:Sys.AuditSys.Console
OpenVLE-Infra-VMsmit folgenden Privilegien:VM.AllocateVM.AuditVM.CloneVM.Config.DiskVM.Config.CDROMVM.Config.CPUVM.Config.MemoryVM.Config.NetworkVM.Config.HWTypeVM.Config.OptionsVM.Config.CloudinitVM.GuestAuditVM.MigrateVM.MonitorVM.PowerMgmt
Das Privileg VM.GuestAudit existiert erst ab Proxmox VE 9. Wenn du eine ältere Version einsetzt, lasse dieses Privileg weg.
Wozu werden diese Privilegien benötigt?
OpenVLE-Infra-General — Wird auf Pfad / zugewiesen und ermöglicht systemweite Abfragen:
| Privileg | Verwendung in OpenVLE |
|---|---|
Sys.Audit | Cluster-Status und -Ressourcen abfragen, Node-Statistiken abrufen, Task-Status prüfen, HA-Konfiguration lesen |
Sys.Console | HA-Konfiguration für VMs erstellen, ändern und löschen |
OpenVLE-Infra-VMs — Wird auf den VM-Pool zugewiesen und ermöglicht die Verwaltung von VMs und Templates:
| Privileg | Verwendung in OpenVLE |
|---|---|
VM.Allocate | VMs und Templates erstellen und löschen |
VM.Audit | VM-Status und -Konfiguration abfragen, CloudInit-Konfiguration regenerieren |
VM.Clone | VMs und Templates klonen |
VM.Config.* | VM-Konfiguration ändern (Disk, CDROM, CPU, Memory, Network, HWType, Options, Cloudinit) |
VM.GuestAudit | Guest-Agent-Abfragen und -Befehle ausführen (ab PVE 9, bei PVE < 9 weglassen) |
VM.Migrate | VMs zwischen Nodes migrieren |
VM.Monitor | Netzwerk-Interfaces auslesen (z. B. IPv4-Adresse einer VM ermitteln) |
VM.PowerMgmt | VMs starten, stoppen, neu starten, herunterfahren, pausieren und fortsetzen |
CLI-Befehl
pvesh create /access/roles --roleid 'OpenVLE-Infra-General' --privs 'Sys.Audit,Sys.Console'
pvesh create /access/roles --roleid 'OpenVLE-Infra-VMs' --privs 'VM.Allocate, VM.Audit, VM.Clone, VM.Config.Disk, VM.Config.CDROM, VM.Config.CPU, VM.Config.Memory, VM.Config.Network, VM.Config.HWType, VM.Config.Options, VM.Config.Cloudinit, VM.GuestAudit, VM.Migrate, VM.Monitor, VM.PowerMgmt'
WebGUI
Datacenter -> Permissions -> Roles -> Create
Berechtigungen zuweisen
Alle folgenden Berechtigungen müssen sowohl dem Benutzer (OpenVLE@pve) als auch dem API-Token (OpenVLE@pve!prod01) zugewiesen werden. Durch Privilege Separation validiert Proxmox die Berechtigungen beider Identitäten unabhängig voneinander — fehlt eine Zuweisung, schlagen die API-Aufrufe fehl.
Zugehörige Rollen zuweisen
Die zuvor erstellten Rollen müssen auf den jeweiligen Pfaden zugewiesen werden.
1. Allgemeine Systemberechtigungen (OpenVLE-Infra-General)
- Pfad:
/ - Rolle:
OpenVLE-Infra-General - Propagate: True
Diese Zuweisung ermöglicht systemweite Operationen: Cluster-Status und -Ressourcen abfragen, Node-Statistiken abrufen, Task-Status prüfen sowie HA-Konfigurationen verwalten.
2. VM-Berechtigungen im Pool (OpenVLE-Infra-VMs)
- Pfad:
/pool/OpenVLE-VMs - Rolle:
OpenVLE-Infra-VMs - Propagate: True
Diese Zuweisung beschränkt die VM-Verwaltung auf den zuvor erstellten Pool. OpenVLE kann damit VMs und Templates innerhalb dieses Pools erstellen, klonen, konfigurieren, steuern und löschen — jedoch keine VMs außerhalb des Pools beeinflussen.
Storage- und Netzwerk-Berechtigungen zuweisen
Beim Klonen von VMs benötigt Proxmox zusätzliche Berechtigungen auf den verwendeten Storage und das Netzwerk. Ohne diese Berechtigungen schlägt das Klonen mit einem Berechtigungsfehler fehl, obwohl die VM-Rechte korrekt gesetzt sind.
Die folgenden Pfade sind Beispiele. Du musst sie an den Storage und das Netzwerk deiner Umgebung anpassen.
Falls deine VMs und Templates unterschiedliche Storages oder Netzwerke verwenden (z. B. VMs auf local-lvm und Templates auf ceph, oder VMs in verschiedenen VLANs), musst du die jeweilige Berechtigung pro Storage bzw. Netzwerk separat vergeben. Erstelle dafür einfach weitere Zuweisungen mit der gleichen Rolle auf den zusätzlichen Pfaden.
3. Storage-Berechtigungen
Pro verwendetem Storage eine Zuweisung erstellen:
- Pfad:
/storage/ceph(ersetzecephmit deinem Storage-Namen) - Rolle:
PVEDatastoreUser - Propagate: True
Ermöglicht das Allozieren von Festplatten-Images beim Klonen und Erstellen von VMs auf dem angegebenen Storage. Nutzen deine VMs und Templates mehrere Storages, wiederhole diesen Schritt für jeden Storage (z. B. /storage/local-lvm, /storage/nfs-share).
4. SDN-/Netzwerk-Berechtigungen
Pro verwendetem Netzwerksegment eine Zuweisung erstellen:
- Pfad:
/sdn/zones/localnetwork/vmbr1/10(ersetze mit deiner Zone, Bridge und VLAN) - Rolle:
PVESDNUser - Propagate: True
Ermöglicht das Zuweisen von Netzwerk-Interfaces beim Klonen und Konfigurieren von VMs. Werden VMs in verschiedenen VLANs oder Bridges betrieben, wiederhole diesen Schritt für jedes Netzwerksegment (z. B. /sdn/zones/localnetwork/vmbr1/20).
CLI-Befehle und WebGUI
CLI-Befehle (alle 4 Zuweisungen)
Ersetze die Werte für Benutzer, API-Token, Pool, Storage und Netzwerk mit deinen eigenen.
# 1. Allgemeine Systemberechtigungen
pvesh set /access/acl --path '/' \
--roles 'OpenVLE-Infra-General' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'
# 2. VM-Berechtigungen im Pool
pvesh set /access/acl --path '/pool/OpenVLE-VMs' \
--roles 'OpenVLE-Infra-VMs' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'
# 3. Storage-Berechtigungen
pvesh set /access/acl --path '/storage/ceph' \
--roles 'PVEDatastoreUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'
# 4. SDN-/Netzwerk-Berechtigungen
pvesh set /access/acl --path '/sdn/zones/localnetwork/vmbr1/10' \
--roles 'PVESDNUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'
WebGUI
Für jede der 4 Zuweisungen:
Datacenter -> Permissions -> Add -> User Permission
Datacenter -> Permissions -> Add -> API Token Permission
Wähle jeweils den Pfad, die Rolle und setze Propagate auf True.
API-Referenz
OpenVLE nutzt die folgenden Proxmox VE API-Endpoints. Diese Übersicht dient als Referenz zur Fehleranalyse bei Berechtigungsproblemen. Die vollständige API-Dokumentation von Proxmox findest du im PVE API Viewer.
Vollständige API-Endpoint-Übersicht
Cluster-Operationen
Endpoints mit Privileg „Keine*" erfordern kein explizites Privileg, liefern aber nur Objekte zurück, auf die der Benutzer bzw. das Token über andere Berechtigungen (z. B. Sys.Audit, VM.Audit) Zugriff hat. Die Ergebnismenge wird von Proxmox dynamisch anhand der vorhandenen Berechtigungen gefiltert.
| Endpoint | Methode | Benötigtes Privileg | Funktion |
|---|---|---|---|
/cluster/resources | GET | Keine* | Cluster-Ressourcen und Node-Zuordnung abfragen |
/cluster/status | GET | Sys.Audit | Cluster-Status abfragen |
/cluster/nextid | GET | Keine* | Nächste verfügbare VM-ID ermitteln |
/cluster/log | GET | Keine* | PVE-Logs abrufen |
/cluster/tasks | GET | Keine* | Aktuelle Cluster-Tasks auflisten |
/nodes | GET | Keine | Alle PVE-Nodes auflisten |
/nodes/{node}/rrd | GET | Sys.Audit | Node-Statistiken abrufen |
High Availability (HA)
| Endpoint | Methode | Benötigtes Privileg | Funktion |
|---|---|---|---|
/cluster/ha/resources | GET | Sys.Audit | Alle HA-Ressourcen auflisten |
/cluster/ha/resources | POST | Sys.Console | HA für eine VM aktivieren |
/cluster/ha/resources/{sid} | GET | Sys.Audit | HA-Status einer VM abfragen |
/cluster/ha/resources/{sid} | PUT | Sys.Console | HA-Konfiguration einer VM ändern |
/cluster/ha/resources/{sid} | DELETE | Sys.Console | HA für eine VM deaktivieren |
VM-Verwaltung
| Endpoint | Methode | Benötigtes Privileg | Funktion |
|---|---|---|---|
/nodes/{node}/qemu/{vmid}/config | GET | VM.Audit | VM-Konfiguration abfragen |
/nodes/{node}/qemu/{vmid}/config | PUT | VM.Config.* | VM-Konfiguration ändern |
/nodes/{node}/qemu/{vmid}/status/current | GET | VM.Audit | Aktuellen VM-Status abfragen |
/nodes/{node}/qemu/{vmid}/clone | POST | VM.Clone, VM.Allocate | VM oder Template klonen |
/nodes/{node}/qemu/{vmid} | DELETE | VM.Allocate | VM löschen |
/nodes/{node}/qemu/{vmid}/migrate | POST | VM.Migrate | VM auf anderen Node migrieren |
/nodes/{node}/qemu/{vmid}/cloudinit | PUT | VM.Audit | CloudInit-Konfiguration regenerieren |
/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces | GET | VM.Monitor | Netzwerk-Interfaces (IPv4) auslesen |
/nodes/{node}/tasks/{upid}/status | GET | Sys.Audit | Task-Status abfragen |
VM-Steuerung (Power Management)
| Endpoint | Methode | Benötigtes Privileg | Funktion |
|---|---|---|---|
/nodes/{node}/qemu/{vmid}/status/{action} | POST | VM.PowerMgmt | VM steuern: start, stop, shutdown, reboot, reset, resume, suspend |