feat(backup): BackupServerDriver, a role base for backup servers (#82) #83

Merged
christianmanivong merged 1 commits from feat/backup-server-role into main 2026-11-02 19:55:05 +00:00
Owner

Closes #82. Part of NetOrk/netork#1918 (Proxmox Backup Server support).

What

  • BackupServerDriver (ROLE = "backup_server", TYPE_LABEL = "Backup Server"): declarations only, under TYPE_CHECKING, like every role base.
    • Reads: get_backup_datastores, get_backup_groups(datastore="") (each group with its newest snapshot), get_backup_snapshots(datastore, namespace, group_type, group_id), get_backup_jobs, get_backup_remotes.
    • Actions: start_garbage_collection, run_backup_job(kind, job_id), verify_backup_snapshot, set_backup_snapshot_protected, delete_backup_snapshot; they return a BackupTaskDict, followed with get_backup_task.
  • Shapes in napalm_device_types/backups.py (models.py is over the file size limit).
  • ClusterStorageDict.backup_server: NotRequired[BackupServerRefDict | None]: server, port, datastore, namespace, fingerprint of a hypervisor's backup storage.
  • README, docs/STRUCTURE.md, CHANGELOG (Unreleased; the release is a separate step).

Changed from the proposal in #82

  1. Role key backup_server, not backup, like management_controller and residential_gateway.
  2. Garbage collection is a job (kind: "gc", id = datastore) rather than a field on the datastore: it has a schedule and a last run like the other jobs, so there is one place for "did it run, did it fail".
  3. No matching helper for storage ref → server here: docs/STRUCTURE.md keeps what an application does with a device out of this package. It moves to netOrk (NetOrk/netork#1919).
  4. Added get_backup_snapshots (choose one snapshot to protect or delete) and get_backup_task (follow what an action started).

Checks

  • pytest: 1194 passed; new modules 100 % covered, total 96 %.
  • ruff format --check, ruff check, mypy --strict: clean.
  • napalm-standard check: meets the standard; napalm-standard ratchet: within the baseline.

Not breaking: the new key on ClusterStorageDict is optional, so existing hypervisor drivers stay valid. Minor bump (4.25.0) once merged.

Closes #82. Part of NetOrk/netork#1918 (Proxmox Backup Server support). ## What - `BackupServerDriver` (`ROLE = "backup_server"`, `TYPE_LABEL = "Backup Server"`): declarations only, under `TYPE_CHECKING`, like every role base. - Reads: `get_backup_datastores`, `get_backup_groups(datastore="")` (each group with its newest snapshot), `get_backup_snapshots(datastore, namespace, group_type, group_id)`, `get_backup_jobs`, `get_backup_remotes`. - Actions: `start_garbage_collection`, `run_backup_job(kind, job_id)`, `verify_backup_snapshot`, `set_backup_snapshot_protected`, `delete_backup_snapshot`; they return a `BackupTaskDict`, followed with `get_backup_task`. - Shapes in `napalm_device_types/backups.py` (`models.py` is over the file size limit). - `ClusterStorageDict.backup_server: NotRequired[BackupServerRefDict | None]`: server, port, datastore, namespace, fingerprint of a hypervisor's backup storage. - README, `docs/STRUCTURE.md`, CHANGELOG (Unreleased; the release is a separate step). ## Changed from the proposal in #82 1. Role key `backup_server`, not `backup`, like `management_controller` and `residential_gateway`. 2. Garbage collection is a job (`kind: "gc"`, `id` = datastore) rather than a field on the datastore: it has a schedule and a last run like the other jobs, so there is one place for "did it run, did it fail". 3. No matching helper for storage ref → server here: `docs/STRUCTURE.md` keeps what an application does with a device out of this package. It moves to netOrk (NetOrk/netork#1919). 4. Added `get_backup_snapshots` (choose one snapshot to protect or delete) and `get_backup_task` (follow what an action started). ## Checks - `pytest`: 1194 passed; new modules 100 % covered, total 96 %. - `ruff format --check`, `ruff check`, `mypy --strict`: clean. - `napalm-standard check`: meets the standard; `napalm-standard ratchet`: within the baseline. Not breaking: the new key on `ClusterStorageDict` is optional, so existing hypervisor drivers stay valid. Minor bump (4.25.0) once merged.
christianmanivong added the
prio
P2
enhancement
labels 2026-11-02 19:46:59 +00:00
christianmanivong added 1 commit 2026-11-02 19:46:59 +00:00
feat(backup): BackupServerDriver, a role base for backup servers (#82)
driver / lint (pull_request) Successful in 15s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 1m6s
driver / test (3.13) (pull_request) Successful in 1m7s
driver / test (3.12) (pull_request) Successful in 1m15s
driver / lowest (pull_request) Successful in 30s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 58s
CI / driver (pull_request) Successful in 2m22s
driver / publish (pull_request) Skipped
95e3aa1e26
A backup server keeps datastores, one backup group per source with its
snapshots, and the jobs that keep them healthy: garbage collection,
verify, prune, sync and tape. None of that is a pool, a volume or a
replication job, so it is a role of its own instead of being bent into
StorageDriver. A server that manages its own disks lists StorageDriver
second.

The role declares the reads (datastores, groups with their newest
snapshot, a group's snapshots, jobs, remotes) and the actions (garbage
collection, running a job, verifying, protecting and deleting a
snapshot), which start a task and return its id for get_backup_task.
The shapes live in napalm_device_types.backups.

ClusterStorageDict gains an optional backup_server: which server,
datastore and namespace a hypervisor's backup storage writes to, with
the fingerprint it pins. Matching that to a server is the application's.
christianmanivong merged commit 9d6a1a65ed into main 2026-11-02 19:55:05 +00:00
christianmanivong deleted branch feat/backup-server-role 2026-11-02 19:55:05 +00:00
Sign in to join this conversation.