Merge pull request 'feat: HA state, backups, quorum votes, migrate_vm and node maintenance' (#71) from feat/vm-lifecycle into main
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 15s
driver / types (push) Successful in 58s
driver / test (3.12) (push) Successful in 1m3s
driver / test (3.13) (push) Successful in 53s
driver / lowest (push) Successful in 30s
driver / build (push) Successful in 27s
driver / security (push) Successful in 56s
CI / driver (push) Successful in 2m29s
driver / publish (push) Skipped

This commit was merged in pull request #71.
This commit is contained in:
christianmanivong committed 2026-11-01 21:48:11 +00:00
commit 9c3be46d8a
7 files changed
+247 -2

No files matched your search

+15
View File
@@ -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),
+8
View File
@@ -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",
+42
View File
@@ -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]
+35
View File
@@ -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
+26
View File
@@ -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
+56 -2
View File
@@ -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")
+65
View File
@@ -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],
}