docs(acp): add MetalLB host FRR S2 workaround

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.

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 冲突未解决时，不应回滚。