fix: rename undersync mechanism and load it and add documentation

components/neutron/values.yaml

@@ -45,7 +45,7 @@ conf:
         extension_drivers: 'port_security'
         # set the default ml2 backend to our plugin, neutron_understack
         # we'll need to use the ovn ML2 plugin to hook the routers to our network
-        mechanism_drivers: "understack,ovn"
+        mechanism_drivers: "understack,undersync,ovn"
         tenant_network_types: "vxlan"
         type_drivers: "vlan,vxlan"
       ml2_type_vxlan:

docs/design-guide/neutron-networking.md

@@ -10,7 +10,7 @@ To enable this we are using the following plugins/features of Neutron:
 - [OVN driver][ovn-driver] for general [OVN][ovn] support
 - [networking-baremetal][networking-baremetal] to have Neutron aware of the physical
   networks of Ironic baremetal ports.
-- our custom mechanism driver called `understack`
+- our custom mechanism drivers `understack` and `undersync` (both must be loaded)
 - [ovn-router][ovn-admin] as the L3 router plugin
 - [trunk plugin][neutron-trunk] service plugin
 - [network segment range][neutron-network-segment-range] service plugin
@@ -376,7 +376,23 @@ The names and the IDs all match, along with the VLAN ID of the segment where the
 
 ## ML2 Mechanism Operations
 
-Our ML2 mechanism is responsible for the following:
+Our ML2 mechanism is split across two drivers that must both be present in
+`mechanism_drivers`:
+
+- `understack` — the primary driver responsible for allocating dynamic VLAN
+  segments on VXLAN networks (`bind_port()`), releasing them when ports are
+  removed (`delete_port_postcommit()`), and triggering switch configuration
+  updates (`update_port_postcommit()`)
+- `undersync` — handles level-1 binding by calling `set_binding()`
+  on the VLAN segment that `understack` allocated via `continue_binding()`;
+  without it port binding fails at level 1
+
+The binding flow is: `understack` handles the VXLAN segment at level 0 and
+calls `continue_binding()` with a dynamically allocated VLAN segment, then
+`undersync` finalises the binding at level 1 by calling
+`set_binding()` on that VLAN segment.
+
+Together they are responsible for:
 
 - creating dynamic VLAN segments on VXLAN networks via port binding operations via `bind_port()`
 - deleting dynamic VLAN segments on VXLAN networks when ports are removed via `delete_port_postcommit()`

docs/operator-guide/openstack-neutron.md

@@ -17,7 +17,7 @@ conf:
         # replacing so you'll need to pay attention
         # to any changes your environment might have
         # from the default
-        mechanism_drivers: "logger,understack,ovn"
+        mechanism_drivers: "logger,understack,undersync,ovn"
   logging:
     loggers:
       # for 'keys' we are attempt to append 'mechanism_logger'

python/neutron-understack/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
 
 [project.entry-points."neutron.ml2.mechanism_drivers"]
 understack = "neutron_understack.neutron_understack_mech:UnderstackDriver"
-understack_undersync = "neutron_understack.undersync_mech:UnderstackUndersyncDriver"
+undersync = "neutron_understack.undersync_mech:UnderstackUndersyncDriver"
 
 [project.entry-points."neutron.ml2.type_drivers"]
 understack_vxlan = "neutron_understack.type_understack_vxlan:UnderstackVxlanTypeDriver"