From a6289cb24a82b25652270ab94972fa50b81923d4 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 22:15:01 +0100 Subject: [PATCH] feat: HA state, backups, quorum votes, migrate_vm and node maintenance get_clusters() may also report the cluster's HA resources, backup jobs, the newest backup per guest and storage, and each node's quorum votes (all NotRequired; None means not read). HypervisorDriver declares get_vm_migration_preflight(), migrate_vm() and set_node_maintenance(); the preflight shape lives in vm_migration.py. Part of NetOrk/netork#1820 (stage 7: #759, #760, #761). --- CHANGELOG.md | 15 +++++++ napalm_device_types/__init__.py | 8 ++++ napalm_device_types/clusters.py | 42 +++++++++++++++++++ napalm_device_types/hypervisor.py | 35 ++++++++++++++++ napalm_device_types/vm_migration.py | 26 ++++++++++++ tests/test_clusters.py | 58 ++++++++++++++++++++++++- tests/test_vm_migration.py | 65 +++++++++++++++++++++++++++++ 7 files changed, 247 insertions(+), 2 deletions(-) create mode 100644 napalm_device_types/vm_migration.py create mode 100644 tests/test_vm_migration.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad65a9..7f1879e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,21 @@ recorded here; their history is the git log. 3.12 venv no longer has. ### Added +- `HypervisorDriver.get_vm_migration_preflight(name)`, `migrate_vm(name, target_node, + online=True, target_storage=None, timeout=3600)` and `set_node_maintenance(node, + enabled)`: which nodes of its cluster a guest could move to and what blocks it + (`MigrationPreflightDict`: `allowed_nodes`, `refused_nodes` with the platform's + reason, `local_disks` the migration copies, `local_resources` that block it), the + move itself, blocking until the platform's task ended and raising with the + platform's own cause, and a node's HA maintenance mode. Declared only; netOrk + probes each with `hasattr`. +- `get_clusters()` may report HA, backups and quorum votes: `ClusterDict.ha_resources` + (`HAResourceDict`: requested and current state, node, PVE 8 group, PVE 9 rules), + `backup_jobs` (`BackupJobDict`: schedule, storage, mode, the guests a job covers) + and `backups` (`BackupDict`: per guest and storage the newest backup, its size + and how many there are), and `ClusterNodeDict.votes`. All `NotRequired`, so + drivers written before stay valid; None means could not be read, `[]` read and + empty. - `HypervisorDriver.get_clusters()` and its shapes `ClusterDict`, `ClusterNodeDict`, `ClusterStorageDict`, `ClusterNetworkDict`: every cluster the connection can see, with its nodes (offline ones included, `local` on the node the connection is), diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 743e0d5..31df183 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -88,10 +88,13 @@ from napalm_device_types.channel import ( run_on_transport, ) from napalm_device_types.clusters import ( + BackupDict, + BackupJobDict, ClusterDict, ClusterNetworkDict, ClusterNodeDict, ClusterStorageDict, + HAResourceDict, ) from napalm_device_types.config_lifecycle import ConfigLifecycleMixin from napalm_device_types.config_sync import ConfigSyncMixin @@ -238,13 +241,18 @@ from napalm_device_types.virtual_ips import ( VirtualIpsMixin, parse_virtual_ips, ) +from napalm_device_types.vm_migration import MigrationPreflightDict from napalm_device_types.vm_stop_request import VmStopRequestMixin __all__ = [ + "BackupDict", + "BackupJobDict", "ClusterDict", "ClusterNetworkDict", "ClusterNodeDict", "ClusterStorageDict", + "HAResourceDict", + "MigrationPreflightDict", "HypervisorHostDict", "DnsForwardDict", "DnsForwardMixin", diff --git a/napalm_device_types/clusters.py b/napalm_device_types/clusters.py index c5e136e..cbc77ab 100644 --- a/napalm_device_types/clusters.py +++ b/napalm_device_types/clusters.py @@ -21,6 +21,7 @@ class ClusterNodeDict(TypedDict): cpu_usage: float | None # 0.0–1.0 memory_total: int | None # bytes memory_used: int | None # bytes + votes: NotRequired[int | None] # quorum votes of this node; None standalone/unreadable class ClusterStorageDict(TypedDict): @@ -45,6 +46,43 @@ class ClusterNetworkDict(TypedDict): nodes: list[str] +class HAResourceDict(TypedDict): + """A guest the cluster's HA manager looks after.""" + + vmid: int + kind: str # "qemu" or "lxc" + requested: str # state HA is asked to keep: "started", "stopped", "disabled", "ignored" + status: str | None # what the HA manager reports now: "started", "fence", "migrate", ... + node: str | None # the node the HA manager places it on now + group: NotRequired[str | None] # HA group (Proxmox VE 8) + rules: list[str] # ids of the HA rules that name it (Proxmox VE 9); [] where there are none + + +class BackupJobDict(TypedDict): + """A scheduled backup job of the cluster.""" + + id: str + enabled: bool + schedule: str | None # as the platform writes it: "sat 02:00", "daily", "mon..fri 21:00" + storage: str | None + mode: str | None # "snapshot", "suspend", "stop" + all: bool # every guest, minus ``exclude`` + vmids: list[int] # the guests it names; a pool job: the pool's members now; [] with all + exclude: list[int] + pool: str | None + node: str | None # the one node it runs on; None for every node + + +class BackupDict(TypedDict): + """The backups of one guest on one storage.""" + + vmid: int + storage: str + time: int # unix seconds of the newest backup of this guest on this storage + size: int | None # bytes of that newest backup + count: int # backups of this guest on this storage + + class ClusterDict(TypedDict): """A cluster the connection can see. A standalone host is a cluster of one, with no name.""" @@ -55,3 +93,7 @@ class ClusterDict(TypedDict): nodes: list[ClusterNodeDict] storages: list[ClusterStorageDict] networks: list[ClusterNetworkDict] + # None: could not be read; []: read, nothing there. + ha_resources: NotRequired[list[HAResourceDict] | None] + backup_jobs: NotRequired[list[BackupJobDict] | None] + backups: NotRequired[list[BackupDict] | None] diff --git a/napalm_device_types/hypervisor.py b/napalm_device_types/hypervisor.py index 3618c22..7b2a8d0 100644 --- a/napalm_device_types/hypervisor.py +++ b/napalm_device_types/hypervisor.py @@ -31,6 +31,7 @@ from napalm_device_types.models import ( ) from napalm_device_types.packages import PackageManagementMixin from napalm_device_types.provisioning import QEMU_GUEST_AGENTS, GuestAgents +from napalm_device_types.vm_migration import MigrationPreflightDict class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDriver): @@ -662,6 +663,40 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri """ ... + def get_vm_migration_preflight(self, name: str) -> MigrationPreflightDict: + """Which nodes of its cluster the guest could move to, and what blocks it + (see ``vm_migration``). + + :raises ValueError: If no VM with the given name/ID exists. + """ + ... + + def migrate_vm( + self, + name: str, + target_node: str, + online: bool = True, + target_storage: str | None = None, + timeout: int = 3600, + ) -> None: + """Move the guest to another node of its cluster; block until the + platform's task ended. ``online`` keeps a running guest running. + + :raises ValueError: Unknown VM, or a target that is not another + member of the cluster. + :raises RuntimeError: The migration failed, with the platform's cause. + """ + ... + + def set_node_maintenance(self, node: str, enabled: bool) -> None: + """Switch HA maintenance mode of a cluster node; HA guests leave it + while it is on. + + :raises ValueError: If ``node`` is not a member of the cluster. + :raises RuntimeError: If the platform refuses or cannot be asked. + """ + ... + def get_hypervisor_hosts(self) -> list[HypervisorHostDict]: """The hosts this hypervisor or its manager runs, and how each stands: connected, in maintenance, with configuration issues, under a central diff --git a/napalm_device_types/vm_migration.py b/napalm_device_types/vm_migration.py new file mode 100644 index 0000000..23d14c2 --- /dev/null +++ b/napalm_device_types/vm_migration.py @@ -0,0 +1,26 @@ +"""Moving a guest to another node of its cluster (``HypervisorDriver.migrate_vm``). + +``get_vm_migration_preflight`` reports what the platform says before a move: +which nodes would take the guest, which refuse it and why, and what the guest +holds on its current node. ``migrate_vm`` then moves it and blocks until the +platform's task ended; a failure raises with the platform's own cause. +``set_node_maintenance`` switches a node's HA maintenance mode, which makes the +HA manager move its HA guests away while it is on. + +Facts only: which node to pick, and whether a local disk is worth copying, is +the caller's to decide. +""" + +from typing import TypedDict + + +class MigrationPreflightDict(TypedDict): + """Where a guest could move to, and what stands in the way.""" + + running: bool + allowed_nodes: list[str] # nodes the platform would move it to + refused_nodes: dict[str, str] # node -> the platform's reason, in plain words + # volume ids on storage the target does not share; they block nothing by + # themselves, the migration copies them + local_disks: list[str] + local_resources: list[str] # e.g. "hostpci0", "usb0": they block the migration diff --git a/tests/test_clusters.py b/tests/test_clusters.py index 30e537c..d678669 100644 --- a/tests/test_clusters.py +++ b/tests/test_clusters.py @@ -23,10 +23,13 @@ from typing import NotRequired, get_type_hints import napalm_device_types.hypervisor as hypervisor_module from napalm_device_types import ( + BackupDict, + BackupJobDict, ClusterDict, ClusterNetworkDict, ClusterNodeDict, ClusterStorageDict, + HAResourceDict, HypervisorDriver, ) @@ -52,17 +55,26 @@ class TestClusterListing: class TestClusterShape: def test_cluster(self): - assert get_type_hints(ClusterDict) == { + assert get_type_hints(ClusterDict, include_extras=True) == { "id": str | None, "name": str | None, "quorate": bool | None, "nodes": list[ClusterNodeDict], "storages": list[ClusterStorageDict], "networks": list[ClusterNetworkDict], + "ha_resources": NotRequired[list[HAResourceDict] | None], + "backup_jobs": NotRequired[list[BackupJobDict] | None], + "backups": NotRequired[list[BackupDict] | None], } + def test_cluster_keys_added_later_stay_optional(self): + """A driver written before HA and backups were part of the report stays valid.""" + assert ClusterDict.__required_keys__ == frozenset( + {"id", "name", "quorate", "nodes", "storages", "networks"} + ) + def test_node(self): - hints = get_type_hints(ClusterNodeDict) + hints = get_type_hints(ClusterNodeDict, include_extras=True) assert hints == { "name": str, "status": str, @@ -75,7 +87,9 @@ class TestClusterShape: "cpu_usage": float | None, "memory_total": int | None, "memory_used": int | None, + "votes": NotRequired[int | None], } + assert "votes" not in ClusterNodeDict.__required_keys__ def test_storage(self): assert get_type_hints(ClusterStorageDict) == { @@ -102,6 +116,46 @@ class TestClusterShape: ) +class TestHAAndBackupShapes: + def test_ha_resource(self): + hints = get_type_hints(HAResourceDict, include_extras=True) + assert hints == { + "vmid": int, + "kind": str, + "requested": str, + "status": str | None, + "node": str | None, + "group": NotRequired[str | None], + "rules": list[str], + } + assert HAResourceDict.__required_keys__ == frozenset( + {"vmid", "kind", "requested", "status", "node", "rules"} + ) + + def test_backup_job(self): + assert get_type_hints(BackupJobDict) == { + "id": str, + "enabled": bool, + "schedule": str | None, + "storage": str | None, + "mode": str | None, + "all": bool, + "vmids": list[int], + "exclude": list[int], + "pool": str | None, + "node": str | None, + } + + def test_backup(self): + assert get_type_hints(BackupDict) == { + "vmid": int, + "storage": str, + "time": int, + "size": int | None, + "count": int, + } + + class TestCreateVmTakesANode: def test_node_is_an_optional_keyword(self): fn = _declared("create_vm_from_cloud_init") diff --git a/tests/test_vm_migration.py b/tests/test_vm_migration.py new file mode 100644 index 0000000..18d7a8a --- /dev/null +++ b/tests/test_vm_migration.py @@ -0,0 +1,65 @@ +"""Moving a guest to another node of its cluster, and a node's HA maintenance mode. + +``get_vm_migration_preflight`` says where a guest could go and what holds it +back, ``migrate_vm`` moves it and waits, ``set_node_maintenance`` switches a +node's HA maintenance mode. Declared only, under ``TYPE_CHECKING``: netOrk +probes each with ``hasattr`` and hides what a driver lacks (VMware has none of +them yet). +""" + +from __future__ import annotations + +import ast +import inspect +from typing import get_type_hints + +import pytest + +import napalm_device_types.hypervisor as hypervisor_module +from napalm_device_types import HypervisorDriver, MigrationPreflightDict + + +def _declared(name: str) -> ast.FunctionDef: + tree = ast.parse(inspect.getsource(hypervisor_module)) + for node in ast.walk(tree): + if isinstance(node, ast.FunctionDef) and node.name == name: + return node + raise AssertionError(f"HypervisorDriver does not declare {name}()") + + +def _signature(name: str) -> str: + fn = _declared(name) + return f"({ast.unparse(fn.args)}) -> {ast.unparse(fn.returns) if fn.returns else None}" + + +class TestDeclarations: + @pytest.mark.parametrize( + "method", ["get_vm_migration_preflight", "migrate_vm", "set_node_maintenance"] + ) + def test_absent_until_a_driver_implements_it(self, method): + assert not hasattr(HypervisorDriver, method) + + def test_preflight(self): + assert _signature("get_vm_migration_preflight") == ( + "(self, name: str) -> MigrationPreflightDict" + ) + + def test_migrate(self): + assert _signature("migrate_vm") == ( + "(self, name: str, target_node: str, online: bool=True, " + "target_storage: str | None=None, timeout: int=3600) -> None" + ) + + def test_maintenance(self): + assert _signature("set_node_maintenance") == "(self, node: str, enabled: bool) -> None" + + +class TestPreflightShape: + def test_keys(self): + assert get_type_hints(MigrationPreflightDict) == { + "running": bool, + "allowed_nodes": list[str], + "refused_nodes": dict[str, str], + "local_disks": list[str], + "local_resources": list[str], + }