Add English documentation
This commit is contained in:
@@ -0,0 +1,159 @@
|
||||
# Target Architecture
|
||||
|
||||
[Version francaise](../architecture.md)
|
||||
|
||||
## Overview
|
||||
|
||||
The application is a batch tool designed to run once per day. It collects data from the Proxmox VE API, transforms it into internal objects, computes backup coverage, then generates a timestamped PDF report.
|
||||
|
||||
The Docker container runs a single command and exits with an explicit return code.
|
||||
|
||||
Current repository state: the CLI, configuration, logging, PVE/PBS collection, coverage analysis and WeasyPrint PDF generation are implemented. The Docker container includes the system dependencies required for PDF rendering.
|
||||
|
||||
## Components
|
||||
|
||||
### CLI
|
||||
|
||||
The CLI is the script entry point.
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- load configuration;
|
||||
- initialize logging;
|
||||
- run collection;
|
||||
- run analysis;
|
||||
- generate the PDF;
|
||||
- return an appropriate exit code.
|
||||
|
||||
### Configuration
|
||||
|
||||
The configuration module reads environment variables and validates required values.
|
||||
|
||||
It must not contain API call logic.
|
||||
|
||||
### PVE Client
|
||||
|
||||
The PVE client encapsulates HTTP calls to the Proxmox VE API.
|
||||
|
||||
The client uses `requests` and a reusable session.
|
||||
|
||||
It implements:
|
||||
|
||||
- API token authentication;
|
||||
- configurable TLS verification;
|
||||
- optional CA bundle;
|
||||
- network timeout;
|
||||
- dedicated errors for connection, HTTP and invalid response failures;
|
||||
- verification methods for `/nodes`, `/storage` and `/cluster/backup`.
|
||||
|
||||
It handles:
|
||||
|
||||
- base URL;
|
||||
- token authentication;
|
||||
- TLS verification;
|
||||
- HTTP errors;
|
||||
- timeouts;
|
||||
- JSON deserialization.
|
||||
|
||||
### Collectors
|
||||
|
||||
Collectors retrieve raw information:
|
||||
|
||||
- storages;
|
||||
- backup jobs;
|
||||
- cluster resources;
|
||||
- useful VM and CT information;
|
||||
- VM/CT notes from their node-local configuration;
|
||||
- PBS prune jobs, when PBS collection is configured;
|
||||
- PBS snapshots by datastore and namespace, when the corresponding PBS collection is configured.
|
||||
|
||||
Each collector must return structured data, not raw JSON scattered across the application.
|
||||
|
||||
Current state: collection of PBS storages via `/storage`, backup jobs via `/cluster/backup`, VM/CT via `/cluster/resources`, pools via `/pools`, latest `vzdump` tasks via `/cluster/tasks` and `/nodes/{node}/tasks`, plus prune jobs and snapshots via the PBS API, is implemented.
|
||||
|
||||
### Models
|
||||
|
||||
Models represent internal entities:
|
||||
|
||||
- `PbsStorage`;
|
||||
- `PbsRetentionPolicy`;
|
||||
- `PbsBackupSnapshotSummary`;
|
||||
- `Guest`;
|
||||
- `BackupJob`;
|
||||
- `BackupCoverage`;
|
||||
- `ReportData`;
|
||||
- `ReportSummary`;
|
||||
- `CollectionIssue`.
|
||||
|
||||
Models can be implemented with `dataclasses` or Pydantic depending on project choices.
|
||||
|
||||
### Coverage Analysis
|
||||
|
||||
The analysis module compares the VM/CT inventory with active backup jobs.
|
||||
|
||||
It produces one status per VM/CT:
|
||||
|
||||
- `sauvegarde_planifiee`;
|
||||
- `non_sauvegardee`;
|
||||
- `indetermine`.
|
||||
|
||||
Current state: coverage based on explicitly listed `vmid` values, `all=1` and `pool=<name>` is computed. Simple exclusions are handled.
|
||||
|
||||
### PDF Generation
|
||||
|
||||
The PDF generator receives a complete `ReportData` object and produces a file.
|
||||
|
||||
It must not call the PVE API.
|
||||
|
||||
It must not reread global configuration except for strictly necessary rendering options.
|
||||
|
||||
The main renderer uses `WeasyPrint` from an HTML/CSS template. This keeps business logic separate from presentation and makes visual changes easier.
|
||||
|
||||
The PDF currently contains the summary, PBS storages declared in PVE, PBS storage usage, PBS retention policies, backup jobs, VM/CT without backup, VM/CT coverage, VM/CT backup retention by PBS with expected version count and delta, and anomalies.
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. Load configuration.
|
||||
2. Connect to the PVE API.
|
||||
3. Optionally connect to configured PBS APIs.
|
||||
4. Collect storages.
|
||||
5. Filter PBS storages.
|
||||
6. Collect prune jobs and snapshots, if configured.
|
||||
7. Collect backup jobs.
|
||||
8. Collect VMs and CTs.
|
||||
9. Compute coverage.
|
||||
10. Build the report model.
|
||||
11. Generate the PDF.
|
||||
12. Log result and exit code.
|
||||
|
||||
A preparation step assembles a final `ReportData` object with a computed `ReportSummary`. The `--dump-report-data` command previews this model as JSON.
|
||||
|
||||
The `--generate-pdf` command renders this model as a PDF with WeasyPrint. With Docker Compose, it must be launched explicitly:
|
||||
|
||||
```sh
|
||||
docker compose run --rm pve-backup-report --generate-pdf
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Blocking errors stop execution:
|
||||
|
||||
- invalid configuration;
|
||||
- authentication failure;
|
||||
- PVE API fully unavailable;
|
||||
- inability to write the PDF.
|
||||
|
||||
Partial errors can be added to the report:
|
||||
|
||||
- a node does not respond;
|
||||
- an expected field is missing;
|
||||
- a job cannot be interpreted;
|
||||
- a referenced storage is missing from collection.
|
||||
|
||||
## Idempotence
|
||||
|
||||
Daily execution must not modify PVE state.
|
||||
|
||||
The tool is read-only with regard to the cluster.
|
||||
|
||||
The only expected side effect is the creation of a new report in the output directory.
|
||||
Reference in New Issue
Block a user