fix: populate per-network HCG for vxlan gateway routers after 2026.1 upgrade

After upgrading to neutron 28 (2026.1), attaching a subnet to a router whose
external gateway is on a vxlan-type network leaves the per-network unified
HA_Chassis_Group (neutron-<network_id>) empty. External (baremetal) ports with
OVN LSP type=external on that network reference this HCG; with it empty, no
chassis owns them and ARP/routing breaks for all baremetal nodes on the network.

Root cause: for a vxlan-type external gateway neutron pins the Logical_Router to
one chassis via options:chassis and creates a per-router HCG
(neutron-<router_id>) carrying that chassis, but never sets ha_chassis_group on
the gateway LRP. neutron's link_network_ha_chassis_group (called on internal LRP
creation) bails at its `if not gw_lrps[0].ha_chassis_group: return` guard, so
it never copies the chassis into neutron-<network_id>.

Fix: subscribe to ROUTER_INTERFACE/AFTER_CREATE at PRIORITY_DEFAULT+1000 (after
OVN's handler has created the LRP) with a new handler
link_vxlan_network_ha_chassis_group. The handler:

1. Detects a vxlan-type gateway by checking that the per-router HCG
    (neutron-<router_id>) exists and has non-empty ha_chassis; VLAN/FLAT gateways
    have no router HCG and continue to be handled by neutron unchanged.
2. Calls ovn_utils.sync_ha_chassis_group_network_unified to populate the
    per-network HCG (neutron-<network_id>) from the router HCG chassis — this is
    what fixes external/baremetal ports that already reference it.
3. Anchors the internal router-interface LRP (lrp-<port_id>) to the same unified
    network HCG so the router port is also correctly owned.

Both operations run in a single OVN NB transaction. The create_port_postcommit
hook is unaffected — the internal LRP does not exist at that point (it is
created later, on the same AFTER_CREATE event OVN processes first).

Author: skrobul

python/neutron-understack/neutron_understack/neutron_understack_mech.py

@@ -6,6 +6,7 @@
 from neutron_lib import constants as p_const
 from neutron_lib.api.definitions import portbindings
 from neutron_lib.callbacks import events
+from neutron_lib.callbacks import priority_group
 from neutron_lib.callbacks import registry
 from neutron_lib.callbacks import resources
 from neutron_lib.plugins.ml2 import api
@@ -99,6 +100,15 @@ def subscribe(self):
             events.PRECOMMIT_DELETE,
             cancellable=True,
         )
+        # Runs after neutron's OVN handler (PRIORITY_DEFAULT) has created the
+        # internal LRP, so the unified network HCG and the LRP both exist.
+        # Smaller priority is called earlier, so use a larger value to run later.
+        registry.subscribe(
+            routers.link_vxlan_network_ha_chassis_group,
+            resources.ROUTER_INTERFACE,
+            events.AFTER_CREATE,
+            priority=priority_group.PRIORITY_DEFAULT + 1000,
+        )
 
     def create_network_precommit(self, context):
         pass

python/neutron-understack/neutron_understack/routers.py

@@ -44,6 +44,7 @@ def create_port_postcommit(context: PortContext) -> None:
     In situation 2, we don't have to do anything.
     """
     network_id = context.current["network_id"]
+
     if not is_only_router_port_on_network(
         network_id=network_id, transaction_context=context.plugin_context
     ):
@@ -185,6 +186,103 @@ def create_uplink_port(segment: NetworkSegment, network_id: str, txn=None) -> No
     ovn_client()._transaction([cmd], txn=txn)
 
 
+def link_vxlan_network_ha_chassis_group(_resource, _event, _trigger, payload) -> None:
+    """Populate the unified network HCG (and anchor the internal LRP) for vxlan.
+
+    Workaround for a neutron bug exposed in 2026.1. For a router with a vxlan-type
+    external gateway, neutron pins the Logical_Router to a single
+    chassis via ``options:chassis`` and creates a per-router HA_Chassis_Group
+    (neutron-<router_id>) carrying that chassis, but it never sets
+    ha_chassis_group on the gateway LRP. neutron's link_network_ha_chassis_group
+    (fired when the internal LRP is created) bails out at its
+    ``if not gw_lrps[0].ha_chassis_group`` check, so it never copies the chassis
+    into the per-network unified HCG (neutron-<network_id>). External/baremetal
+    ports on that network reference the empty network HCG, so no chassis owns
+    them and routing/ARP breaks.
+
+    We do what link_network_ha_chassis_group would have done, but source the
+    chassis from the router HCG instead of the (empty) gateway LRP: populate the
+    unified network HCG with sync_ha_chassis_group_network_unified, then anchor
+    the internal router-interface LRP to that same HCG. External ports already
+    reference the unified network HCG, so populating it fixes them.
+
+    Subscribed to ROUTER_INTERFACE/AFTER_CREATE at a priority that runs after
+    neutron's OVN handler, so the LRP (lrp-<port_id>) already exists by now.
+    """
+    router_id = payload.states[0].id
+    port = payload.metadata["port"]
+    port_id = port["id"]
+    network_id = port["network_id"]
+
+    try:
+        client = ovn_client()
+        if not client:
+            return
+        nb_idl = client._nb_idl
+
+        # Vxlan-gateway signal: the per-router HCG exists with chassis.
+        # VLAN/FLAT gateways have no router HCG and are handled by neutron.
+        router_hcg = nb_idl.lookup(
+            "HA_Chassis_Group", ovn_utils.ovn_name(router_id), default=None
+        )
+        if not router_hcg or not router_hcg.ha_chassis:
+            LOG.debug(
+                "No HA_Chassis_Group with chassis found for router %(router)s",
+                {"router": router_id},
+            )
+            return
+
+        chassis_prio = {hc.chassis_name: hc.priority for hc in router_hcg.ha_chassis}
+        lrp_name = ovn_utils.ovn_lrouter_port_name(port_id)
+
+        LOG.info(
+            "Linking unified HCG for network %(net)s (router %(router)s) with "
+            "chassis %(chassis)s and anchoring internal LRP %(lrp)s",
+            {
+                "net": network_id,
+                "router": router_id,
+                "chassis": list(chassis_prio),
+                "lrp": lrp_name,
+            },
+        )
+
+        admin_context = n_context.get_admin_context()
+        with nb_idl.transaction(check_error=True) as txn:
+            # Populate the per-network unified HCG with the gateway chassis.
+            # This is what fixes the external (baremetal) ports, which already
+            # reference neutron-<network_id>.
+            hcg, _ = ovn_utils.sync_ha_chassis_group_network_unified(
+                admin_context,
+                nb_idl,
+                client._sb_idl,
+                network_id,
+                router_id,
+                chassis_prio,
+                txn,
+            )
+
+            # Anchor the internal router-interface LRP to the same unified HCG.
+            if nb_idl.lookup("Logical_Router_Port", lrp_name, default=None):
+                txn.add(
+                    nb_idl.db_set(
+                        "Logical_Router_Port",
+                        lrp_name,
+                        ("ha_chassis_group", hcg),
+                    )
+                )
+    except Exception as err:
+        LOG.error(
+            "Failed linking HA_Chassis_Group for network %(net)s port "
+            "%(port)s (router %(router)s): %(error)s",
+            {
+                "net": network_id,
+                "port": port_id,
+                "router": router_id,
+                "error": err,
+            },
+        )
+
+
 def delete_uplink_port(segment: NetworkSegment, network_id: str) -> None:
     """Remove a localnet uplink port from a network node."""
     port_to_del = f"uplink-{segment['id']}"

python/neutron-understack/neutron_understack/tests/test_routers.py

@@ -6,6 +6,7 @@
 from neutron_understack.routers import fetch_or_create_router_segment
 from neutron_understack.routers import handle_router_interface_removal
 from neutron_understack.routers import handle_subport_removal
+from neutron_understack.routers import link_vxlan_network_ha_chassis_group
 
 
 class TestFetchOrCreateRouterSegment:
@@ -202,3 +203,94 @@ def test_no_router_on_network(self, mocker, port_context):
         create_uplink_port.assert_called_once_with(
             fake_segment, port_context.current["network_id"]
         )
+
+
+class TestLinkVxlanNetworkHaChassisGroup:
+    @staticmethod
+    def _payload(mocker, router_id="router-1", port_id="port-1", network_id="net-1"):
+        router = mocker.Mock()
+        router.id = router_id
+        return mocker.Mock(
+            states=[router],
+            metadata={"port": {"id": port_id, "network_id": network_id}},
+        )
+
+    @staticmethod
+    def _client(mocker, router_hcg, lrp):
+        nb_idl = mocker.MagicMock()
+
+        def lookup(table, _name, default=None):
+            if table == "HA_Chassis_Group":
+                return router_hcg
+            if table == "Logical_Router_Port":
+                return lrp
+            return default
+
+        nb_idl.lookup.side_effect = lookup
+        client = mocker.Mock(_nb_idl=nb_idl)
+        return client, nb_idl
+
+    def _patch_sync(self, mocker, hcg="net-hcg-uuid"):
+        mocker.patch(
+            "neutron_understack.routers.n_context.get_admin_context",
+            return_value="ctx",
+        )
+        return mocker.patch(
+            "neutron_understack.routers.ovn_utils.sync_ha_chassis_group_network_unified",
+            return_value=(hcg, "chassis-1"),
+        )
+
+    def test_populates_network_hcg_and_anchors_lrp(self, mocker):
+        hc = mocker.Mock(chassis_name="chassis-1", priority=10)
+        router_hcg = mocker.Mock(ha_chassis=[hc], name="neutron-router-1")
+        lrp = mocker.Mock(ha_chassis_group=[])
+        client, nb_idl = self._client(mocker, router_hcg, lrp)
+        sync = self._patch_sync(mocker)
+        mocker.patch("neutron_understack.routers.ovn_client", return_value=client)
+
+        link_vxlan_network_ha_chassis_group(None, None, None, self._payload(mocker))
+
+        # Network HCG is populated from the router's chassis.
+        assert sync.call_args.args[3] == "net-1"  # network_id
+        assert sync.call_args.args[4] == "router-1"  # router_id
+        assert sync.call_args.args[5] == {"chassis-1": 10}  # chassis_prio
+        # Internal LRP is anchored to the unified network HCG.
+        nb_idl.db_set.assert_called_once_with(
+            "Logical_Router_Port",
+            "lrp-port-1",
+            ("ha_chassis_group", "net-hcg-uuid"),
+        )
+
+    def test_no_router_hcg(self, mocker):
+        client, nb_idl = self._client(mocker, router_hcg=None, lrp=None)
+        sync = self._patch_sync(mocker)
+        mocker.patch("neutron_understack.routers.ovn_client", return_value=client)
+
+        link_vxlan_network_ha_chassis_group(None, None, None, self._payload(mocker))
+
+        sync.assert_not_called()
+        nb_idl.db_set.assert_not_called()
+
+    def test_router_hcg_without_chassis(self, mocker):
+        router_hcg = mocker.Mock(ha_chassis=[])
+        client, nb_idl = self._client(mocker, router_hcg, lrp=None)
+        sync = self._patch_sync(mocker)
+        mocker.patch("neutron_understack.routers.ovn_client", return_value=client)
+
+        link_vxlan_network_ha_chassis_group(None, None, None, self._payload(mocker))
+
+        sync.assert_not_called()
+        nb_idl.db_set.assert_not_called()
+
+    def test_lrp_missing_still_populates_network_hcg(self, mocker):
+        hc = mocker.Mock(chassis_name="chassis-1", priority=10)
+        router_hcg = mocker.Mock(ha_chassis=[hc], name="neutron-router-1")
+        client, nb_idl = self._client(mocker, router_hcg, lrp=None)
+        sync = self._patch_sync(mocker)
+        mocker.patch("neutron_understack.routers.ovn_client", return_value=client)
+
+        link_vxlan_network_ha_chassis_group(None, None, None, self._payload(mocker))
+
+        # The network HCG is still populated even if the LRP is not found yet.
+        sync.assert_called_once()
+        nb_idl.db_set.assert_not_called()