From 4150570a9459369dbade6f50dd83af1296ea55e6 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 22:09:01 +0100 Subject: [PATCH 1/2] feat: VMProvisionIncomplete names the VM a failed creation left behind create_vm_from_cloud_init raised a plain error once the VM existed, so the caller had no id to remove it by. The new RuntimeError carries vmid and node, with the failure as its cause; a failure before the VM exists raises as before. Refs NAPALM/napalm-proxmox#28 --- CHANGELOG.md | 4 ++ README.md | 5 ++- napalm_device_types/__init__.py | 2 + napalm_device_types/hypervisor.py | 3 ++ napalm_device_types/provisioning.py | 29 ++++++++++++++- tests/test_vm_provision_incomplete.py | 53 +++++++++++++++++++++++++++ 6 files changed, 93 insertions(+), 3 deletions(-) create mode 100644 tests/test_vm_provision_incomplete.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad65a9..55a31b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ recorded here; their history is the git log. 3.12 venv no longer has. ### Added +- `VMProvisionIncomplete` (`napalm_device_types.provisioning`): what + `create_vm_from_cloud_init` raises when it fails after the VM was created. A + `RuntimeError` with the failure as its cause and the half-built VM's `vmid` and + `node`, so the caller can remove it with `destroy_vm` (NAPALM/napalm-proxmox#28). - `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/README.md b/README.md index 8a4c22e..bfde346 100644 --- a/README.md +++ b/README.md @@ -547,7 +547,10 @@ any other. A QEMU-based driver takes `provisioning.QEMU_GUEST_AGENTS` (Linux, FreeBSD, OpenBSD). `provisioning.network_config()` writes the network-config v2 every cloud-init flavour reads (FreeBSD's nuageinit reads no other), and `provisioning.split_compression()` says how a packed image is -unpacked; both are the same for every hypervisor. +unpacked; both are the same for every hypervisor. A creation that fails once +the VM exists raises `VMProvisionIncomplete`, a `RuntimeError` that names the +half-built VM (`vmid`, `node`) for the caller to `destroy_vm`, with the failure +as its cause. ### OS / Linux diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 743e0d5..83c4c5a 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -178,6 +178,7 @@ from napalm_device_types.package_updates import ( from napalm_device_types.packages import PackageManagementMixin from napalm_device_types.phone import PhoneDriver from napalm_device_types.ping_sweep import PingSweepMixin, driver_supports_ping +from napalm_device_types.provisioning import VMProvisionIncomplete from napalm_device_types.residential_gateway import ResidentialGatewayDriver from napalm_device_types.roles import primary_role_of, role_keys_of, roles_of from napalm_device_types.service_clusters import ( @@ -353,6 +354,7 @@ __all__ = [ "VIRTUAL_IPS_COMMAND", "VirtualIpsMixin", "VmStopRequestMixin", + "VMProvisionIncomplete", "SERVICE_CLUSTERS_COMMAND", "ServiceClustersMixin", "parse_service_clusters", diff --git a/napalm_device_types/hypervisor.py b/napalm_device_types/hypervisor.py index 3618c22..d6e3f17 100644 --- a/napalm_device_types/hypervisor.py +++ b/napalm_device_types/hypervisor.py @@ -532,6 +532,9 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri Raises: RuntimeError - if provisioning fails (download failure, checksum mismatch, storage unavailable, invalid config, timeout, etc.) + VMProvisionIncomplete - a RuntimeError for a failure after the VM + was created: it carries that VM's ``vmid`` and ``node``, so the + caller can ``destroy_vm`` it, and the failure as its cause. """ ... diff --git a/napalm_device_types/provisioning.py b/napalm_device_types/provisioning.py index 8879934..b479614 100644 --- a/napalm_device_types/provisioning.py +++ b/napalm_device_types/provisioning.py @@ -3,8 +3,9 @@ What provisioning a VM from a cloud image needs to know about the guest. The same for every hypervisor: which agent a guest runs so a QEMU-based hypervisor can read its IP, the network-config cloud-init and FreeBSD's -nuageinit both read, and how a packed cloud image is unpacked. How a -hypervisor attaches, boots and talks to the VM stays in its driver. +nuageinit both read, how a packed cloud image is unpacked, and how a failure +names the VM it left behind. How a hypervisor attaches, boots and talks to +the VM stays in its driver. """ from __future__ import annotations @@ -37,6 +38,30 @@ _DECOMPRESSORS = { } +class VMProvisionIncomplete(RuntimeError): + """``create_vm_from_cloud_init`` failed after the VM was created. + + The VM is still on the hypervisor, half built: ``vmid`` and ``node`` name it + as ``VMProvisionResultDict`` would have, so the caller can remove it with + ``destroy_vm``. The failure itself is the ``__cause__`` (``raise ... from``), + and the message is its own. A failure before the VM exists raises as before. + """ + + def __init__(self, message: str, *, vmid: str, node: str) -> None: + super().__init__(message) + self.vmid = vmid + self.node = node + + def __reduce__(self) -> tuple[Any, ...]: + # The keyword-only arguments are not in ``args``, which is all that + # pickle passes back by default. + return (_vm_provision_incomplete, (str(self), self.vmid, self.node)) + + +def _vm_provision_incomplete(message: str, vmid: str, node: str) -> VMProvisionIncomplete: + return VMProvisionIncomplete(message, vmid=vmid, node=node) + + def network_config(nics: list[tuple[str, bool]]) -> dict[str, Any] | None: """Network-config v2: DHCP on every ``(mac, dhcp)`` NIC that asks for it. diff --git a/tests/test_vm_provision_incomplete.py b/tests/test_vm_provision_incomplete.py new file mode 100644 index 0000000..ddaef8d --- /dev/null +++ b/tests/test_vm_provision_incomplete.py @@ -0,0 +1,53 @@ +"""A provisioning that failed after the hypervisor gave the VM its id says +which VM it left behind, so the caller can remove it (NAPALM/napalm-proxmox#28).""" + +from __future__ import annotations + +import pickle + +import pytest + +from napalm_device_types import VMProvisionIncomplete +from napalm_device_types.provisioning import VMProvisionIncomplete as from_module + + +def _raise_from(cause: Exception) -> VMProvisionIncomplete: + try: + try: + raise cause + except Exception as exc: + raise VMProvisionIncomplete(str(exc), vmid="101", node="pve1") from exc + except VMProvisionIncomplete as caught: + return caught + + +def test_it_is_exported_from_the_package_root(): + assert VMProvisionIncomplete is from_module + + +def test_it_names_the_vm_left_behind(): + caught = _raise_from(RuntimeError("disk import failed")) + assert (caught.vmid, caught.node) == ("101", "pve1") + + +def test_it_keeps_the_failure_and_its_words(): + cause = RuntimeError("disk import failed") + caught = _raise_from(cause) + assert caught.__cause__ is cause + assert str(caught) == "disk import failed" + + +def test_a_caller_catching_runtime_error_still_catches_it(): + # The contract has create_vm_from_cloud_init raise RuntimeError on failure. + with pytest.raises(RuntimeError): + raise VMProvisionIncomplete("start failed", vmid="7", node="n") + + +def test_vmid_and_node_are_keyword_only(): + with pytest.raises(TypeError): + VMProvisionIncomplete("failed", "101", "pve1") # type: ignore[misc] + + +def test_it_survives_pickling_as_a_task_result_would(): + caught = pickle.loads(pickle.dumps(VMProvisionIncomplete("failed", vmid="101", node="pve1"))) + assert (str(caught), caught.vmid, caught.node) == ("failed", "101", "pve1") From 73771aba006fcdf45c87f0302b0fed62d68011d8 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Sun, 1 Nov 2026 23:02:46 +0100 Subject: [PATCH 2/2] docs: a tighter create_vm_from_cloud_init docstring The VMProvisionIncomplete entry pushed the method past its recorded length in the quality baseline. The image-cache note joins the paragraph it repeated, and the Raises entry takes two lines; nothing it says is dropped. --- napalm_device_types/hypervisor.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/napalm_device_types/hypervisor.py b/napalm_device_types/hypervisor.py index a9df8ea..8784884 100644 --- a/napalm_device_types/hypervisor.py +++ b/napalm_device_types/hypervisor.py @@ -473,13 +473,11 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri """ Create a new virtual machine from a cloud image via Cloud-Init. - Downloads the cloud image (qcow2/raw) directly on the hypervisor if not - already cached there, creates a new VM shell, imports the image as its - root disk, configures virtual network interfaces, and injects Cloud-Init - configuration via a storage snippet or similar mechanism. The resulting - VM is left in a running state. - - Implementations cache downloaded images on the hypervisor by URL/filename. + Downloads the cloud image (qcow2/raw) directly on the hypervisor unless it is + cached there already (implementations cache by URL/filename), creates a new VM + shell, imports the image as its root disk, configures virtual network interfaces, + and injects Cloud-Init configuration via a storage snippet or similar mechanism. + The resulting VM is left in a running state. Args: name (string) - new VM display name @@ -533,9 +531,8 @@ class HypervisorDriver(PackageManagementMixin, HealthMetricsMixin, DeviceTypeDri Raises: RuntimeError - if provisioning fails (download failure, checksum mismatch, storage unavailable, invalid config, timeout, etc.) - VMProvisionIncomplete - a RuntimeError for a failure after the VM - was created: it carries that VM's ``vmid`` and ``node``, so the - caller can ``destroy_vm`` it, and the failure as its cause. + VMProvisionIncomplete - a RuntimeError for a failure after the VM was created, + with that VM's ``vmid`` and ``node`` for ``destroy_vm`` and the failure as cause. """ ...