# API Proxmox VE ## Principes L'application doit utiliser l'API REST Proxmox VE en lecture seule. Etat actuel : le module `pve_client.py` implemente la connexion API reutilisable et les tests des endpoints `/nodes`, `/storage`, `/cluster` et de l'endpoint configure pour les jobs de sauvegarde. La collecte des stockages PBS, des jobs de sauvegarde, des VM/CT et des pools est implementee. Le calcul de couverture prend en charge les `vmid` explicitement listes dans les jobs actifs, les jobs `all=1` et les jobs `pool=`. L'URL de base suit generalement ce format : ```text https://:8006/api2/json ``` Le script peut interroger n'importe quel noeud disponible du cluster pour les endpoints globaux. ## Authentification par token L'authentification recommandee utilise l'en-tete HTTP `Authorization`. Format : ```text Authorization: PVEAPIToken== ``` Le token secret ne doit jamais etre logue. Dans `.env`, renseigner : ```env PVE_API_TOKEN_ID=backup-report@pve!report PVE_API_TOKEN_SECRET=secret-fourni-par-pve ``` ## Endpoints utiles Les endpoints exacts doivent etre verifies avec la version PVE cible pendant l'implementation. Endpoints generalement utiles : | Besoin | Endpoint indicatif | | --- | --- | | Version PVE | `/version` | | Ressources cluster | `/cluster/resources` | | Configuration des stockages | `/storage` | | Index cluster | `/cluster` | | Jobs de sauvegarde | `/cluster/backup` | | Pools | `/pools` et `/pools/{poolid}` | | Taches de sauvegarde recentes | `/cluster/tasks` et `/nodes/{node}/tasks` | | Configuration VM QEMU | `/nodes/{node}/qemu/{vmid}/config` | | Configuration conteneur LXC | `/nodes/{node}/lxc/{vmid}/config` | | Statut des noeuds | `/nodes` | La valeur nominale pour les jobs de sauvegarde est : ```text /cluster/backup ``` `PVE_BACKUP_JOBS_ENDPOINT` existe seulement comme override technique. La valeur attendue reste `/cluster/backup`. Privilege observe pour les jobs de sauvegarde : ```text Sys.Audit sur / ``` Si le token ne possede pas ce privilege, PVE retourne typiquement `HTTP 403 - Permission check failed (/, Sys.Audit)`. Avec les tokens en privileges separes, avoir `PVEAuditor` visible dans l'interface ne suffit pas toujours : il faut verifier les droits effectifs du token, pas seulement ceux de l'utilisateur parent. Verification manuelle : ```sh PYTHONPATH=src python3 -m pve_backup_report --check-api ``` La commande affiche uniquement le statut et le nombre d'elements retournes. Elle ne journalise pas le token secret. Les endpoints sont testes independamment. Un echec sur l'endpoint des jobs de sauvegarde n'empeche pas d'afficher le resultat de `/nodes`, `/storage` et `/cluster`. ## Stockages PBS Un stockage PBS est generalement identifie par un type equivalent a `pbs`. Champs attendus a normaliser : - `storage` ou ID equivalent ; - `type` ; - `server` ; - `datastore` ; - `namespace` ; - `username`. Tous les champs ne sont pas forcement presents selon la version ou la configuration. Le rapport doit afficher une valeur explicite comme `non renseigne` lorsqu'un champ non critique est absent. Pour l'etat actif, PVE expose generalement `disable=1` lorsqu'un storage est desactive et omet le champ lorsque le storage est actif. L'absence de `disable` doit donc etre interpretee comme actif. La commande de diagnostic actuelle est : ```sh PYTHONPATH=src python3 -m pve_backup_report --dump-inventory ``` Elle affiche les stockages PBS normalises sans afficher de secret. ## Ressources VM et CT L'inventaire peut etre construit depuis `/cluster/resources`. Filtrer les types utiles : - `qemu` pour les VM ; - `lxc` pour les conteneurs. Champs utiles : - `vmid` ; - `name` ; - `type` ; - `node` ; - `status`. Les notes des VM/CT sont collectees depuis la configuration de chaque guest sur son noeud courant : - VM QEMU : `/nodes/{node}/qemu/{vmid}/config` ; - conteneurs LXC : `/nodes/{node}/lxc/{vmid}/config`. Le champ attendu est `description`. Si la configuration d'une VM/CT est indisponible, la collecte continue, une anomalie `guests` est ajoutee, et la note est affichee comme `non renseigné` dans le rapport. Commande de diagnostic : ```sh PYTHONPATH=src python3 -m pve_backup_report --dump-coverage ``` Commande de previsualisation du modele final : ```sh PYTHONPATH=src python3 -m pve_backup_report --dump-report-data ``` ## Derniere sauvegarde realisee L'etat de la derniere sauvegarde est deduit des taches PVE recentes recuperees via `/cluster/tasks` et `/nodes/{node}/tasks` sans parametre, puis filtrees localement sur le type `vzdump`. Le nombre de taches inspectees localement est controle par `PVE_TASK_HISTORY_LIMIT`. Le nombre de lignes recuperees pour chaque log de tache est controle par `PVE_TASK_LOG_LIMIT`. Si l'historique des taches est indisponible, la generation du rapport continue et une anomalie est ajoutee. Pour les jobs qui sauvegardent plusieurs VM/CT, le resultat par VM/CT est extrait du log de la tache via `/nodes/{node}/tasks/{upid}/log`. La duree de sauvegarde est extraite en priorite des lignes `Finished Backup of ... (HH:MM:SS)`, car cette valeur correspond a la VM/CT concernee. En repli, pour une tache simple ou une VM/CT explicitement demarree dans le log, elle peut etre calculee depuis `starttime` et `endtime`. Le VMID est extrait depuis les lignes de log `Starting Backup of ...`, `Finished Backup of ...` et `Backup of ... failed`. Si le log est indisponible, le script tente un repli depuis les champs `vmid`, `id`, `guest` ou `upid`. Si une VM/CT vient d'etre ajoutee a un job et n'a pas encore eu de sauvegarde terminee dans l'historique disponible, aucun resultat de derniere sauvegarde ne peut etre renseigne. ## Jobs de sauvegarde Les jobs de sauvegarde PVE contiennent les informations necessaires pour determiner : - activation ou desactivation du job ; - cible storage ; - planification ; - selection des VM/CT ; - exclusions eventuelles ; - mode de sauvegarde. L'implementation doit distinguer : - les jobs actifs ; - les jobs desactives ; - les jobs ciblant un PBS ; - les jobs ciblant un autre type de storage. Etat actuel : les jobs sont normalises avec ID, storage, schedule, activation, mode, selection brute et exclusions brutes. Le calcul de couverture interprete les listes explicites `vmid=...`, les jobs `all=1`, les jobs `pool=`, et les exclusions simples. Si un job reference un pool absent ou impossible a collecter, la couverture concernee reste `indetermine`. ## Planification PVE peut exprimer les horaires avec une syntaxe de calendrier. Le rapport doit afficher la valeur brute si le parsing complet n'est pas implemente. Si une interpretation lisible est ajoutee, conserver aussi la valeur source en cas d'ambiguite. ## Anomalies de collecte Ajouter une anomalie lorsque : - un endpoint retourne une erreur ; - une reponse est incomplete ; - un job reference un storage inconnu ; - un type de selection de VM n'est pas pris en charge ; - un champ indispensable a l'analyse est absent. Une anomalie doit contenir : - une severite ; - le composant concerne ; - un message court ; - des details techniques non sensibles. ## Erreurs gerees par le client Le client distingue : - erreur de connexion ou timeout ; - erreur HTTP avec endpoint et code retour ; - reponse JSON invalide ; - reponse JSON sans champ `data`. Les messages d'erreur ne doivent jamais inclure `PVE_API_TOKEN_SECRET`. ## TLS La connexion API peut etre executee avec `PVE_VERIFY_TLS=false` lorsque la CA existante n'est pas compatible avec la validation stricte de Python/OpenSSL et ne peut pas etre remplacee.