From 00aa5efef01765f5678d63a3ed8538d576b4a6cf Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 16:38:38 +0100 Subject: [PATCH 1/2] feat: get_clusters() and create_vm_from_cloud_init(node=) A hypervisor reports every cluster its connection can see: the cluster's name and quorum, its nodes (offline ones too, the local one marked) with CPU and memory, and the storages and networks with the nodes that see each. A standalone host is a cluster of one without a name; a manager reports each cluster and standalone host it runs. Declared only, so a capability check stays truthful. create_vm_from_cloud_init() takes the node to create the VM on; a driver that can only create on its own node refuses another. Refs NetOrk/netork#484, NetOrk/netork#1822 --- CHANGELOG.md | 9 +++ napalm_device_types/__init__.py | 8 +++ napalm_device_types/hypervisor.py | 33 +++++++++ napalm_device_types/models.py | 51 +++++++++++++ tests/test_clusters.py | 114 ++++++++++++++++++++++++++++++ 5 files changed, 215 insertions(+) create mode 100644 tests/test_clusters.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 58e1ba6..9ad65a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,15 @@ recorded here; their history is the git log. 3.12 venv no longer has. ### Added +- `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), + their CPU and memory, and the storages and networks with the nodes that see each. + A standalone host is a cluster of one with no name; a manager reports each cluster + and standalone host it runs. Declared only (NetOrk/netork#484, #1821). +- `create_vm_from_cloud_init(node=…)`: the cluster node to create the VM on. None + leaves it to the driver; a driver that can only create on its own node raises + ValueError for another (NetOrk/netork#1822). - `LocalAccountsMixin.add_service_account(name, public_key)`: netOrk's own account, created through the account the driver logs in with today. It takes a key and no password, and a rule of its own in `85-service-` lets it run everything as diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index a3d1e8f..f455983 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -135,6 +135,10 @@ from napalm_device_types.management_controller import ManagementControllerDriver from napalm_device_types.media import MediaDriver from napalm_device_types.models import ( POWER_ACTIONS, + ClusterDict, + ClusterNetworkDict, + ClusterNodeDict, + ClusterStorageDict, ConfigSyncDict, DhcpHaDict, DhcpHaPeerDict, @@ -235,6 +239,10 @@ from napalm_device_types.virtual_ips import ( from napalm_device_types.vm_stop_request import VmStopRequestMixin __all__ = [ + "ClusterDict", + "ClusterNetworkDict", + "ClusterNodeDict", + "ClusterStorageDict", "HypervisorHostDict", "DnsForwardDict", "DnsForwardMixin", diff --git a/napalm_device_types/hypervisor.py b/napalm_device_types/hypervisor.py index 86c3d42..655a709 100644 --- a/napalm_device_types/hypervisor.py +++ b/napalm_device_types/hypervisor.py @@ -15,6 +15,7 @@ from typing import TYPE_CHECKING, Any from napalm_device_types.base import DeviceTypeDriver from napalm_device_types.health_metrics import HealthMetricsMixin from napalm_device_types.models import ( + ClusterDict, HypervisorHostDict, NetworkTargetDict, NICConfigDict, @@ -464,6 +465,7 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri storage: str | None = None, cpu_type: str | None = None, guest_os: str = "linux", + node: str | None = None, download_timeout: int = 300, timeout: int = 180, ) -> VMProvisionResultDict: @@ -519,6 +521,13 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri network-config itself (``provisioning.network_config``). A guest_os the driver does not list raises ValueError before anything is created. Default ``"linux"``. + node (string | None) - the cluster node to create the VM on, a + node ``name`` from ``get_clusters()``. None leaves it to the + driver: the node this connection talks to, or, on a manager of + several hosts, a host of the driver's choosing. A driver that + can only create on its own node raises ValueError for any other + name, before creating anything. ``storage`` and the NICs' + bridges must then be ones that node sees. download_timeout (int) - maximum seconds to wait for the image download (skipped entirely if already cached on the hypervisor). Default 300. timeout (int) - maximum seconds to wait for the remaining provisioning @@ -637,6 +646,30 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri """ ... + def get_clusters(self) -> list[ClusterDict]: + """ + List the clusters this connection can see, each with its nodes, its + storages and its networks. + + A cluster member (a Proxmox node) reports its one cluster, the whole of + it: every node, offline ones included with ``status`` ``"offline"``, and + ``local`` set on the node it is. A manager (vCenter) reports each + cluster it runs, and each standalone host it runs as a cluster of one. + A standalone host reports itself as a cluster of one, ``name`` None. + + The VMs ``get_vms()`` lists name their node in ``node``; that name is + the node's ``name`` here. A storage or network lists the nodes it is + available on, so a caller can tell where a VM may go. A value the + platform does not report is None, never a guess. + + Facts only: which node is a good place for a VM is the caller's to + decide. + + Returns: + List[ClusterDict] + """ + ... + 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/models.py b/napalm_device_types/models.py index 112a57c..3819fa1 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1195,6 +1195,57 @@ class HypervisorHostDict(TypedDict): managed_by: NotRequired[str | None] # the address of a central manager, if any +class ClusterNodeDict(TypedDict): + """One host of a cluster, as its cluster sees it. A value the platform does not + report is None; it is never guessed.""" + + name: str # the node's name in its cluster, as get_vms() reports it in ``node`` + status: str # "online", "offline" or "unknown" + local: bool # the node this connection talks to; False on a manager (vCenter) + maintenance: bool | None # in maintenance mode + cpu_threads: int | None # logical CPUs + cpu_cores: int | None # physical cores + cpu_model: str | None + cpu_flags: list[str] | None # cpuinfo flags; None where the platform does not say + cpu_usage: float | None # 0.0–1.0 + memory_total: int | None # bytes + memory_used: int | None # bytes + + +class ClusterStorageDict(TypedDict): + """A storage of a cluster and the nodes that see it.""" + + name: str # usable as create_vm_from_cloud_init(storage=...) on each of ``nodes`` + type: str # backend type: "dir", "lvmthin", "zfspool", "nfs", "rbd", "vmfs", ... + shared: bool # the same storage on every node in ``nodes``, so a VM on it can move + content: list[str] # what it holds: "images", "iso", "snippets", ... + nodes: list[str] # the nodes it is available on + total: int | None # bytes; None where the platform does not report it + used: int | None # bytes + + +class ClusterNetworkDict(TypedDict): + """A network a VM's NIC may attach to, and the nodes that carry it.""" + + name: str # usable as NICConfigDict.bridge on each of ``nodes`` + kind: str # "bridge", "vnet" or "portgroup", as in NetworkTargetDict + vlan_aware: bool # True if a NICConfigDict.vlan_tag may be set on top of it + fixed_vlan_tag: NotRequired[int | None] # vnet/portgroup: the VLAN baked into it + nodes: list[str] + + +class ClusterDict(TypedDict): + """A cluster the connection can see. A standalone host is a cluster of one, + with no name.""" + + id: str | None # stable across connections where the platform has one; None otherwise + name: str | None # the cluster's name; None for a standalone host + quorate: bool | None # None where the platform has no quorum (standalone, vSphere) + nodes: list[ClusterNodeDict] + storages: list[ClusterStorageDict] + networks: list[ClusterNetworkDict] + + class FixStepOutcomeDict(TypedDict): """What one step of a fix routine reports (see ``napalm_device_types.fixes``).""" diff --git a/tests/test_clusters.py b/tests/test_clusters.py new file mode 100644 index 0000000..30e537c --- /dev/null +++ b/tests/test_clusters.py @@ -0,0 +1,114 @@ +"""A hypervisor says which cluster it belongs to, and what that cluster holds. + +A Proxmox node is one member of a cluster and can read the whole of it; a vCenter +manages several clusters and standalone hosts at once; a standalone host is a +cluster of one. One getter serves all three: ``get_clusters()`` lists every +cluster the connection can see, each with its nodes, its storages and its +networks, and which nodes see which. What a caller does with that (placement, +headroom, identity) is the caller's. + +A new VM can be placed on a named node (``create_vm_from_cloud_init(node=…)``), +so a manager that runs several hosts takes the caller's choice instead of making +its own. + +The declarations sit under ``TYPE_CHECKING`` (see test_role_contracts), so the +signatures are read from the source rather than from the class. +""" + +from __future__ import annotations + +import ast +import inspect +from typing import NotRequired, get_type_hints + +import napalm_device_types.hypervisor as hypervisor_module +from napalm_device_types import ( + ClusterDict, + ClusterNetworkDict, + ClusterNodeDict, + ClusterStorageDict, + HypervisorDriver, +) + + +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}()") + + +class TestClusterListing: + def test_is_declared(self): + fn = _declared("get_clusters") + assert ast.unparse(fn.returns) == "list[ClusterDict]" + + def test_absent_until_a_driver_implements_it(self): + """netOrk probes capabilities with hasattr; a hypervisor that cannot + describe its cluster must not seem to.""" + assert not hasattr(HypervisorDriver, "get_clusters") + + +class TestClusterShape: + def test_cluster(self): + assert get_type_hints(ClusterDict) == { + "id": str | None, + "name": str | None, + "quorate": bool | None, + "nodes": list[ClusterNodeDict], + "storages": list[ClusterStorageDict], + "networks": list[ClusterNetworkDict], + } + + def test_node(self): + hints = get_type_hints(ClusterNodeDict) + assert hints == { + "name": str, + "status": str, + "local": bool, + "maintenance": bool | None, + "cpu_threads": int | None, + "cpu_cores": int | None, + "cpu_model": str | None, + "cpu_flags": list[str] | None, + "cpu_usage": float | None, + "memory_total": int | None, + "memory_used": int | None, + } + + def test_storage(self): + assert get_type_hints(ClusterStorageDict) == { + "name": str, + "type": str, + "shared": bool, + "content": list[str], + "nodes": list[str], + "total": int | None, + "used": int | None, + } + + def test_network(self): + hints = get_type_hints(ClusterNetworkDict, include_extras=True) + assert hints == { + "name": str, + "kind": str, + "vlan_aware": bool, + "fixed_vlan_tag": NotRequired[int | None], + "nodes": list[str], + } + assert ClusterNetworkDict.__required_keys__ == frozenset( + {"name", "kind", "vlan_aware", "nodes"} + ) + + +class TestCreateVmTakesANode: + def test_node_is_an_optional_keyword(self): + fn = _declared("create_vm_from_cloud_init") + kwonly = { + arg.arg: default + for arg, default in zip(fn.args.kwonlyargs, fn.args.kw_defaults, strict=True) + } + assert "node" in kwonly + default = kwonly["node"] + assert isinstance(default, ast.Constant) and default.value is None -- 2.54.0 From 5b894913e1eaa6d0cf2d38081a8bb70c7c450175 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 17:08:10 +0100 Subject: [PATCH 2/2] refactor: the cluster shapes in clusters.py, a shorter provisioning docstring models.py is over the file size limit and may not grow, and the declaration of create_vm_from_cloud_init() may not get longer: the four cluster shapes move to napalm_device_types/clusters.py (exported from the package as before), and the docstring says the same in fewer lines. Refs NetOrk/netork#484 --- napalm_device_types/__init__.py | 10 +++--- napalm_device_types/clusters.py | 57 +++++++++++++++++++++++++++++++ napalm_device_types/hypervisor.py | 22 ++++-------- napalm_device_types/models.py | 51 --------------------------- 4 files changed, 70 insertions(+), 70 deletions(-) create mode 100644 napalm_device_types/clusters.py diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index f455983..743e0d5 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -87,6 +87,12 @@ from napalm_device_types.channel import ( open_stream_on_transport, run_on_transport, ) +from napalm_device_types.clusters import ( + ClusterDict, + ClusterNetworkDict, + ClusterNodeDict, + ClusterStorageDict, +) from napalm_device_types.config_lifecycle import ConfigLifecycleMixin from napalm_device_types.config_sync import ConfigSyncMixin from napalm_device_types.container_engine import ( @@ -135,10 +141,6 @@ from napalm_device_types.management_controller import ManagementControllerDriver from napalm_device_types.media import MediaDriver from napalm_device_types.models import ( POWER_ACTIONS, - ClusterDict, - ClusterNetworkDict, - ClusterNodeDict, - ClusterStorageDict, ConfigSyncDict, DhcpHaDict, DhcpHaPeerDict, diff --git a/napalm_device_types/clusters.py b/napalm_device_types/clusters.py new file mode 100644 index 0000000..c5e136e --- /dev/null +++ b/napalm_device_types/clusters.py @@ -0,0 +1,57 @@ +"""The shapes of a hypervisor's clusters (``HypervisorDriver.get_clusters()``). + +Apart from ``models.py``, which is over the file size limit. +""" + +from typing import NotRequired, TypedDict + + +class ClusterNodeDict(TypedDict): + """One host of a cluster, as its cluster sees it. A value the platform does not + report is None; it is never guessed.""" + + name: str # the node's name in its cluster, as get_vms() reports it in ``node`` + status: str # "online", "offline" or "unknown" + local: bool # the node this connection talks to; False on a manager (vCenter) + maintenance: bool | None # in maintenance mode + cpu_threads: int | None # logical CPUs + cpu_cores: int | None # physical cores + cpu_model: str | None + cpu_flags: list[str] | None # cpuinfo flags; None where the platform does not say + cpu_usage: float | None # 0.0–1.0 + memory_total: int | None # bytes + memory_used: int | None # bytes + + +class ClusterStorageDict(TypedDict): + """A storage of a cluster and the nodes that see it.""" + + name: str # usable as create_vm_from_cloud_init(storage=...) on each of ``nodes`` + type: str # backend type: "dir", "lvmthin", "zfspool", "nfs", "rbd", "vmfs", ... + shared: bool # the same storage on every node in ``nodes``, so a VM on it can move + content: list[str] # what it holds: "images", "iso", "snippets", ... + nodes: list[str] # the nodes it is available on + total: int | None # bytes; None where the platform does not report it + used: int | None # bytes + + +class ClusterNetworkDict(TypedDict): + """A network a VM's NIC may attach to, and the nodes that carry it.""" + + name: str # usable as NICConfigDict.bridge on each of ``nodes`` + kind: str # "bridge", "vnet" or "portgroup", as in NetworkTargetDict + vlan_aware: bool # True if a NICConfigDict.vlan_tag may be set on top of it + fixed_vlan_tag: NotRequired[int | None] # vnet/portgroup: the VLAN baked into it + nodes: list[str] + + +class ClusterDict(TypedDict): + """A cluster the connection can see. A standalone host is a cluster of one, + with no name.""" + + id: str | None # stable across connections where the platform has one; None otherwise + name: str | None # the cluster's name; None for a standalone host + quorate: bool | None # None where the platform has no quorum (standalone, vSphere) + nodes: list[ClusterNodeDict] + storages: list[ClusterStorageDict] + networks: list[ClusterNetworkDict] diff --git a/napalm_device_types/hypervisor.py b/napalm_device_types/hypervisor.py index 655a709..3618c22 100644 --- a/napalm_device_types/hypervisor.py +++ b/napalm_device_types/hypervisor.py @@ -13,9 +13,9 @@ Usage:: from typing import TYPE_CHECKING, Any from napalm_device_types.base import DeviceTypeDriver +from napalm_device_types.clusters import ClusterDict from napalm_device_types.health_metrics import HealthMetricsMixin from napalm_device_types.models import ( - ClusterDict, HypervisorHostDict, NetworkTargetDict, NICConfigDict, @@ -478,9 +478,7 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri configuration via a storage snippet or similar mechanism. The resulting VM is left in a running state. - Implementations should cache downloaded images by URL/filename on the - hypervisor so repeated provisioning from the same image does not - re-download it every time. + Implementations cache downloaded images on the hypervisor by URL/filename. Args: name (string) - new VM display name @@ -499,10 +497,8 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri image_checksum (string | None) - expected checksum of the downloaded image (e.g. "sha256:"). If given, verified after download; mismatch raises RuntimeError. If None, no verification is performed. - ssh_public_keys (list[str] | None) - SSH public keys to inject into guest. - If None or empty, no SSH key injection is performed. - disk_resize_gb (int | None) - resize root disk to this size in GB. - If None, disk remains the downloaded image's native size. Default None. + ssh_public_keys (list[str] | None) - SSH public keys to inject (None: none). + disk_resize_gb (int | None) - resize root disk to this size in GB (None: keep). storage (string | None) - name of the storage pool to place the root disk on (a name returned by ``get_image_storages()``). If None, the driver auto-detects the first enabled, node-available storage @@ -521,13 +517,9 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri network-config itself (``provisioning.network_config``). A guest_os the driver does not list raises ValueError before anything is created. Default ``"linux"``. - node (string | None) - the cluster node to create the VM on, a - node ``name`` from ``get_clusters()``. None leaves it to the - driver: the node this connection talks to, or, on a manager of - several hosts, a host of the driver's choosing. A driver that - can only create on its own node raises ValueError for any other - name, before creating anything. ``storage`` and the NICs' - bridges must then be ones that node sees. + node (string | None) - a node ``name`` from ``get_clusters()`` to create + the VM on; None leaves it to the driver. One that only creates on its + own node raises ValueError for another, before creating anything. download_timeout (int) - maximum seconds to wait for the image download (skipped entirely if already cached on the hypervisor). Default 300. timeout (int) - maximum seconds to wait for the remaining provisioning diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 3819fa1..112a57c 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1195,57 +1195,6 @@ class HypervisorHostDict(TypedDict): managed_by: NotRequired[str | None] # the address of a central manager, if any -class ClusterNodeDict(TypedDict): - """One host of a cluster, as its cluster sees it. A value the platform does not - report is None; it is never guessed.""" - - name: str # the node's name in its cluster, as get_vms() reports it in ``node`` - status: str # "online", "offline" or "unknown" - local: bool # the node this connection talks to; False on a manager (vCenter) - maintenance: bool | None # in maintenance mode - cpu_threads: int | None # logical CPUs - cpu_cores: int | None # physical cores - cpu_model: str | None - cpu_flags: list[str] | None # cpuinfo flags; None where the platform does not say - cpu_usage: float | None # 0.0–1.0 - memory_total: int | None # bytes - memory_used: int | None # bytes - - -class ClusterStorageDict(TypedDict): - """A storage of a cluster and the nodes that see it.""" - - name: str # usable as create_vm_from_cloud_init(storage=...) on each of ``nodes`` - type: str # backend type: "dir", "lvmthin", "zfspool", "nfs", "rbd", "vmfs", ... - shared: bool # the same storage on every node in ``nodes``, so a VM on it can move - content: list[str] # what it holds: "images", "iso", "snippets", ... - nodes: list[str] # the nodes it is available on - total: int | None # bytes; None where the platform does not report it - used: int | None # bytes - - -class ClusterNetworkDict(TypedDict): - """A network a VM's NIC may attach to, and the nodes that carry it.""" - - name: str # usable as NICConfigDict.bridge on each of ``nodes`` - kind: str # "bridge", "vnet" or "portgroup", as in NetworkTargetDict - vlan_aware: bool # True if a NICConfigDict.vlan_tag may be set on top of it - fixed_vlan_tag: NotRequired[int | None] # vnet/portgroup: the VLAN baked into it - nodes: list[str] - - -class ClusterDict(TypedDict): - """A cluster the connection can see. A standalone host is a cluster of one, - with no name.""" - - id: str | None # stable across connections where the platform has one; None otherwise - name: str | None # the cluster's name; None for a standalone host - quorate: bool | None # None where the platform has no quorum (standalone, vSphere) - nodes: list[ClusterNodeDict] - storages: list[ClusterStorageDict] - networks: list[ClusterNetworkDict] - - class FixStepOutcomeDict(TypedDict): """What one step of a fix routine reports (see ``napalm_device_types.fixes``).""" -- 2.54.0