diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 34f9b57..25a750f 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -11,7 +11,5 @@ jobs: uses: NAPALM/driver-standard/.gitea/workflows/driver.yml@main with: standard-ref: main - # Until napalm-device-types 4.22.0 (AptProxyMixin, #53) is on PyPI. - pre-install: "git+https://git.netork.io/NAPALM/napalm-device-types.git" secrets: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ca7a7f..31f8a18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Changed +- The floor on napalm-device-types is 4.23.0, the first release with what this driver uses. - Python 3.12 is the floor (`requires-python = ">=3.12"`): netOrk runs every driver on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6). @@ -106,6 +107,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - A failed cloud-image download in `create_vm_from_cloud_init()` says why (wget's own message, such as "No space left on device") and removes its partial `.tmp` file instead of leaving it to fill the node's disk (#3). +- A `create_vm_from_cloud_init()` that fails once the VM shell exists (disk import, + storage, NIC or snippet configuration, start) raises `VMProvisionIncomplete`, a + `RuntimeError` with the VMID and node of the VM it left behind and the failure as + its cause, so the caller can remove it with `destroy_vm()`. Failures there that + were a `ValueError` (no snippet storage, a NIC without a bridge) are its cause now. + Needs `VMProvisionIncomplete` from napalm-device-types (#28). ## [0.8.0] - 2026-10-23 diff --git a/napalm_proxmox/vm_provision_mixin.py b/napalm_proxmox/vm_provision_mixin.py index 02d6194..87beb7c 100644 --- a/napalm_proxmox/vm_provision_mixin.py +++ b/napalm_proxmox/vm_provision_mixin.py @@ -21,6 +21,7 @@ from napalm_device_types.models import ( from napalm_device_types.provisioning import ( QEMU_GUEST_AGENTS, GuestAgents, + VMProvisionIncomplete, network_config, split_compression, ) @@ -130,6 +131,29 @@ def _import_volume_name(image_url: str) -> str | None: return f"netork-{_url_key(image_url)}-{safe_stem}.{extension}" +def _nic_config_args(nics: list[dict[str, Any]]) -> dict[str, str]: + """``{"net": "virtio[=],bridge=[,tag=|,trunks=]"}`` per NIC.""" + config_args: dict[str, str] = {} + for i, nic in enumerate(nics): + bridge = nic.get("bridge") + if not bridge: + raise ValueError(f"NIC {i}: bridge is required") + + # Build base config: model[=mac] + bridge + mac = nic.get("mac") + net_config = f"virtio={mac},bridge={bridge}" if mac else f"virtio,bridge={bridge}" + + # Add VLAN configuration (access vs trunk) + if "trunk_vlan_tags" in nic and nic["trunk_vlan_tags"]: + vlan_list = ";".join(str(v) for v in nic["trunk_vlan_tags"]) + net_config += f",trunks={vlan_list}" + elif "vlan_tag" in nic and nic["vlan_tag"] is not None: + net_config += f",tag={nic['vlan_tag']}" + + config_args[f"net{i}"] = net_config + return config_args + + class ProxmoxVMProvisionMixin: """Mixin to add VM provisioning to ProxmoxDriver.""" @@ -618,12 +642,18 @@ class ProxmoxVMProvisionMixin: {"vmid": str, "name": str, "node": str} Raises: - RuntimeError: provisioning failure (download, import, config, timeout, etc.) - ValueError: invalid storage or configuration, or a cpu_type that is - unknown or that this node's CPU cannot run, or another node - (raised before anything is created) + VMProvisionIncomplete: any failure once the VM shell exists (download, + import, storage, NIC or snippet config, start, timeout, ...); a + RuntimeError that carries the half-built VM's vmid and node, with + the failure as its cause + RuntimeError: a failure taking the VMID or creating the shell (no VM + is left behind) + ValueError: a cpu_type that is unknown or that this node's CPU cannot + run, a guest_os it cannot provision, or another node (raised + before anything is created) """ self._check_placement(guest_os, node) + created: int | None = None # the VMID once the shell exists on the node try: _logger.info(f"Creating {guest_os} VM '{name}' from image {image_url}") cpu_model = self._resolve_cpu_type(cpu_type) @@ -647,6 +677,7 @@ class ProxmoxVMProvisionMixin: # queries (below) would have nothing to talk to. **_GUEST_VM_SETTINGS[guest_os], ) + created = vmid # Step 3: Download cloud image (cached) and import as root disk image_storage = storage or self._find_default_image_storage() @@ -656,29 +687,7 @@ class ProxmoxVMProvisionMixin: # Step 4: Configure network interfaces (CPU/memory already set at shell creation) _logger.info(f"Configuring {len(nics)} NIC(s) for VM {vmid}") - - config_args: dict[str, Any] = {} - - # Build NIC config strings generically - for i, nic in enumerate(nics): - bridge = nic.get("bridge") - if not bridge: - raise ValueError(f"NIC {i}: bridge is required") - - # Build base config: model[=mac] + bridge - mac = nic.get("mac") - net_config = f"virtio={mac},bridge={bridge}" if mac else f"virtio,bridge={bridge}" - - # Add VLAN configuration (access vs trunk) - if "trunk_vlan_tags" in nic and nic["trunk_vlan_tags"]: - vlan_list = ";".join(str(v) for v in nic["trunk_vlan_tags"]) - net_config += f",trunks={vlan_list}" - elif "vlan_tag" in nic and nic["vlan_tag"] is not None: - net_config += f",tag={nic['vlan_tag']}" - - config_args[f"net{i}"] = net_config - - self._node_api().qemu(vmid).config.post(**config_args) + self._node_api().qemu(vmid).config.post(**_nic_config_args(nics)) # Step 5: Verify snippet storage exists # (enabled is absent-not-falsy, and node-scoping matters — see @@ -786,7 +795,10 @@ class ProxmoxVMProvisionMixin: except Exception as e: _logger.exception(f"Failed to create VM '{name}': {e}") - raise + if created is None: + raise + # The VM stays behind half built; the caller removes it by its id. + raise VMProvisionIncomplete(str(e), vmid=str(created), node=self._node_name) from e def destroy_vm( self, diff --git a/pyproject.toml b/pyproject.toml index 8e8a529..07bbd3f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -21,7 +21,7 @@ classifiers = [ requires-python = ">=3.12" dependencies = [ "napalm>=5.0.0", - "napalm_device_types>=4.22.0", + "napalm_device_types>=4.23.0", "paramiko>=5.0.0", # CVE-2026-44405; imported directly for SSH fallback (driver.py) "proxmoxer>=2.0.0", "netaddr>=0.9.0", diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 6c9c8d9..97dd17c 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -21,7 +21,7 @@ "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin._get_vm_disk_and_boot": 16, "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vm_interfaces": 37, "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vms": 21, - "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.create_vm_from_cloud_init": 25, + "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.create_vm_from_cloud_init": 18, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.get_vm_status": 16 }, "function_lines": { @@ -38,7 +38,7 @@ "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vm_interfaces": 179, "napalm_proxmox/vm_mixin.py::ProxmoxVMMixin.get_vms": 114, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin._download_cloud_image": 56, - "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.create_vm_from_cloud_init": 232, + "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.create_vm_from_cloud_init": 220, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.destroy_vm": 56, "napalm_proxmox/vm_provision_mixin.py::ProxmoxVMProvisionMixin.get_vm_status": 92 }, diff --git a/tests/test_vm_half_built.py b/tests/test_vm_half_built.py new file mode 100644 index 0000000..0402fe9 --- /dev/null +++ b/tests/test_vm_half_built.py @@ -0,0 +1,125 @@ +"""A creation that fails once the VM exists names that VM (#28). + +Without its id the caller cannot remove the half-built VM, and it stays on the +node. A failure before the VM shell exists leaves nothing behind and raises +as it did. +""" + +from __future__ import annotations + +from unittest.mock import MagicMock, patch + +import pytest +from napalm_device_types.provisioning import VMProvisionIncomplete + +from napalm_proxmox.vm_provision_mixin import ProxmoxVMProvisionMixin + +_DEBIAN_URL = ( + "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2" +) + + +def _mixin() -> tuple: + """A mixin whose node answers like Proxmox and hands out VMID 101.""" + mixin = ProxmoxVMProvisionMixin() + mixin._node_name = "pve1" + api = MagicMock() + api.cluster.nextid.get.return_value = 101 + api.storage.return_value.get.return_value = {"path": "/var/lib/vz"} + node = MagicMock() + node.storage.get.return_value = [ + {"storage": "local-lvm", "type": "lvmthin", "content": "images,rootdir", "enabled": 1}, + {"storage": "local", "type": "dir", "content": "snippets,iso", "enabled": 1}, + ] + vm = MagicMock() + node.qemu.return_value = vm + vm.config.get.return_value = {"unused0": "local-lvm:vm-101-disk-0"} + vm.status.start.post.return_value = "UPID:pve1:start" + node.tasks.return_value.status.get.return_value = {"status": "stopped", "exitstatus": "OK"} + mixin._api = api + mixin._node_api = MagicMock(return_value=node) + mixin._download_cloud_image = MagicMock( + return_value="/var/lib/vz/template/netork-images/x.qcow2" + ) + mixin._run_node_command = MagicMock(return_value="") + return mixin, node, vm + + +def _create(mixin): + with patch("time.sleep"): + return mixin.create_vm_from_cloud_init( + name="half-built", + image_url=_DEBIAN_URL, + cpu=2, + memory=2048, + nics=[{"bridge": "vmbr0"}], + cloud_init_config={"hostname": "half-built"}, + ) + + +def test_a_failed_disk_import_names_the_vm_it_left_behind(): + mixin, _node, _vm = _mixin() + failure = RuntimeError("qm importdisk 101: storage 'local-lvm' is full") + mixin._download_cloud_image.side_effect = failure + + with pytest.raises(VMProvisionIncomplete) as caught: + _create(mixin) + + assert (caught.value.vmid, caught.value.node) == ("101", "pve1") + assert caught.value.__cause__ is failure + assert str(caught.value) == str(failure) + + +def test_a_failed_start_names_the_vm_it_left_behind(): + mixin, node, _vm = _mixin() + node.tasks.return_value.status.get.return_value = { + "status": "stopped", + "exitstatus": "start failed: QEMU exited with code 1", + } + + with pytest.raises(VMProvisionIncomplete, match="QEMU exited") as caught: + _create(mixin) + + assert (caught.value.vmid, caught.value.node) == ("101", "pve1") + + +def test_an_invalid_nic_after_the_shell_exists_names_the_vm_too(): + mixin, _node, _vm = _mixin() + + with pytest.raises(VMProvisionIncomplete, match="bridge is required") as caught: + with patch("time.sleep"): + mixin.create_vm_from_cloud_init( + name="half-built", + image_url=_DEBIAN_URL, + cpu=2, + memory=2048, + nics=[{"vlan_tag": 10}], + cloud_init_config={}, + ) + + assert isinstance(caught.value.__cause__, ValueError) + assert caught.value.vmid == "101" + + +def test_a_failure_creating_the_shell_leaves_no_vm_to_name(): + mixin, node, _vm = _mixin() + failure = RuntimeError("VM 101 already exists") + node.qemu.post.side_effect = failure + + with pytest.raises(RuntimeError) as caught: + _create(mixin) + + assert caught.value is failure + assert not isinstance(caught.value, VMProvisionIncomplete) + + +def test_a_failure_taking_the_vmid_leaves_no_vm_to_name(): + mixin, node, _vm = _mixin() + failure = RuntimeError("cluster not ready - no quorum?") + mixin._api.cluster.nextid.get.side_effect = failure + + with pytest.raises(RuntimeError) as caught: + _create(mixin) + + assert caught.value is failure + node.qemu.post.assert_not_called() diff --git a/tests/test_vm_provision_mixin.py b/tests/test_vm_provision_mixin.py index d6a0235..98df5e0 100644 --- a/tests/test_vm_provision_mixin.py +++ b/tests/test_vm_provision_mixin.py @@ -6,6 +6,7 @@ import base64 from unittest.mock import MagicMock, patch import pytest +from napalm_device_types.provisioning import VMProvisionIncomplete from napalm_proxmox.vm_provision_mixin import ProxmoxVMProvisionMixin @@ -220,7 +221,8 @@ def test_create_vm_from_cloud_init_dual_nic_trunk(): def test_create_vm_missing_snippet_storage(): - """create_vm_from_cloud_init raises ValueError if snippet storage unavailable.""" + """No snippet storage fails the creation; the VM shell exists by then, so the + ValueError arrives as the cause of VMProvisionIncomplete naming it (#28).""" mixin = ProxmoxVMProvisionMixin() mixin._node_name = "pve1" @@ -250,7 +252,7 @@ def test_create_vm_missing_snippet_storage(): mock_task.status.get.return_value = {"status": "stopped", "exitstatus": "OK"} mock_node.tasks.return_value = mock_task - with pytest.raises(ValueError, match="snippet"): + with pytest.raises(VMProvisionIncomplete, match="snippet") as caught: with patch("napalm_proxmox.vm_provision_mixin.time.sleep"): mixin.create_vm_from_cloud_init( name="test-vm", @@ -260,6 +262,8 @@ def test_create_vm_missing_snippet_storage(): nics=[{"bridge": "vmbr0"}], cloud_init_config={}, ) + assert isinstance(caught.value.__cause__, ValueError) + assert caught.value.vmid == "101" def test_create_vm_with_disk_resize():