diff --git a/docs/en/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md b/docs/en/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md new file mode 100644 index 000000000..d5d0f3b04 --- /dev/null +++ b/docs/en/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md @@ -0,0 +1,62 @@ +--- +kind: + - Troubleshooting +products: + - Alauda Container Platform +ProductsVersion: + - '4.3.x,4.4.x' +--- + +# S2 Workaround for Host FRR and MetalLB FRR Conflicts + +## Problem + +Some bare-metal ACP nodes already run a customer-managed FRR service as a systemd unit. When MetalLB uses its `frr` BGP backend, each MetalLB speaker Pod runs in the host network namespace with FRR-related containers. The MetalLB FRR process can then modify routes in the node's main routing table and interfere with the customer-managed FRR service. + +## Root Cause + +MetalLB speakers use `hostNetwork: true`. With the `frr` BGP backend, the speaker Pod includes `frr`, `reloader`, and `frr-metrics` containers. The MetalLB FRR process shares the node network namespace with the systemd-managed FRR service, so both processes can affect the host routing and BGP control plane. + +## Temporary Workaround + +Change MetalLB to its `native` BGP backend. This removes the MetalLB-managed FRR containers from the speaker Pod, so MetalLB no longer runs an FRR process in the node network namespace. + +Use this workaround only on a non-OpenShift cluster. The native BGP backend is not supported on OpenShift. + +### 1. Configure BGP peers in the console + +Open the target cluster, then go to **Networking -> BGP Peers**. Create or edit the BGP peer used by MetalLB. + +Do not edit a ConfigMap or manually create `BGPPeer` resources for this configuration. Set these fields in the console: + +- **Local AS**, **Remote AS**, and **Remote IP**: use the values assigned for MetalLB by the network team. +- **Local IP**: use an address that is not used by the host FRR service. +- **Router ID**: use an identifier that is not used by the host FRR service. +- **BGP connection node**: select only the nodes assigned to MetalLB. When available, select nodes that do not run the customer-managed FRR service. + +MetalLB and host FRR must not use the same local address, neighbor, router ID, or advertised prefixes. + +### 2. Configure the BGP external address pool in the console + +Go to **Networking -> External IP Pools** and create or edit the pool used by the LoadBalancer Services: + +1. Set **Type** to **BGP**. +2. Enter the MetalLB VIP range in **IP Resources**. +3. Associate the BGP peer created in the previous step. +4. Select only the nodes that are allowed to advertise the VIP range. + +The VIP range must not overlap with prefixes advertised by the host FRR service. + +### 3. Switch the MetalLB backend + +The current console exposes BGP peers and external address pools, but does not expose the MetalLB `bgpBackend` setting. An S2 engineer changes this setting to `native` during the maintenance window. The change rolls the speaker DaemonSet. + +### 4. Verify the result + +After the speaker rollout, confirm that the speaker Pod no longer contains `frr`, `reloader`, or `frr-metrics` containers. Then use the normal network monitoring tools to confirm the MetalLB BGP session and VIP route advertisement. + +Pod readiness alone does not prove that the BGP session is established or that the expected VIP prefixes are advertised. + +## Rollback + +If native mode cannot meet the BGP requirements, an S2 engineer can change the backend back to `frr`. Do not roll back while the original host FRR conflict is unresolved. diff --git a/docs/zh/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md b/docs/zh/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md new file mode 100644 index 000000000..b10c2d626 --- /dev/null +++ b/docs/zh/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md @@ -0,0 +1,62 @@ +--- +kind: + - Troubleshooting +products: + - Alauda Container Platform +ProductsVersion: + - '4.3.x,4.4.x' +--- + +# S2 临时方案:解决主机 FRR 与 MetalLB FRR 的冲突 + +## 问题 + +部分裸金属 ACP 节点已通过 systemd 运行客户自行维护的 FRR 服务。当 MetalLB 使用 `frr` BGP 后端时,每个 MetalLB speaker Pod 都会在主机网络命名空间中运行多个 FRR 相关容器。MetalLB 的 FRR 进程可能修改节点主路由表,并与客户维护的 FRR 服务相互影响。 + +## 根本原因 + +MetalLB speaker 使用 `hostNetwork: true`。当 BGP 后端为 `frr` 时,speaker Pod 包含 `frr`、`reloader` 和 `frr-metrics` 容器。MetalLB FRR 进程与由 systemd 管理的 FRR 服务共享节点网络命名空间,因此二者都可能影响主机路由和 BGP 控制面。 + +## 临时解决方案 + +将 MetalLB 切换为 `native` BGP 后端。此操作会从 speaker Pod 中移除 MetalLB 管理的 FRR 容器,使 MetalLB 不再在节点网络命名空间中运行 FRR 进程。 + +本方案仅适用于非 OpenShift 集群。MetalLB native BGP 后端不支持 OpenShift。 + +### 1. 在控制台配置 BGP 对等体 + +进入目标集群,选择 **网络 -> BGP 对等体**,创建或编辑 MetalLB 使用的 BGP 对等体。 + +此处不需要编辑 ConfigMap,也不需要手动创建 `BGPPeer` 资源。请在控制台中配置以下字段: + +- **本地 AS**、**对端 AS**、**对端 IP**:使用网络团队分配给 MetalLB 的参数。 +- **本地 IP**:必须与主机 FRR 使用的地址不同。 +- **Router ID**:必须与主机 FRR 使用的 Router ID 不同。 +- **BGP 连接节点**:仅选择分配给 MetalLB 的节点;如有条件,选择未运行客户 FRR 服务的节点。 + +MetalLB 与主机 FRR 不得使用相同的本地地址、邻居、Router ID 或宣告前缀。 + +### 2. 在控制台配置 BGP 外部地址池 + +选择 **网络 -> 外部地址池**,创建或编辑 LoadBalancer 服务使用的地址池: + +1. 将 **类型** 设置为 **BGP**。 +2. 在 **IP 资源** 中填写 MetalLB VIP 范围。 +3. 关联上一步创建的 BGP 对等体。 +4. 仅选择允许宣告该 VIP 范围的节点。 + +VIP 范围不得与主机 FRR 服务宣告的前缀重叠。 + +### 3. 切换 MetalLB 后端 + +当前控制台已提供 BGP 对等体和外部地址池配置,但未提供 MetalLB `bgpBackend` 配置项。由 S2 工程师在维护窗口内将其切换为 `native`,该操作会滚动更新 speaker DaemonSet。 + +### 4. 验证结果 + +speaker 滚动更新完成后,确认 speaker Pod 中不再包含 `frr`、`reloader`、`frr-metrics` 容器。然后使用正常的网络监控工具确认 MetalLB BGP 会话及 VIP 路由宣告。 + +Pod 就绪并不能证明 BGP 会话已建立,也不能证明预期 VIP 前缀已完成宣告。 + +## 回滚 + +若 native 模式无法满足 BGP 要求,S2 工程师可将后端恢复为 `frr`。原有主机 FRR 冲突未解决时,不应回滚。