MetalLB 负载均衡器 v0.14 升级避坑指南：配置迁移前必须处理的 3 个破坏性变更

MetalLB 负载均衡器 v0.14 升级避坑指南：配置迁移前必须处理的 3 个破坏性变更

【免费下载链接】metallbA network load-balancer implementation for Kubernetes using standard routing protocols项目地址: https://gitcode.com/gh_mirrors/me/metallb

MetalLB 是 Kubernetes 的网络负载均衡器实现，通过 BGP 和二层协议把 Service 的 IP 宣告到集群外网络。这次 MetalLB 升级（v0.13 → v0.14）的核心差异只有一个：旧的 ConfigMap 配置通道被彻底移除，所有配置改为一组 CRD 管理（IPAddressPool、BGPPeer、BGPAdvertisement 等）。如果你一直用 ConfigMap 配置，升级瞬间 MetalLB 会找不到任何配置，Service 将全部丢失外部 IP。本文按时间线带你走完整个升级过程：升级前摸底、升级中迁移配置并处理破坏性变更、升级后验证与回滚。

升级前必查的 3 件事

确认你是否还在用旧版 ConfigMap 配置

v0.13 里你可以继续用metallb-system命名空间下的configConfigMap 来配置。先查一下：

kubectl get configmap -n metallb-system -o name

如果它存在、且集群里没有任何 CRD 资源，说明你升级前必须完成配置迁移；反之则可以直接升级。

备份旧配置

迁移工具完全依赖这份文件生成新资源，它丢了，IP 池和 BGP 对等体信息就无法从集群恢复。先导出到本地文件再动手：

kubectl get configmap -n metallb-system config -o yaml > metallb-config-backup.yaml

检查集群版本并记录 Helm revision

v0.14 要求 Kubernetes 至少 1.21。同时记下当前 Helm release 的 revision 号——这是升级失败时回滚的唯一凭证，务必写进你的操作记录里。

如何把旧配置迁移到新 CRD

这是整个 MetalLB 版本迁移里最关键的一步。项目自带 configmaptocrs/ 迁移工具，把旧 ConfigMap 离线转换成包含新 CRD 的resources.yaml：

kubectl get configmap -n metallb-system config -o yaml > config.yaml docker run -d -v $(pwd):/var/input quay.io/metallb/configmaptocrs

跑完后当前目录会多出resources.yaml，原来的单份 ConfigMap 被拆成 IPAddressPool、BGPPeer、BGPAdvertisement 等独立资源。应用前注意两点：

• 资源名会被清洗：旧配置里带下划线或大写字母的池名，会被自动改成连字符和小写。如果你别处按名字引用过这些池，记得同步修改。
• 生成的 BGPPeer 已经是 v1beta2 API，其余资源为 v1beta1，属正常现象。

然后按顺序应用，先装 CRD 再上资源，顺序反了 controller 会一直报找不到资源：

kubectl apply -f config/crd/bases/ kubectl apply -f resources.yaml

确认新资源状态正常后，再删除旧 ConfigMap。

v0.14 的三个核心变更点

BGPPeer 从 v1beta1 弃用到 v1beta2

集群里遗留的 v1beta1 BGPPeer 还能被转换 webhook 兜底，但新字段和校验逻辑都只存在于 v1beta2。新建或修改 BGPPeer 时直接写apiVersion: metallb.io/v1beta2，并排查一遍集群里是否还有旧版本的存量资源。

FRR 模式成为默认 BGP 后端

默认 BGP 宣告从内置 native 实现换成了 FRR。好处是支持 BFD、IPv6 等更完整的特性，代价是每个节点多跑一个 FRR 容器，资源占用上升，升级前确认节点 CPU 和内存余量。如果确实要留在 native 模式，可在 Helm values 中显式指定，但该路径功能受限，后续新特性只会加到 FRR 一侧。

注解前缀切换

Service 上metallb.universe.tf/address-pool这类注解被metallb.io/address-pool取代。旧前缀暂时仍有效，但后续版本可能移除兼容处理，建议升级时统一替换掉所有存量注解。

升级后如何验证服务宣告状态

升级完成后按三步验证：

1. kubectl get pods -n metallb-system -o wide，controller 与 speaker 全部 Running；
2. kubectl get ipaddresspools -n metallb-system，新版本 IPAddressPool 带 status 字段，显示可用/已分配 IP 数量，若显示耗尽，说明迁移后池被占满，需要扩段；
3. kubectl get servicebgpstatus -n metallb-system，核对每个 Service 正在向哪些对等体宣告。

有外部路由器的话，登上去看 BGP 邻居：会话 Established 且收到前缀，才是真正成功。

升级卡住怎么排查、如何回滚到旧版本

⚠️ 看到 "BGP not connected, 无路由" 先别慌：这表示会话已建立但没宣告任何路由，与"会话根本没建立"是两类问题，排查方向完全不同。

常见排查入口：

• BGPPeer 的 myASN、peerAddress 与旧配置不一致，或 FRR 容器反复重启（kubectl describe pod看事件）；
• CRD 与资源应用顺序颠倒，controller 拉不到配置；
• v0.13 残留的 ConfigMap 被删得太早，而新资源还没建好。

回滚方案：如果约定时间内无法恢复，先恢复业务——Helm 回滚到旧 revision、恢复备份的 ConfigMap、删掉新资源。前提是升级前那份 ConfigMap 备份，在你彻底确认新配置正确之前不要删：

helm rollback metallb <revision> -n metallb-system kubectl apply -f metallb-config-backup.yaml

业务恢复后再回头定位升级失败的根因。

升级检查清单

• 旧 ConfigMap 已导出备份到本地文件
• 已记录当前 Helm revision 号
• 已用 configmaptocrs 生成 resources.yaml，并核对资源名变更
• 先安装 CRD，再应用新资源
• BGPPeer 全部使用 v1beta2 API
• 节点资源足够承载 FRR 容器
• 旧前缀注解已替换为metallb.io前缀
• 已核对 IPAddressPool 状态与 ServiceBGPStatus 宣告关系
• 外部路由器已确认 BGP 会话与路由宣告

更多细节可参考项目内资料：

• 迁移工具说明：configmaptocrs/README.md
• Helm 配置选项：charts/metallb/values.yaml
• 完整发行说明：website/content/release-notes/_index.md

【免费下载链接】metallbA network load-balancer implementation for Kubernetes using standard routing protocols项目地址: https://gitcode.com/gh_mirrors/me/metallb