Organize documentation by language
This commit is contained in:
@@ -0,0 +1,228 @@
|
||||
# API Proxmox VE
|
||||
|
||||
[English version](../en/api-pve.md)
|
||||
|
||||
## 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 :
|
||||
|
||||
```text
|
||||
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 :
|
||||
|
||||
```text
|
||||
Authorization: PVEAPIToken=<token-id>=<token-secret>
|
||||
```
|
||||
|
||||
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=<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.
|
||||
Reference in New Issue
Block a user