From 72c30dd4c2e2f0909e096a5685a61c5d76ad5820 Mon Sep 17 00:00:00 2001 From: Christian Manivong Date: Fri, 30 Oct 2026 09:28:07 +0100 Subject: [PATCH] feat: get_network_targets names each bridge's uplinks (NetOrk/netork#1325) netOrk's VM dialog follows a bridge's physical NICs to the switch port behind it, to warn when a VM without a VLAN tag would land nowhere. The driver knows those NICs from the node's network config. uplinks is read from bridge_ports (Linux bridge) or ovs_ports (OVS bridge), one group per bridge port: a bond (slaves / ovs_bonds) as its NICs together, a NIC alone. Internal ports (OVSIntPort) and VLAN subinterfaces leave out, as they never carry the bridge's untagged traffic to the switch. A port missing from the config or of a kind the driver cannot place leaves the key out rather than guessing. --- CHANGELOG.md | 6 ++ napalm_proxmox/uplinks.py | 67 +++++++++++++ napalm_proxmox/vm_provision_mixin.py | 22 +++-- tests/test_network_target_uplinks.py | 135 +++++++++++++++++++++++++++ 4 files changed, 222 insertions(+), 8 deletions(-) create mode 100644 napalm_proxmox/uplinks.py create mode 100644 tests/test_network_target_uplinks.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 23f7371..3901e87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 on 3.12, so 3.10 and 3.11 are no longer tested (NAPALM/driver-standard#6). ### Added +- `get_network_targets()` names each bridge's physical NICs in `uplinks`, read + from `bridge_ports`/`ovs_ports`, one group per bridge port: a bond's slaves + together, a NIC alone, without internal ports (`OVSIntPort`) and VLAN + subinterfaces. Left out when a port is missing from the + node's network config or of a kind it cannot place (NetOrk/netork#1325). Needs + the `uplinks` field of napalm-device-types' `NetworkTargetDict`. - `shutdown_host()`: the node shuts itself down through the API (`POST /nodes/{node}/status command=shutdown`), and `begin_stop_vm(name)`: a guest's clean shutdown, returning once Proxmox took it instead of waiting for diff --git a/napalm_proxmox/uplinks.py b/napalm_proxmox/uplinks.py new file mode 100644 index 0000000..4d3695f --- /dev/null +++ b/napalm_proxmox/uplinks.py @@ -0,0 +1,67 @@ +"""The physical NICs a bridge leaves the node through (``NetworkTargetDict.uplinks``). + +One group per way out of the bridge: a bond's slaves together, a single NIC alone. + +Read from the node's network config (``GET /nodes/{node}/network``): a Linux +bridge names its ports in ``bridge_ports``, an OVS bridge in ``ovs_ports``. A +Linux bond lists its NICs in ``slaves``, an OVS bond in ``ovs_bonds``. Internal +ports (``OVSIntPort``) and VLAN subinterfaces are no uplinks: the first never +leaves the node, the second leaves it tagged, so the switch port's untagged +VLAN is not the bridge's. +""" + +from __future__ import annotations + +from typing import Any + +#: Types of a port that is a physical NIC of its own. +_NIC_TYPES = frozenset({"eth", "OVSPort"}) +#: Types of a port that leaves the node through its member NICs. +_BOND_TYPES = frozenset({"bond", "OVSBond"}) +#: Types of a port that is no uplink. +_NOT_UPLINK_TYPES = frozenset({"vlan", "OVSIntPort"}) + + +class _Unknown(Exception): + """A port whose kind the network config does not tell.""" + + +def _words(value: Any) -> list[str]: + return [w for w in str(value or "").split() if w != "none"] + + +def _nics_of(port: str, by_name: dict[str, dict[str, Any]], in_bond: bool = False) -> list[str]: + info = by_name.get(port) + if info is None: + raise _Unknown(port) + kind = info.get("type", "") + if kind in _BOND_TYPES: + return _bond_nics(info, by_name) + # An OVS bond's slave can come without a type of its own. + if kind in _NIC_TYPES or (in_bond and not kind): + # A VLAN subinterface added to an OVS bridge is an OVSPort too. + return [] if "." in port else [port] + if kind in _NOT_UPLINK_TYPES: + return [] + raise _Unknown(port) + + +def _bond_nics(bond: dict[str, Any], by_name: dict[str, dict[str, Any]]) -> list[str]: + members = _words(bond.get("slaves") or bond.get("ovs_bonds")) + return [nic for member in members for nic in _nics_of(member, by_name, in_bond=True)] + + +def bridge_uplinks(bridge: dict[str, Any], network: list[dict[str, Any]]) -> list[list[str]] | None: + """The physical NICs *bridge* leaves the node through, per port, or None when unknown. + + An empty list is a bridge without uplink. None means a port is missing from + the network config or of a kind this cannot place — a guess would send the + caller to the wrong switch port. + """ + by_name = {iface["iface"]: iface for iface in network if iface.get("iface")} + ports = _words(bridge.get("ovs_ports") or bridge.get("bridge_ports")) + try: + groups = [_nics_of(port, by_name) for port in ports] + except _Unknown: + return None + return [group for group in groups if group] diff --git a/napalm_proxmox/vm_provision_mixin.py b/napalm_proxmox/vm_provision_mixin.py index 6f339cc..e418e27 100644 --- a/napalm_proxmox/vm_provision_mixin.py +++ b/napalm_proxmox/vm_provision_mixin.py @@ -25,6 +25,8 @@ from napalm_device_types.provisioning import ( split_compression, ) +from napalm_proxmox.uplinks import bridge_uplinks + if TYPE_CHECKING: # Type-only: VMCpuTypeDict is newer than the napalm_device_types floor in # pyproject.toml, and nothing here needs it at runtime. @@ -949,19 +951,23 @@ class ProxmoxVMProvisionMixin: those are never valid ``NICConfigDict.bridge`` values on Proxmox. """ targets: list[NetworkTargetDict] = [] + network = self._get_node_network() - for iface in self._get_node_network(): + for iface in network: iface_type = iface.get("type") name = iface.get("iface", "") - if not name: + if not name or iface_type not in ("bridge", "OVSBridge"): continue - if iface_type == "bridge": - vlan_aware = bool(int(iface.get("bridge_vlan_aware", 0) or 0)) - targets.append({"name": name, "kind": "bridge", "vlan_aware": vlan_aware}) - elif iface_type == "OVSBridge": - # OVS bridges tag per-port regardless of a dedicated "VLAN aware" setting. - targets.append({"name": name, "kind": "bridge", "vlan_aware": True}) + # OVS bridges tag per-port regardless of a dedicated "VLAN aware" setting. + vlan_aware = iface_type == "OVSBridge" or bool( + int(iface.get("bridge_vlan_aware", 0) or 0) + ) + target: NetworkTargetDict = {"name": name, "kind": "bridge", "vlan_aware": vlan_aware} + uplinks = bridge_uplinks(iface, network) + if uplinks is not None: + target["uplinks"] = uplinks + targets.append(target) for vnet in self._get_sdn_vnets(): name = vnet.get("vnet", "") diff --git a/tests/test_network_target_uplinks.py b/tests/test_network_target_uplinks.py new file mode 100644 index 0000000..3fd2613 --- /dev/null +++ b/tests/test_network_target_uplinks.py @@ -0,0 +1,135 @@ +"""get_network_targets names the physical NICs each bridge leaves the node through. + +NetOrk follows their LLDP neighbours to the switch port behind the bridge, to +tell whether a VM without a VLAN tag lands in a network at all +(NetOrk/netork#1325). They come in groups, one per way out of the bridge: a +bond's slaves together, a single NIC alone. Internal ports, VLAN subinterfaces +and virtual ports are no uplinks. When a port cannot be told +apart, ``uplinks`` is left out rather than guessed. +""" + +from __future__ import annotations + +from unittest.mock import MagicMock + +from napalm_proxmox.vm_provision_mixin import ProxmoxVMProvisionMixin + + +def _targets(network: list[dict]) -> dict[str, dict]: + mixin = ProxmoxVMProvisionMixin() + mixin._get_node_network = MagicMock(return_value=network) + mixin._get_sdn_vnets = MagicMock(return_value=[]) + return {t["name"]: t for t in mixin.get_network_targets()} + + +def test_linux_bridge_on_a_nic(): + targets = _targets( + [ + {"iface": "eno1", "type": "eth"}, + {"iface": "vmbr0", "type": "bridge", "bridge_ports": "eno1", "bridge_vlan_aware": 1}, + ] + ) + + assert targets["vmbr0"]["uplinks"] == [["eno1"]] + + +def test_linux_bridge_on_a_bond_lists_the_slaves(): + targets = _targets( + [ + {"iface": "eno1", "type": "eth"}, + {"iface": "eno2", "type": "eth"}, + {"iface": "bond0", "type": "bond", "slaves": "eno1 eno2"}, + {"iface": "vmbr0", "type": "bridge", "bridge_ports": "bond0"}, + ] + ) + + assert targets["vmbr0"]["uplinks"] == [["eno1", "eno2"]] + + +def test_linux_bridge_on_a_vlan_subinterface_has_no_uplink(): + """A bridge on ``eno1.40`` leaves tagged; the port's untagged VLAN is not its.""" + targets = _targets( + [ + {"iface": "eno1", "type": "eth"}, + {"iface": "eno1.40", "type": "vlan", "vlan-raw-device": "eno1"}, + {"iface": "vmbr40", "type": "bridge", "bridge_ports": "eno1.40"}, + ] + ) + + assert targets["vmbr40"]["uplinks"] == [] + + +def test_host_only_bridge_has_no_uplink(): + targets = _targets([{"iface": "vmbr9", "type": "bridge"}]) + + assert targets["vmbr9"]["uplinks"] == [] + + +def test_ovs_bridge_with_bond_and_internal_port(): + """pve-dual's shape: vmbr0 carries an LACP bond and the management OVSIntPort.""" + targets = _targets( + [ + {"iface": "nic0", "type": "OVSPort"}, + {"iface": "nic1", "type": "OVSPort"}, + { + "iface": "bond0", + "type": "OVSBond", + "ovs_bonds": "nic0 nic1", + "ovs_bridge": "vmbr0", + }, + {"iface": "mgmt_vlan", "type": "OVSIntPort", "ovs_bridge": "vmbr0", "ovs_tag": 8}, + {"iface": "vmbr0", "type": "OVSBridge", "ovs_ports": "bond0 mgmt_vlan"}, + ] + ) + + assert targets["vmbr0"]["uplinks"] == [["nic0", "nic1"]] + + +def test_ovs_bridge_on_a_single_port(): + targets = _targets( + [ + {"iface": "eno1", "type": "OVSPort", "ovs_bridge": "vmbr1"}, + {"iface": "vmbr1", "type": "OVSBridge", "ovs_ports": "eno1"}, + ] + ) + + assert targets["vmbr1"]["uplinks"] == [["eno1"]] + + +def test_ovs_bridge_on_two_single_ports_has_two_groups(): + targets = _targets( + [ + {"iface": "eno1", "type": "OVSPort", "ovs_bridge": "vmbr1"}, + {"iface": "eno2", "type": "OVSPort", "ovs_bridge": "vmbr1"}, + {"iface": "vmbr1", "type": "OVSBridge", "ovs_ports": "eno1 eno2"}, + ] + ) + + assert targets["vmbr1"]["uplinks"] == [["eno1"], ["eno2"]] + + +def test_port_missing_from_the_network_config_leaves_uplinks_out(): + targets = _targets([{"iface": "vmbr0", "type": "bridge", "bridge_ports": "enp9s0"}]) + + assert "uplinks" not in targets["vmbr0"] + + +def test_port_of_an_unknown_kind_leaves_uplinks_out(): + targets = _targets( + [ + {"iface": "wg0", "type": "unknown"}, + {"iface": "vmbr0", "type": "bridge", "bridge_ports": "wg0"}, + ] + ) + + assert "uplinks" not in targets["vmbr0"] + + +def test_vnet_has_no_uplinks(): + mixin = ProxmoxVMProvisionMixin() + mixin._get_node_network = MagicMock(return_value=[]) + mixin._get_sdn_vnets = MagicMock(return_value=[{"vnet": "vnet0", "zone": "z", "tag": 10}]) + + (target,) = mixin.get_network_targets() + + assert "uplinks" not in target -- 2.54.0