160 lines
4.6 KiB
Markdown
160 lines
4.6 KiB
Markdown
# Target Architecture
|
|
|
|
[Version francaise](../fr/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.
|