feat: get_clusters() and create_vm_from_cloud_init(node=) #68

Merged
christianmanivong merged 2 commits from feat/cluster-inventory into main 2026-11-01 18:41:05 +00:00
5 changed files with 222 additions and 7 deletions

No files matched your search

+9
View File
@@ -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-<name>` lets it run everything as
+10
View File
@@ -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 (
@@ -235,6 +241,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",
+57
View File
@@ -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]
+32 -7
View File
@@ -13,6 +13,7 @@ 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 (
HypervisorHostDict,
@@ -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:
@@ -476,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
@@ -497,10 +497,8 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri
image_checksum (string | None) - expected checksum of the downloaded
image (e.g. "sha256:<hex>"). 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
@@ -519,6 +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) - 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
@@ -637,6 +638,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
+114
View File
@@ -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