PVE-Backup-Report/docs/api-pve.md

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=<nom>.

L'URL de base suit generalement ce format :

https://<pve-host>: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 :

Authorization: PVEAPIToken=<token-id>=<token-secret>

Le token secret ne doit jamais etre logue.

Dans .env, renseigner :

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 :

/cluster/backup

PVE_BACKUP_JOBS_ENDPOINT existe seulement comme override technique. La valeur attendue reste /cluster/backup.

Privilege observe pour les jobs de sauvegarde :

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 :

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 :

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 :

PYTHONPATH=src python3 -m pve_backup_report --dump-coverage

Commande de previsualisation du modele final :

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=<nom>, 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.