ctauchen · Oct 28, 2026 · Oct 23, 2026
diff --git a/...rprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx b/...rprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx
@@ -265,6 +265,53 @@
    asNumber: <parent cluster's AS number>
   ```
 
+### Speed up BGP reconvergence for live migration
+
+When a workload (such as a KubeVirt VM) is live-migrated to a new node, its BGP session to the
+host must re-establish on the new node, during which the workload's advertised routes are
+unreachable. By default the workload is the active initiator of this session, so after a migration
+the workload — the side that just moved — must redial through BGP's reconnect back-off before
+routes recover.
+
+You can shorten this window with the [`connectionMode`](../../reference/resources/bgppeer.mdx)
+field, by making the **host node** the active initiator instead of the workload. Because the host
+node is stable across the migration, it re-establishes the session promptly, while the
+**workload** waits passively. Set it on both peerings:
+
+- In the parent cluster, set `connectionMode: Active` on the `localWorkloadSelector` peer:
+
+  ```yaml
+  apiVersion: projectcalico.org/v3
+  kind: BGPPeer
+  metadata:
+   name: peer-to-workloads
+  spec:
+   localWorkloadSelector: color == 'red'
+   asNumber: <workload cluster's AS number>
+   connectionMode: Active
+   filters:
+   - no-export
+   - accept-nested-ip-pools
+  ```
+
+- In the nested cluster, set `connectionMode: Passive` on the peer(s) to the parent cluster:
+
+  ```yaml
+  apiVersion: projectcalico.org/v3
+  kind: BGPPeer
+  metadata:
+   name: peer-to-parent-cluster
+  spec:
+   peerIP: 169.254.0.179
+   asNumber: <parent cluster's AS number>
+   connectionMode: Passive
+  ```
+
+We recommend configuring `connectionMode` as shown above for any deployment where workloads are
+live-migrated. Both ends must be set together — the parent peer `Active` and the nested peer
+`Passive`; setting only one end does not produce the intended behavior. If you leave the field
+unset, it defaults to `Auto`, which preserves the previous behavior.
+
 ### Configure more than one nested cluster
 
 You can configure more than one nested cluster by:

diff --git a/calico-enterprise_versioned_docs/version-3.23-2/reference/resources/bgppeer.mdx b/calico-enterprise_versioned_docs/version-3.23-2/reference/resources/bgppeer.mdx
@@ -63,6 +63,7 @@
 | reachableBy              | Adds a static route that may be needed to connect to a peer. In some cases, not having a static route for BGP peering results in route flapping. By adding the address of the gateway that the peer is connected to, a static route is added to prevent route flapping.                                                                                                                                                                                                                                                                                                                                                                                    | The address of the gateway that the peer is connected to                                    | string                      |                                                                              |
 | nextHopMode              | Specifies the method of calculating the next hop attribute for received routes. This replaces and expands the deprecated KeepOriginalNextHop field. Users should use this setting to control the next hop attribute for a BGP peer. When this is set, the value of the keepOriginalNextHop field is ignored. If neither keepOriginalNextHop or nextHopMode is specified, BGP's default behavior is used. Default value “Auto” means to apply BGP’s default behavior. "Self" means to configure "next hop self;" in "bird.cfg". "Keep" means to configure "next hop keep;" in "bird.cfg".                                                                   | "Auto", "Self", "Keep"                                                                      | string                      | "Auto"                                                                       |
 | reversePeering | Specifies whether Calico automatically generates reverse peerings for nodes selected by the peerSelector. If set to Manual, a separate BGPPeer must be created for the reverse peering. | "Auto", "Manual" | string | "Auto" |
+| connectionMode | Controls which end initiates the BGP connection for the peerings generated by this resource, from the perspective of the node(s) selected by `node`/`nodeSelector`. "Auto" uses $[prodname]'s built-in selection. "Active" makes the selected node(s) initiate the connection; "Passive" makes them wait for the far end to initiate. "Active" and "Passive" are only valid for an explicit-`peerIP` or `localWorkloadSelector` peer; a `peerSelector` peer must be "Auto". | "Auto", "Active", "Passive" | string | "Auto" |
 
 :::tip