From 93f9f41ab5f280179ab664aeebc120870c75f22e Mon Sep 17 00:00:00 2001 From: Chris Tauchen Date: Fri, 23 Oct 2026 12:55:13 +0100 Subject: [PATCH] Document BGPPeer connectionMode for Calico Enterprise 3.23.3 Ports the connectionMode reference row and the live-migration reconvergence section from the next tree to version-3.23-2, where the field first ships. --- .../configuring/bgp-to-workload.mdx | 47 +++++++++++++++++++ .../reference/resources/bgppeer.mdx | 1 + 2 files changed, 48 insertions(+) diff --git a/calico-enterprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx b/calico-enterprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx index 42832cba9b..40fe41fbfb 100644 --- a/calico-enterprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx +++ b/calico-enterprise_versioned_docs/version-3.23-2/networking/configuring/bgp-to-workload.mdx @@ -265,6 +265,53 @@ In the child cluster, asNumber: ``` +### 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: + 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: + 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 index dac5fbb712..45cd7a3f39 100644 --- 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 @@ spec: | 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