Proxmox VE — Intégration

Ce guide décrit les étapes pour intégrer OpenVLE avec Proxmox VE (PVE), y compris la configuration des utilisateurs, des permissions et de l'accès API.

Composant obligatoire

Proxmox VE est une dépendance essentielle d'OpenVLE. Sans configuration Proxmox correcte, l'application démarre, mais toutes les actions sur les VMs et les modèles de VM (création, clonage, démarrage, arrêt, suppression) échouent.

Configurer l'utilisateur et le token Proxmox

Pour utiliser l'API Proxmox, il faut créer un pool, un utilisateur, un token API, des rôles et les permissions correspondantes.

Créer un pool

Créez un pool comme OpenVLE-VMs. Ce pool sera utilisé pour tous les templates et VMs gérés par OpenVLE. Seuls les VMs et templates de ce pool sont visibles pour OpenVLE.

Commande CLI

pvesh create /pools --poolid 'OpenVLE-VMs'

WebGUI

Datacenter -> Permissions -> Pools -> Add

Créer un compte utilisateur

Créez un utilisateur comme OpenVLE@pve — vous pouvez choisir n'importe quel nom d'utilisateur (nous utilisons celui-ci comme référence dans la suite du guide). Cet utilisateur sera utilisé pour toutes les interactions d'OpenVLE avec Proxmox. Il peut s'agir d'un compte @pve, @pam, @ldap ou de tout autre type. Comme OpenVLE se connecte via un token API, le realm du backend n'a pas d'importance. Le compte n'a pas besoin de mot de passe (remarque : les comptes sans mot de passe ne peuvent être créés que via la CLI PVE, pas via la WebGUI). Les attributs utilisateur tels que Prénom / Nom, E-mail et Commentaire peuvent être définis librement — ils ne sont pas pertinents pour le fonctionnement d'OpenVLE. L'utilisateur doit simplement avoir le drapeau Enabled à true.

Commande CLI

pvesh create /access/users --userid 'OpenVLE@pve'

WebGUI

Datacenter -> Permissions -> Users -> Add

Générer un token API

Générez un token API pour l'utilisateur que vous venez de créer. Comme Token ID, vous pouvez choisir un identifiant quelconque — nous utilisons ici prod01. Définissez Privilege Separation sur true. Notez les détails du token, car ils ne seront affichés qu'une seule fois.

Pourquoi Privilege Separation ?

Sans Privilege Separation, un token API hérite automatiquement de toutes les permissions de son utilisateur. Avec Privilege Separation activée, un token ne dispose que des permissions qui lui sont explicitement attribuées.

Cela permet d'exploiter plusieurs instances OpenVLE de manière isolée avec un seul utilisateur Proxmox : créez pour chaque instance (par ex. production, staging, test) un token API distinct et attribuez à chaque token uniquement le pool de VMs correspondant. Ainsi, une instance staging ne peut accéder qu'à ses propres VMs, sans voir ni affecter les VMs de production.

Exemple : Un utilisateur OpenVLE@pve avec deux tokens :

• OpenVLE@pve!prod01 → Pool OpenVLE-Prod (environnement de production)
• OpenVLE@pve!staging01 → Pool OpenVLE-Staging (environnement de test)

Commande CLI

pvesh create /access/users/OpenVLE@pve/token/prod01

WebGUI

Datacenter -> Permissions -> API Tokens -> Add

Créer deux rôles sur le PVE

Comme l'utilisateur et le token API nécessitent des permissions différentes sur différents chemins au sein de PVE, deux rôles doivent être créés.

1. OpenVLE-Infra-General avec les privilèges suivants :
   1. Sys.Audit
   2. Sys.Console
2. OpenVLE-Infra-VMs avec les privilèges suivants :
   1. VM.Allocate
   2. VM.Audit
   3. VM.Clone
   4. VM.Config.Disk
   5. VM.Config.CDROM
   6. VM.Config.CPU
   7. VM.Config.Memory
   8. VM.Config.Network
   9. VM.Config.HWType
   10. VM.Config.Options
   11. VM.Config.Cloudinit
   12. VM.GuestAudit
   13. VM.Migrate
   14. VM.Monitor
   15. VM.PowerMgmt

Proxmox VE < 9

Le privilège VM.GuestAudit n'existe qu'à partir de Proxmox VE 9. Si vous utilisez une version antérieure, omettez ce privilège.

À quoi servent ces privilèges ?

OpenVLE-Infra-General — Attribué sur le chemin / et permet les requêtes à l'échelle du système :

Privilège	Utilisation dans OpenVLE
Sys.Audit	Interroger le statut et les ressources du cluster, consulter les statistiques des nœuds, vérifier le statut des tâches, lire la configuration HA
Sys.Console	Créer, modifier et supprimer la configuration HA pour les VMs

OpenVLE-Infra-VMs — Attribué sur le pool de VMs et permet la gestion des VMs et des templates :

Privilège	Utilisation dans OpenVLE
VM.Allocate	Créer et supprimer des VMs et des templates
VM.Audit	Interroger le statut et la configuration des VMs, régénérer la configuration CloudInit
VM.Clone	Cloner des VMs et des templates
VM.Config.*	Modifier la configuration des VMs (Disk, CDROM, CPU, Memory, Network, HWType, Options, Cloudinit)
VM.GuestAudit	Exécuter les requêtes et commandes Guest Agent (à partir de PVE 9, omettre pour PVE < 9)
VM.Migrate	Migrer les VMs entre les nœuds
VM.Monitor	Lire les interfaces réseau (par ex. déterminer l'adresse IPv4 d'une VM)
VM.PowerMgmt	Démarrer, arrêter, redémarrer, éteindre, suspendre et reprendre les VMs

Commande CLI

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

Attribuer les permissions

Toutes les permissions suivantes doivent être attribuées aussi bien à l'utilisateur (OpenVLE@pve) qu'au token API (OpenVLE@pve!prod01). En raison de la Privilege Separation, Proxmox valide les permissions des deux identités de manière indépendante — si une attribution manque, les appels API échouent.

Attribuer les rôles correspondants

Les rôles créés précédemment doivent être attribués sur les chemins respectifs.

1. Permissions système générales (OpenVLE-Infra-General)

• Chemin : /
• Rôle : OpenVLE-Infra-General
• Propagate : True

Cette attribution permet les opérations à l'échelle du système : interroger le statut et les ressources du cluster, consulter les statistiques des nœuds, vérifier le statut des tâches et gérer les configurations HA.

2. Permissions VM dans le pool (OpenVLE-Infra-VMs)

• Chemin : /pool/OpenVLE-VMs
• Rôle : OpenVLE-Infra-VMs
• Propagate : True

Cette attribution restreint la gestion des VMs au pool créé précédemment. OpenVLE peut ainsi créer, cloner, configurer, contrôler et supprimer des VMs et des templates au sein de ce pool — mais ne peut pas affecter les VMs en dehors du pool.

Attribuer les permissions de stockage et de réseau

Lors du clonage de VMs, Proxmox nécessite des permissions supplémentaires sur le stockage et le réseau utilisés. Sans ces permissions, le clonage échoue avec une erreur de permission, même si les droits sur la VM sont correctement définis.

Dépend de l'environnement

Les chemins suivants sont des exemples. Vous devez les adapter au stockage et au réseau de votre environnement.

Si vos VMs et templates utilisent différents stockages ou réseaux (par ex. VMs sur local-lvm et templates sur ceph, ou VMs dans différents VLANs), vous devez attribuer la permission respective par stockage ou réseau séparément. Créez simplement des attributions supplémentaires avec le même rôle sur les chemins additionnels.

3. Permissions de stockage

Créez une attribution par stockage utilisé :

• Chemin : /storage/ceph (remplacez ceph par le nom de votre stockage)
• Rôle : PVEDatastoreUser
• Propagate : True

Permet l'allocation d'images disque lors du clonage et de la création de VMs sur le stockage spécifié. Si vos VMs et templates utilisent plusieurs stockages, répétez cette étape pour chaque stockage (par ex. /storage/local-lvm, /storage/nfs-share).

4. Permissions SDN/réseau

Créez une attribution par segment réseau utilisé :

• Chemin : /sdn/zones/localnetwork/vmbr1/10 (remplacez par votre zone, bridge et VLAN)
• Rôle : PVESDNUser
• Propagate : True

Permet l'attribution d'interfaces réseau lors du clonage et de la configuration de VMs. Si les VMs sont exploitées dans différents VLANs ou bridges, répétez cette étape pour chaque segment réseau (par ex. /sdn/zones/localnetwork/vmbr1/20).

Commandes CLI et WebGUI

Commandes CLI (les 4 attributions)

Remplacez les valeurs pour l'utilisateur, le token API, le pool, le stockage et le réseau par les vôtres.

# 1. Permissions système générales
pvesh set /access/acl --path '/' \
--roles 'OpenVLE-Infra-General' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 2. Permissions VM dans le pool
pvesh set /access/acl --path '/pool/OpenVLE-VMs' \
--roles 'OpenVLE-Infra-VMs' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 3. Permissions de stockage
pvesh set /access/acl --path '/storage/ceph' \
--roles 'PVEDatastoreUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

# 4. Permissions SDN/réseau
pvesh set /access/acl --path '/sdn/zones/localnetwork/vmbr1/10' \
--roles 'PVESDNUser' \
--users 'OpenVLE@pve' --tokens 'OpenVLE@pve!prod01'

WebGUI

Pour chacune des 4 attributions :

Datacenter -> Permissions -> Add -> User Permission
Datacenter -> Permissions -> Add -> API Token Permission

Sélectionnez le chemin et le rôle, puis définissez Propagate sur True.

Référence API

OpenVLE utilise les endpoints API Proxmox VE suivants. Cette vue d'ensemble sert de référence pour l'analyse des erreurs liées aux permissions. La documentation API complète de Proxmox est disponible dans le PVE API Viewer.

Vue d'ensemble complète des endpoints API

Opérations cluster

Les endpoints avec le privilège « Aucun* » ne nécessitent pas de privilège explicite, mais ne retournent que les objets auxquels l'utilisateur ou le token a accès via d'autres permissions (par ex. Sys.Audit, VM.Audit). L'ensemble des résultats est filtré dynamiquement par Proxmox en fonction des permissions existantes.

Endpoint	Méthode	Privilège requis	Fonction
/cluster/resources	GET	Aucun*	Interroger les ressources du cluster et l'affectation des nœuds
/cluster/status	GET	Sys.Audit	Interroger le statut du cluster
/cluster/nextid	GET	Aucun*	Déterminer le prochain ID de VM disponible
/cluster/log	GET	Aucun*	Récupérer les logs PVE
/cluster/tasks	GET	Aucun*	Lister les tâches du cluster en cours
/nodes	GET	Aucun	Lister tous les nœuds PVE
/nodes/{node}/rrd	GET	Sys.Audit	Consulter les statistiques du nœud

Haute disponibilité (HA)

Endpoint	Méthode	Privilège requis	Fonction
/cluster/ha/resources	GET	Sys.Audit	Lister toutes les ressources HA
/cluster/ha/resources	POST	Sys.Console	Activer la HA pour une VM
/cluster/ha/resources/{sid}	GET	Sys.Audit	Interroger le statut HA d'une VM
/cluster/ha/resources/{sid}	PUT	Sys.Console	Modifier la configuration HA d'une VM
/cluster/ha/resources/{sid}	DELETE	Sys.Console	Désactiver la HA pour une VM

Gestion des VMs

Endpoint	Méthode	Privilège requis	Fonction
/nodes/{node}/qemu/{vmid}/config	GET	VM.Audit	Interroger la configuration de la VM
/nodes/{node}/qemu/{vmid}/config	PUT	VM.Config.*	Modifier la configuration de la VM
/nodes/{node}/qemu/{vmid}/status/current	GET	VM.Audit	Interroger le statut actuel de la VM
/nodes/{node}/qemu/{vmid}/clone	POST	VM.Clone, VM.Allocate	Cloner une VM ou un template
/nodes/{node}/qemu/{vmid}	DELETE	VM.Allocate	Supprimer une VM
/nodes/{node}/qemu/{vmid}/migrate	POST	VM.Migrate	Migrer une VM vers un autre nœud
/nodes/{node}/qemu/{vmid}/cloudinit	PUT	VM.Audit	Régénérer la configuration CloudInit
/nodes/{node}/qemu/{vmid}/agent/network-get-interfaces	GET	VM.Monitor	Lire les interfaces réseau (IPv4)
/nodes/{node}/tasks/{upid}/status	GET	Sys.Audit	Interroger le statut d'une tâche

Contrôle des VMs (Power Management)

Endpoint	Méthode	Privilège requis	Fonction
/nodes/{node}/qemu/{vmid}/status/{action}	POST	VM.PowerMgmt	Contrôler la VM : start, stop, shutdown, reboot, reset, resume, suspend