BackupServerDriver: a role base for backup servers, and the PBS identity of a cluster storage #82

Closed
opened 2026-11-02 19:11:20 +00:00 by christianmanivong · 1 comment
Owner

Part of NetOrk/netork#1918 (Proxmox Backup Server support). Priority: P2 (important and urgent; blocks the driver).

What

A new role base BackupServerDriver (ROLE = "backup", TYPE_LABEL = "Backup server"), declared like every role base: methods under if TYPE_CHECKING, no implementation. The first driver is napalm-proxmox's ProxmoxBackupDriver, which lists it before StorageDriver. Nothing in the contract is Proxmox-specific; a Veeam or Bacula-style server could implement it.

Contract (proposal)

Reads:

  • get_backup_datastores() -> list[BackupDatastoreDict]: name, path, backend ("local", "s3"), total/used/available (bytes, None if unknown), estimated_full (unix seconds or None), gc (BackupGcStatusDict: last_run, state, removed/pending bytes), maintenance mode, comment.
  • get_backup_groups(datastore: str = "") -> list[BackupGroupDict]: datastore, namespace, type ("vm", "ct", "host"), id ("101", hostname), owner, count, newest (BackupSnapshotDict: time, size, verify state "ok" | "failed" | None, protected, comment), oldest_time.
  • get_backup_jobs() -> list[BackupServerJobDict]: id, kind ("gc", "verify", "prune", "sync", "tape"), datastore, schedule (as written), enabled, last_run, last_state ("ok" | "error" | "warning" | None), last_error, next_run, remote (sync), direction ("pull" | "push").
  • get_backup_remotes() -> list[BackupRemoteDict]: name, host, port, fingerprint, auth id (never the secret).

Actions:

  • start_garbage_collection(datastore), run_backup_job(kind, id), verify_backup_snapshot(datastore, ns, type, id, time), set_backup_snapshot_protected(..., protected), delete_backup_snapshot(...). Each returns a task reference netOrk can follow (BackupTaskDict: upid, started), or raises.

Cluster side (for the PVE↔PBS link):

  • ClusterStorageDict gains backup_server: NotRequired[BackupServerRefDict | None] with server, port, datastore, namespace, fingerprint. A PVE pbs storage fills it; every other type leaves it out.

Generic helpers (concrete, in the base, per the generic-vs-vendor rule):

  • backup_group_key(type, id, namespace); matching a cluster's backup_server ref to a server by fingerprint first, host:port second.

Test-First

  • roles_of / primary_role_of on a class (BackupServerDriver, StorageDriver, …) → backup first, storage second.
  • hasattr stays truthful: the base defines none of the methods at runtime.
  • Matching helper: same fingerprint, different host (DNS name vs IP) → match; same host, different fingerprint → no match.
  • TypedDicts round-trip the recorded shapes from the driver's fixtures (added with the driver).

Release: minor bump (4.25.0), tag, PyPI.

Part of NetOrk/netork#1918 (Proxmox Backup Server support). Priority: P2 (important and urgent; blocks the driver). ## What A new role base **`BackupServerDriver`** (`ROLE = "backup"`, `TYPE_LABEL = "Backup server"`), declared like every role base: methods under `if TYPE_CHECKING`, no implementation. The first driver is `napalm-proxmox`'s `ProxmoxBackupDriver`, which lists it before `StorageDriver`. Nothing in the contract is Proxmox-specific; a Veeam or Bacula-style server could implement it. ## Contract (proposal) Reads: - `get_backup_datastores() -> list[BackupDatastoreDict]`: name, path, backend (`"local"`, `"s3"`), total/used/available (bytes, `None` if unknown), estimated_full (unix seconds or `None`), gc (`BackupGcStatusDict`: last_run, state, removed/pending bytes), maintenance mode, comment. - `get_backup_groups(datastore: str = "") -> list[BackupGroupDict]`: datastore, namespace, type (`"vm"`, `"ct"`, `"host"`), id (`"101"`, hostname), owner, count, newest (`BackupSnapshotDict`: time, size, verify state `"ok" | "failed" | None`, protected, comment), oldest_time. - `get_backup_jobs() -> list[BackupServerJobDict]`: id, kind (`"gc"`, `"verify"`, `"prune"`, `"sync"`, `"tape"`), datastore, schedule (as written), enabled, last_run, last_state (`"ok" | "error" | "warning" | None`), last_error, next_run, remote (sync), direction (`"pull" | "push"`). - `get_backup_remotes() -> list[BackupRemoteDict]`: name, host, port, fingerprint, auth id (never the secret). Actions: - `start_garbage_collection(datastore)`, `run_backup_job(kind, id)`, `verify_backup_snapshot(datastore, ns, type, id, time)`, `set_backup_snapshot_protected(..., protected)`, `delete_backup_snapshot(...)`. Each returns a task reference netOrk can follow (`BackupTaskDict`: upid, started), or raises. Cluster side (for the PVE↔PBS link): - `ClusterStorageDict` gains `backup_server: NotRequired[BackupServerRefDict | None]` with server, port, datastore, namespace, fingerprint. A PVE `pbs` storage fills it; every other type leaves it out. Generic helpers (concrete, in the base, per the generic-vs-vendor rule): - `backup_group_key(type, id, namespace)`; matching a cluster's `backup_server` ref to a server by fingerprint first, host:port second. ## Test-First - [ ] `roles_of` / `primary_role_of` on a class `(BackupServerDriver, StorageDriver, …)` → `backup` first, `storage` second. - [ ] `hasattr` stays truthful: the base defines none of the methods at runtime. - [ ] Matching helper: same fingerprint, different host (DNS name vs IP) → match; same host, different fingerprint → no match. - [ ] TypedDicts round-trip the recorded shapes from the driver's fixtures (added with the driver). Release: minor bump (4.25.0), tag, PyPI.
christianmanivong added the
prio
P2
enhancement
labels 2026-11-02 19:11:20 +00:00
Author
Owner

PR #83. Four changes from the proposal above, approved 2026-11-02:

  1. Role key backup_server instead of backup (like management_controller).
  2. Garbage collection is a job (kind: "gc") instead of a field on the datastore.
  3. The storage-ref-to-server matching helper is not in this package (docs/STRUCTURE.md: what an application does with a device stays out); it moves to NetOrk/netork#1919.
  4. Added get_backup_snapshots and get_backup_task.
PR #83. Four changes from the proposal above, approved 2026-11-02: 1. Role key `backup_server` instead of `backup` (like `management_controller`). 2. Garbage collection is a job (`kind: "gc"`) instead of a field on the datastore. 3. The storage-ref-to-server matching helper is not in this package (`docs/STRUCTURE.md`: what an application does with a device stays out); it moves to NetOrk/netork#1919. 4. Added `get_backup_snapshots` and `get_backup_task`.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: NAPALM/napalm-device-types#82