From 318794e0eaad35fa3ec727f36c4e78a1cce3d1f2 Mon Sep 17 00:00:00 2001 From: clyi Date: Tue, 25 Aug 2026 20:04:10 +0800 Subject: [PATCH 1/7] docs(acp): add MetalLB host FRR conflict resolution --- ...S2_Use_Native_BGP_Backend_with_Host_FRR.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 docs/en/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md 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..273fa9f28 --- /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' +--- + +# Resolve Host FRR and MetalLB FRR Conflicts by Using the Native BGP Backend + +## 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. + +## Resolution + +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. Confirm the cluster type before changing the backend. + +### 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. A platform administrator 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, a platform administrator can change the backend back to `frr`. Do not roll back while the original host FRR conflict is unresolved. From 28b0b9098743b9c9ad57a88ca9063890dda63174 Mon Sep 17 00:00:00 2001 From: clyi Date: Wed, 26 Aug 2026 11:57:05 +0800 Subject: [PATCH 2/7] docs(acp): align MetalLB workaround with KB style --- ...S2_Use_Native_BGP_Backend_with_Host_FRR.md | 117 ++++++++++++++---- 1 file changed, 95 insertions(+), 22 deletions(-) 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 index 273fa9f28..ec663f12d 100644 --- 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 @@ -9,54 +9,127 @@ ProductsVersion: # Resolve Host FRR and MetalLB FRR Conflicts by Using the Native BGP Backend -## Problem +## Issue -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. +On a bare-metal Alauda Container Platform cluster, a customer-managed FRR service runs as a systemd unit on the nodes and has established BGP sessions. After the MetalLB plugin is installed, the MetalLB Speaker Pods start their own FRR processes and the host's main routing table can lose BGP routes. The two FRR instances can also interfere with each other's BGP sessions. + +This solution applies when the host FRR service and MetalLB Speakers run on the same nodes. It does not apply to OpenShift clusters. + +## Environment + +- Alauda Container Platform 4.3.x or 4.4.x. +- A bare-metal, non-OpenShift cluster. +- The MetalLB plugin is installed and configured for BGP advertisement. +- A customer-managed FRR service runs on one or more nodes as a systemd unit. ## 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. +MetalLB Speakers use `hostNetwork: true`. With the `frr` BGP backend, each Speaker Pod also runs the MetalLB-managed `frr`, `reloader`, and `frr-metrics` containers. These processes share the node network namespace with the systemd-managed FRR service, so both FRR instances can modify the host routing table and manage overlapping BGP state. + +For non-OpenShift clusters, MetalLB uses the `frr` backend when `spec.bgpBackend` is not set. The MetalLB `MetalLB` custom resource supports the `native` backend, which establishes BGP sessions without deploying the MetalLB FRR containers. ## Resolution -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 the `native` BGP backend and give MetalLB its own BGP session identity. + +:::warning +Updating the `MetalLB` resource rolls the Speaker DaemonSet and can briefly interrupt MetalLB BGP advertisements. Perform the change during a maintenance window and confirm the advertised VIP routes after the rollout. +::: -Use this workaround only on a non-OpenShift cluster. Confirm the cluster type before changing the backend. +### 1. Confirm the current MetalLB backend -### 1. Configure BGP peers in the console +The plugin creates a `MetalLB` resource named `metallb` in the `metallb-system` namespace by default. Run the following commands before changing it: -Open the target cluster, then go to **Networking -> BGP Peers**. Create or edit the BGP peer used by MetalLB. +```bash +kubectl -n metallb-system get metallb +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +``` -Do not edit a ConfigMap or manually create `BGPPeer` resources for this configuration. Set these fields in the console: +If the `bgpBackend` output is empty on a non-OpenShift cluster, the Operator uses `frr` by default. If the container list includes `frr`, the MetalLB FRR process is running in the Speaker Pod. Replace `metallb` in the commands if the resource has a different name. -- **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. +### 2. Configure independent BGP sessions -MetalLB and host FRR must not use the same local address, neighbor, router ID, or advertised prefixes. +In the target cluster, go to **Administrator -> Network Management -> BGP Peers** and create or edit the BGP peers used by MetalLB. Configure values reserved for MetalLB: -### 2. Configure the BGP external address pool in the console +- **Local AS Number**: The local AS number for the MetalLB session. Do not reuse the host FRR local AS number when the upstream router requires separate sessions. +- **Peer AS Number** and **Peer IP**: The values configured on the upstream router for the MetalLB session. +- **Local IP**: A source address that is different from the source address used by the host FRR session. +- **RouterID**: A router ID that is different from the host FRR router ID and other BGP instances on the node. +- **BGP-Connected Node**: Only the nodes that have the MetalLB source address and should run the MetalLB Speaker. -Go to **Networking -> External IP Pools** and create or edit the pool used by the LoadBalancer Services: +If MetalLB and the host FRR service use the same upstream router, configure the router to accept both sessions. MetalLB and host FRR must not reuse the same local address, router ID, or advertised prefixes. + +### 3. Configure the BGP external address pool + +Go to **Administrator -> Network Management -> External IP Address Pool** 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. +3. Associate the MetalLB BGP peer. 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 +### 4. Switch MetalLB to the native BGP backend + +The console does not expose the `spec.bgpBackend` field. A platform administrator must set it with `kubectl`: + +```bash +kubectl -n metallb-system patch metallb metallb \ + --type=merge \ + -p '{"spec":{"bgpBackend":"native"}}' +``` + +The command should report that the resource was configured. The Operator then rolls the Speaker DaemonSet and removes the MetalLB-managed FRR containers. It does not stop or reconfigure the host FRR systemd service. -The current console exposes BGP peers and external address pools, but does not expose the MetalLB `bgpBackend` setting. A platform administrator changes this setting to `native` during the maintenance window. The change rolls the speaker DaemonSet. +### 5. Verify the result -### 4. Verify the result +Wait for the Speaker rollout to complete: -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. +```bash +kubectl -n metallb-system rollout status daemonset/speaker +``` -Pod readiness alone does not prove that the BGP session is established or that the expected VIP prefixes are advertised. +Confirm that the backend is `native` and the Speaker template no longer contains the MetalLB FRR containers: + +```bash +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide +``` + +The first command must return `native`. The container list must not include `frr`, `reloader`, `frr-metrics`, or `metrics-auth-proxy-frr`. All Speaker Pods should be `Running` and `Ready`. Pod readiness alone does not prove that BGP sessions are established or that VIP prefixes are advertised; confirm both the MetalLB session and the existing host FRR sessions with the upstream router or the customer's normal network monitoring tools. + +The `MetalLB` resource stores this setting. Recheck `spec.bgpBackend` after a MetalLB plugin upgrade or reinstall, because a resource recreation or reset can restore the default backend. + +## Diagnostic Steps + +Use the following checks to determine whether the host FRR and MetalLB FRR conflict is present: + +```bash +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{.spec.template.spec.hostNetwork}{"\n"}{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +kubectl -n metallb-system get bgppeers,bgpadvertisements,ipaddresspools +``` + +An empty backend on a non-OpenShift cluster and an `frr` container in the Speaker template indicate that the default MetalLB FRR backend is active. `hostNetwork` should be `true`. Compare the BGP peer source address, router ID, local AS number, and advertised prefixes with the host FRR configuration and the upstream router configuration. ## Rollback -If native mode cannot meet the BGP requirements, a platform administrator can change the backend back to `frr`. Do not roll back while the original host FRR conflict is unresolved. +If the native backend cannot meet the BGP requirements, restore the FRR backend: + +```bash +kubectl -n metallb-system patch metallb metallb \ + --type=merge \ + -p '{"spec":{"bgpBackend":"frr"}}' +kubectl -n metallb-system rollout status daemonset/speaker +``` + +After the rollout, confirm that the required FRR containers are present and validate the BGP sessions. Do not roll back while the original host FRR conflict is unresolved. From 2c80f3bdb968386f5835f83805a48fb09418a3b4 Mon Sep 17 00:00:00 2001 From: clyi Date: Thu, 27 Aug 2026 10:28:35 +0800 Subject: [PATCH 3/7] docs(acp): add Chinese MetalLB host FRR guidance --- ...S2_Use_Native_BGP_Backend_with_Host_FRR.md | 135 ++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 docs/zh/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md 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..9ebe77d44 --- /dev/null +++ b/docs/zh/solutions/acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md @@ -0,0 +1,135 @@ +--- +kind: + - Troubleshooting +products: + - Alauda Container Platform +ProductsVersion: + - '4.3.x,4.4.x' +--- + +# 使用 Native BGP 后端解决主机 FRR 与 MetalLB FRR 冲突 + +## 问题 + +在裸金属 Alauda Container Platform 集群中，客户自行维护的 FRR 服务以 systemd 单元的方式运行在节点上，并且已经建立 BGP 会话。安装 MetalLB 插件后，MetalLB Speaker Pod 会启动自身的 FRR 进程，可能导致主机主路由表中的 BGP 路由丢失。两套 FRR 实例还可能相互干扰 BGP 会话。 + +当主机 FRR 服务与 MetalLB Speaker 运行在相同节点上时，适用本解决方案。本方案不适用于 OpenShift 集群。 + +## 环境 + +- Alauda Container Platform 4.3.x 或 4.4.x。 +- 裸金属、非 OpenShift 集群。 +- 已安装 MetalLB 插件，并已配置 BGP 宣告。 +- 一个或多个节点上以 systemd 单元的方式运行客户自行维护的 FRR 服务。 + +## 根本原因 + +MetalLB Speaker 使用 `hostNetwork: true`。当 BGP 后端为 `frr` 时，每个 Speaker Pod 还会运行由 MetalLB 管理的 `frr`、`reloader` 和 `frr-metrics` 容器。这些进程与 systemd 管理的 FRR 服务共享节点网络命名空间，因此两套 FRR 实例都可能修改主机路由表并管理相互重叠的 BGP 状态。 + +在非 OpenShift 集群中，如果未设置 `spec.bgpBackend`，MetalLB 默认使用 `frr` 后端。MetalLB 自定义资源支持 `native` 后端；该后端建立 BGP 会话时不会部署 MetalLB FRR 容器。 + +## 解决方案 + +使用 `native` BGP 后端，并为 MetalLB 配置独立的 BGP 会话身份。 + +:::warning +更新 `MetalLB` 资源会滚动更新 Speaker DaemonSet，可能短暂中断 MetalLB 的 BGP 宣告。请在维护窗口内执行变更，并在滚动更新完成后确认 VIP 路由已重新宣告。 +::: + +### 1. 确认当前 MetalLB 后端 + +插件默认会在 `metallb-system` 命名空间中创建名为 `metallb` 的 `MetalLB` 资源。在修改资源前执行以下命令： + +```bash +kubectl -n metallb-system get metallb +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +``` + +在非 OpenShift 集群中，如果 `bgpBackend` 输出为空，表示 Operator 默认使用 `frr`。如果容器列表中包含 `frr`，表示 MetalLB FRR 进程正在 Speaker Pod 中运行。如果资源名称不同，请在后续命令中将 `metallb` 替换为实际资源名。 + +### 2. 配置独立的 BGP 会话 + +在目标集群中，进入 **管理员 -> 网络管理 -> BGP 对等体**，创建或编辑 MetalLB 使用的 BGP 对等体。配置为 MetalLB 保留的参数： + +- **本地 AS 号**：MetalLB 会话使用的本地 AS 号。当上游路由器要求使用独立会话时，不要复用主机 FRR 的本地 AS 号。 +- **对端 AS 号** 和 **对端 IP**：上游路由器为 MetalLB 会话配置的参数。 +- **本地 IP**：与主机 FRR 会话使用的源地址不同的地址。 +- **RouterID**：与主机 FRR Router ID 以及节点上的其他 BGP 实例不同的 Router ID。 +- **BGP 连接节点**：仅选择配置了 MetalLB 源地址并且需要运行 MetalLB Speaker 的节点。 + +如果 MetalLB 和主机 FRR 服务使用同一个上游路由器，请在路由器上配置并接受两个会话。MetalLB 与主机 FRR 不得复用相同的本地地址、Router ID 或宣告前缀。 + +### 3. 配置 BGP 外部地址池 + +进入 **管理员 -> 网络管理 -> 外部 IP 地址池**，创建或编辑 LoadBalancer 服务使用的地址池： + +1. 将 **类型** 设置为 **BGP**。 +2. 在 **IP 资源** 中填写 MetalLB VIP 范围。 +3. 关联 MetalLB BGP 对等体。 +4. 仅选择允许宣告该 VIP 范围的节点。 + +VIP 范围不得与主机 FRR 服务宣告的前缀重叠。 + +### 4. 将 MetalLB 切换到 Native BGP 后端 + +控制台不提供 `spec.bgpBackend` 字段。平台管理员必须使用 `kubectl` 设置该字段： + +```bash +kubectl -n metallb-system patch metallb metallb \ + --type=merge \ + -p '{"spec":{"bgpBackend":"native"}}' +``` + +命令应报告资源已被配置。随后 Operator 会滚动更新 Speaker DaemonSet，并移除由 MetalLB 管理的 FRR 容器。该操作不会停止或重新配置主机上的 FRR systemd 服务。 + +### 5. 验证结果 + +等待 Speaker 滚动更新完成： + +```bash +kubectl -n metallb-system rollout status daemonset/speaker +``` + +确认后端为 `native`，并且 Speaker 模板中不再包含 MetalLB FRR 容器： + +```bash +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide +``` + +第一条命令必须返回 `native`。容器列表中不得包含 `frr`、`reloader`、`frr-metrics` 或 `metrics-auth-proxy-frr`。所有 Speaker Pod 都应处于 `Running` 和 `Ready` 状态。Pod 就绪不能单独证明 BGP 会话已经建立或 VIP 前缀已经宣告；请通过上游路由器或客户现有的网络监控工具，同时确认 MetalLB 会话和原有主机 FRR 会话。 + +`MetalLB` 资源会保存此设置。MetalLB 插件升级或重装后，请重新检查 `spec.bgpBackend`，因为资源重建或重置可能恢复默认后端。 + +## 诊断步骤 + +使用以下检查确定是否存在主机 FRR 与 MetalLB FRR 冲突： + +```bash +kubectl -n metallb-system get metallb metallb \ + -o jsonpath='{.spec.bgpBackend}{"\n"}' +kubectl -n metallb-system get daemonset speaker \ + -o jsonpath='{.spec.template.spec.hostNetwork}{"\n"}{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' +kubectl -n metallb-system get bgppeers,bgpadvertisements,ipaddresspools +``` + +在非 OpenShift 集群中，后端输出为空且 Speaker 模板中包含 `frr`，表示 MetalLB 默认 FRR 后端处于启用状态。`hostNetwork` 应为 `true`。将 BGP 对等体的源地址、Router ID、本地 AS 号和宣告前缀与主机 FRR 配置及上游路由器配置进行比较。 + +## 回滚 + +如果 Native 后端无法满足 BGP 要求，请恢复 FRR 后端： + +```bash +kubectl -n metallb-system patch metallb metallb \ + --type=merge \ + -p '{"spec":{"bgpBackend":"frr"}}' +kubectl -n metallb-system rollout status daemonset/speaker +``` + +滚动更新完成后，确认所需的 FRR 容器已恢复，并验证 BGP 会话。原有主机 FRR 冲突未解决时，不要回滚到 `frr`。 From cdc6c6af9fb188e4e0a8e7c51f1c3d7107279f90 Mon Sep 17 00:00:00 2001 From: clyi Date: Thu, 27 Aug 2026 11:11:49 +0800 Subject: [PATCH 4/7] docs(acp): streamline MetalLB host FRR guidance --- ...alLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 14 -------------- ...alLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 14 -------------- 2 files changed, 28 deletions(-) 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 index ec663f12d..702a4171a 100644 --- 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 @@ -107,20 +107,6 @@ The first command must return `native`. The container list must not include `frr The `MetalLB` resource stores this setting. Recheck `spec.bgpBackend` after a MetalLB plugin upgrade or reinstall, because a resource recreation or reset can restore the default backend. -## Diagnostic Steps - -Use the following checks to determine whether the host FRR and MetalLB FRR conflict is present: - -```bash -kubectl -n metallb-system get metallb metallb \ - -o jsonpath='{.spec.bgpBackend}{"\n"}' -kubectl -n metallb-system get daemonset speaker \ - -o jsonpath='{.spec.template.spec.hostNetwork}{"\n"}{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' -kubectl -n metallb-system get bgppeers,bgpadvertisements,ipaddresspools -``` - -An empty backend on a non-OpenShift cluster and an `frr` container in the Speaker template indicate that the default MetalLB FRR backend is active. `hostNetwork` should be `true`. Compare the BGP peer source address, router ID, local AS number, and advertised prefixes with the host FRR configuration and the upstream router configuration. - ## Rollback If the native backend cannot meet the BGP requirements, restore the FRR backend: 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 index 9ebe77d44..cf793c8f6 100644 --- 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 @@ -107,20 +107,6 @@ kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide `MetalLB` 资源会保存此设置。MetalLB 插件升级或重装后，请重新检查 `spec.bgpBackend`，因为资源重建或重置可能恢复默认后端。 -## 诊断步骤 - -使用以下检查确定是否存在主机 FRR 与 MetalLB FRR 冲突： - -```bash -kubectl -n metallb-system get metallb metallb \ - -o jsonpath='{.spec.bgpBackend}{"\n"}' -kubectl -n metallb-system get daemonset speaker \ - -o jsonpath='{.spec.template.spec.hostNetwork}{"\n"}{range .spec.template.spec.containers[*]}{.name}{"\n"}{end}' -kubectl -n metallb-system get bgppeers,bgpadvertisements,ipaddresspools -``` - -在非 OpenShift 集群中，后端输出为空且 Speaker 模板中包含 `frr`，表示 MetalLB 默认 FRR 后端处于启用状态。`hostNetwork` 应为 `true`。将 BGP 对等体的源地址、Router ID、本地 AS 号和宣告前缀与主机 FRR 配置及上游路由器配置进行比较。 - ## 回滚 如果 Native 后端无法满足 BGP 要求，请恢复 FRR 后端： From 6ce0fa0b6920a17fff404265c1f020b5e7c057f1 Mon Sep 17 00:00:00 2001 From: clyi Date: Thu, 27 Aug 2026 11:14:31 +0800 Subject: [PATCH 5/7] docs(acp): limit MetalLB guidance to native backend switch --- ...S2_Use_Native_BGP_Backend_with_Host_FRR.md | 31 +++---------------- ...S2_Use_Native_BGP_Backend_with_Host_FRR.md | 31 +++---------------- 2 files changed, 8 insertions(+), 54 deletions(-) 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 index 702a4171a..669dab1cb 100644 --- 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 @@ -30,7 +30,7 @@ For non-OpenShift clusters, MetalLB uses the `frr` backend when `spec.bgpBackend ## Resolution -Use the `native` BGP backend and give MetalLB its own BGP session identity. +Switch MetalLB to the `native` BGP backend to disable the MetalLB-managed FRR containers. :::warning Updating the `MetalLB` resource rolls the Speaker DaemonSet and can briefly interrupt MetalLB BGP advertisements. Perform the change during a maintenance window and confirm the advertised VIP routes after the rollout. @@ -50,30 +50,7 @@ kubectl -n metallb-system get daemonset speaker \ If the `bgpBackend` output is empty on a non-OpenShift cluster, the Operator uses `frr` by default. If the container list includes `frr`, the MetalLB FRR process is running in the Speaker Pod. Replace `metallb` in the commands if the resource has a different name. -### 2. Configure independent BGP sessions - -In the target cluster, go to **Administrator -> Network Management -> BGP Peers** and create or edit the BGP peers used by MetalLB. Configure values reserved for MetalLB: - -- **Local AS Number**: The local AS number for the MetalLB session. Do not reuse the host FRR local AS number when the upstream router requires separate sessions. -- **Peer AS Number** and **Peer IP**: The values configured on the upstream router for the MetalLB session. -- **Local IP**: A source address that is different from the source address used by the host FRR session. -- **RouterID**: A router ID that is different from the host FRR router ID and other BGP instances on the node. -- **BGP-Connected Node**: Only the nodes that have the MetalLB source address and should run the MetalLB Speaker. - -If MetalLB and the host FRR service use the same upstream router, configure the router to accept both sessions. MetalLB and host FRR must not reuse the same local address, router ID, or advertised prefixes. - -### 3. Configure the BGP external address pool - -Go to **Administrator -> Network Management -> External IP Address Pool** 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 MetalLB BGP peer. -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. - -### 4. Switch MetalLB to the native BGP backend +### 2. Switch MetalLB to the native BGP backend The console does not expose the `spec.bgpBackend` field. A platform administrator must set it with `kubectl`: @@ -85,7 +62,7 @@ kubectl -n metallb-system patch metallb metallb \ The command should report that the resource was configured. The Operator then rolls the Speaker DaemonSet and removes the MetalLB-managed FRR containers. It does not stop or reconfigure the host FRR systemd service. -### 5. Verify the result +### 3. Verify the result Wait for the Speaker rollout to complete: @@ -103,7 +80,7 @@ kubectl -n metallb-system get daemonset speaker \ kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide ``` -The first command must return `native`. The container list must not include `frr`, `reloader`, `frr-metrics`, or `metrics-auth-proxy-frr`. All Speaker Pods should be `Running` and `Ready`. Pod readiness alone does not prove that BGP sessions are established or that VIP prefixes are advertised; confirm both the MetalLB session and the existing host FRR sessions with the upstream router or the customer's normal network monitoring tools. +The first command must return `native`. The container list must not include `frr`, `reloader`, `frr-metrics`, or `metrics-auth-proxy-frr`. All Speaker Pods should be `Running` and `Ready`. The `MetalLB` resource stores this setting. Recheck `spec.bgpBackend` after a MetalLB plugin upgrade or reinstall, because a resource recreation or reset can restore the default backend. 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 index cf793c8f6..ce9758a1b 100644 --- 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 @@ -30,7 +30,7 @@ MetalLB Speaker 使用 `hostNetwork: true`。当 BGP 后端为 `frr` 时，每 ## 解决方案 -使用 `native` BGP 后端，并为 MetalLB 配置独立的 BGP 会话身份。 +将 MetalLB 切换到 `native` BGP 后端，以停用 MetalLB 管理的 FRR 容器。 :::warning 更新 `MetalLB` 资源会滚动更新 Speaker DaemonSet，可能短暂中断 MetalLB 的 BGP 宣告。请在维护窗口内执行变更，并在滚动更新完成后确认 VIP 路由已重新宣告。 @@ -50,30 +50,7 @@ kubectl -n metallb-system get daemonset speaker \ 在非 OpenShift 集群中，如果 `bgpBackend` 输出为空，表示 Operator 默认使用 `frr`。如果容器列表中包含 `frr`，表示 MetalLB FRR 进程正在 Speaker Pod 中运行。如果资源名称不同，请在后续命令中将 `metallb` 替换为实际资源名。 -### 2. 配置独立的 BGP 会话 - -在目标集群中，进入 **管理员 -> 网络管理 -> BGP 对等体**，创建或编辑 MetalLB 使用的 BGP 对等体。配置为 MetalLB 保留的参数： - -- **本地 AS 号**：MetalLB 会话使用的本地 AS 号。当上游路由器要求使用独立会话时，不要复用主机 FRR 的本地 AS 号。 -- **对端 AS 号** 和 **对端 IP**：上游路由器为 MetalLB 会话配置的参数。 -- **本地 IP**：与主机 FRR 会话使用的源地址不同的地址。 -- **RouterID**：与主机 FRR Router ID 以及节点上的其他 BGP 实例不同的 Router ID。 -- **BGP 连接节点**：仅选择配置了 MetalLB 源地址并且需要运行 MetalLB Speaker 的节点。 - -如果 MetalLB 和主机 FRR 服务使用同一个上游路由器，请在路由器上配置并接受两个会话。MetalLB 与主机 FRR 不得复用相同的本地地址、Router ID 或宣告前缀。 - -### 3. 配置 BGP 外部地址池 - -进入 **管理员 -> 网络管理 -> 外部 IP 地址池**，创建或编辑 LoadBalancer 服务使用的地址池： - -1. 将 **类型** 设置为 **BGP**。 -2. 在 **IP 资源** 中填写 MetalLB VIP 范围。 -3. 关联 MetalLB BGP 对等体。 -4. 仅选择允许宣告该 VIP 范围的节点。 - -VIP 范围不得与主机 FRR 服务宣告的前缀重叠。 - -### 4. 将 MetalLB 切换到 Native BGP 后端 +### 2. 将 MetalLB 切换到 Native BGP 后端 控制台不提供 `spec.bgpBackend` 字段。平台管理员必须使用 `kubectl` 设置该字段： @@ -85,7 +62,7 @@ kubectl -n metallb-system patch metallb metallb \ 命令应报告资源已被配置。随后 Operator 会滚动更新 Speaker DaemonSet，并移除由 MetalLB 管理的 FRR 容器。该操作不会停止或重新配置主机上的 FRR systemd 服务。 -### 5. 验证结果 +### 3. 验证结果 等待 Speaker 滚动更新完成： @@ -103,7 +80,7 @@ kubectl -n metallb-system get daemonset speaker \ kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide ``` -第一条命令必须返回 `native`。容器列表中不得包含 `frr`、`reloader`、`frr-metrics` 或 `metrics-auth-proxy-frr`。所有 Speaker Pod 都应处于 `Running` 和 `Ready` 状态。Pod 就绪不能单独证明 BGP 会话已经建立或 VIP 前缀已经宣告；请通过上游路由器或客户现有的网络监控工具，同时确认 MetalLB 会话和原有主机 FRR 会话。 +第一条命令必须返回 `native`。容器列表中不得包含 `frr`、`reloader`、`frr-metrics` 或 `metrics-auth-proxy-frr`。所有 Speaker Pod 都应处于 `Running` 和 `Ready` 状态。 `MetalLB` 资源会保存此设置。MetalLB 插件升级或重装后，请重新检查 `spec.bgpBackend`，因为资源重建或重置可能恢复默认后端。 From a7b561eda86911b5017ba1ddeab784f8bdc44295 Mon Sep 17 00:00:00 2001 From: clyi Date: Thu, 27 Aug 2026 11:27:05 +0800 Subject: [PATCH 6/7] docs(acp): document native backend patch persistence --- .../acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 3 +-- .../acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) 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 index 669dab1cb..5de9477f8 100644 --- 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 @@ -34,6 +34,7 @@ Switch MetalLB to the `native` BGP backend to disable the MetalLB-managed FRR co :::warning Updating the `MetalLB` resource rolls the Speaker DaemonSet and can briefly interrupt MetalLB BGP advertisements. Perform the change during a maintenance window and confirm the advertised VIP routes after the rollout. +The `kubectl patch` change is not guaranteed to persist. A MetalLB plugin upgrade, reinstall, or resource recreation can remove the change and restore the default `frr` backend. Recheck `spec.bgpBackend` after an upgrade and repeat Step 2 if it is no longer `native`. ::: ### 1. Confirm the current MetalLB backend @@ -82,8 +83,6 @@ kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide The first command must return `native`. The container list must not include `frr`, `reloader`, `frr-metrics`, or `metrics-auth-proxy-frr`. All Speaker Pods should be `Running` and `Ready`. -The `MetalLB` resource stores this setting. Recheck `spec.bgpBackend` after a MetalLB plugin upgrade or reinstall, because a resource recreation or reset can restore the default backend. - ## Rollback If the native backend cannot meet the BGP requirements, restore the FRR backend: 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 index ce9758a1b..69c5d5737 100644 --- 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 @@ -34,6 +34,7 @@ MetalLB Speaker 使用 `hostNetwork: true`。当 BGP 后端为 `frr` 时，每 :::warning 更新 `MetalLB` 资源会滚动更新 Speaker DaemonSet，可能短暂中断 MetalLB 的 BGP 宣告。请在维护窗口内执行变更，并在滚动更新完成后确认 VIP 路由已重新宣告。 +通过 `kubectl patch` 修改的配置不保证在升级后保留。MetalLB 插件升级、重装或资源重建可能删除此修改并恢复默认的 `frr` 后端。升级后请重新检查 `spec.bgpBackend`；如果不再是 `native`，请重新执行步骤 2。 ::: ### 1. 确认当前 MetalLB 后端 @@ -82,8 +83,6 @@ kubectl -n metallb-system get pods -l app=metallb,component=speaker -o wide 第一条命令必须返回 `native`。容器列表中不得包含 `frr`、`reloader`、`frr-metrics` 或 `metrics-auth-proxy-frr`。所有 Speaker Pod 都应处于 `Running` 和 `Ready` 状态。 -`MetalLB` 资源会保存此设置。MetalLB 插件升级或重装后，请重新检查 `spec.bgpBackend`，因为资源重建或重置可能恢复默认后端。 - ## 回滚 如果 Native 后端无法满足 BGP 要求，请恢复 FRR 后端： From 5b0ea9bb61db8c17b99021a30f28c45ccbc64c86 Mon Sep 17 00:00:00 2001 From: clyi Date: Thu, 27 Aug 2026 14:45:40 +0800 Subject: [PATCH 7/7] docs(acp): align MetalLB verification wording --- .../acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 4 ++-- .../acp/MetalLB_S2_Use_Native_BGP_Backend_with_Host_FRR.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) 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 index 5de9477f8..d6438ff40 100644 --- 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 @@ -33,7 +33,7 @@ For non-OpenShift clusters, MetalLB uses the `frr` backend when `spec.bgpBackend Switch MetalLB to the `native` BGP backend to disable the MetalLB-managed FRR containers. :::warning -Updating the `MetalLB` resource rolls the Speaker DaemonSet and can briefly interrupt MetalLB BGP advertisements. Perform the change during a maintenance window and confirm the advertised VIP routes after the rollout. +Updating the `MetalLB` resource rolls the Speaker DaemonSet and can briefly interrupt MetalLB BGP advertisements. Perform the change during a maintenance window and confirm that the Speaker rollout completes successfully. The `kubectl patch` change is not guaranteed to persist. A MetalLB plugin upgrade, reinstall, or resource recreation can remove the change and restore the default `frr` backend. Recheck `spec.bgpBackend` after an upgrade and repeat Step 2 if it is no longer `native`. ::: @@ -61,7 +61,7 @@ kubectl -n metallb-system patch metallb metallb \ -p '{"spec":{"bgpBackend":"native"}}' ``` -The command should report that the resource was configured. The Operator then rolls the Speaker DaemonSet and removes the MetalLB-managed FRR containers. It does not stop or reconfigure the host FRR systemd service. +The command should report `metallb.metallb.io/metallb patched`. The Operator then rolls the Speaker DaemonSet and removes the MetalLB-managed FRR containers. It does not stop or reconfigure the host FRR systemd service. ### 3. Verify the result 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 index 69c5d5737..86cf0745c 100644 --- 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 @@ -33,7 +33,7 @@ MetalLB Speaker 使用 `hostNetwork: true`。当 BGP 后端为 `frr` 时，每 将 MetalLB 切换到 `native` BGP 后端，以停用 MetalLB 管理的 FRR 容器。 :::warning -更新 `MetalLB` 资源会滚动更新 Speaker DaemonSet，可能短暂中断 MetalLB 的 BGP 宣告。请在维护窗口内执行变更，并在滚动更新完成后确认 VIP 路由已重新宣告。 +更新 `MetalLB` 资源会滚动更新 Speaker DaemonSet，可能短暂中断 MetalLB 的 BGP 宣告。请在维护窗口内执行变更，并确认 Speaker 已成功完成滚动更新。 通过 `kubectl patch` 修改的配置不保证在升级后保留。MetalLB 插件升级、重装或资源重建可能删除此修改并恢复默认的 `frr` 后端。升级后请重新检查 `spec.bgpBackend`；如果不再是 `native`，请重新执行步骤 2。 ::: @@ -61,7 +61,7 @@ kubectl -n metallb-system patch metallb metallb \ -p '{"spec":{"bgpBackend":"native"}}' ``` -命令应报告资源已被配置。随后 Operator 会滚动更新 Speaker DaemonSet，并移除由 MetalLB 管理的 FRR 容器。该操作不会停止或重新配置主机上的 FRR systemd 服务。 +命令应返回 `metallb.metallb.io/metallb patched`。随后 Operator 会滚动更新 Speaker DaemonSet，并移除由 MetalLB 管理的 FRR 容器。该操作不会停止或重新配置主机上的 FRR systemd 服务。 ### 3. 验证结果