目录

LoxiLB 实战:k3s 上的 eBPF LoadBalancer、PodIP 分发与 BGP 通告

LoxiLB 0.9.8.8 + kube-loxilb:单节点实测、端点模式对比与 BGP 路由撤销

自建 Kubernetes 最烦的一件事,是 Service type=LoadBalancer 没有云厂商给你分配 VIP。MetalLB 能补上 L2/BGP 通告,但数据面还是走内核协议栈;LoxiLB 换了个思路,把转发逻辑放进 eBPF,由 kube-loxilb 监听 Service 和 EndpointSlice,把规则下发给 LoxiLB。

这篇在单节点 k3s 上把 in-cluster 模式跑了一遍:VIP 分配、NodePort 与 PodIP 两种端点模式、轮询分发、端点伸缩,最后用 BIRD 做 BGP 对端,验证 VIP 前缀的通告和撤销。

实测范围

实测:k3s v1.32.3 单节点、in-cluster 模式、LoxiLB 0.9.8.8、kube-loxilb(2026-11-16 的 latest 镜像)、LoadBalancer VIP、NodePort 后端 + onearm、PodIP 后端 + default、轮询分发、端点伸缩、BGP 通告与撤销、eBPF tc 程序挂载。

未实测:External 模式、多节点 HA、BFD、DSR 模式、VyOS 实际对接、主动探测的故障注入。PodIP 后端配 onearm/fullnat 在本次单节点环境里外部访问失败,原因未定位,文中如实记录。

不用云厂商的托管 LB,通常会遇到三个问题:

  • 没有外部 IP:type: LoadBalancer 的 Service 一直停在 Pending,只能退化成 NodePort。
  • VIP 不可达:即使分配了地址,上游网络不知道这个地址在哪,需要 ARP 或 BGP 把它通告出去。
  • 组件太多:MetalLB 管 VIP,kube-proxy 管转发,再做健康检查还要加一层,排障时要在几个组件之间对日志。

LoxiLB 把这些收进一个二进制:eBPF 数据面负责 NAT 和调度,内置 goBGP 负责路由通告,kube-loxilb 负责把 Kubernetes 的 Service 翻译成 LoxiLB 规则。

层面 组件 职责
数据面 eBPF 程序 连接跟踪、NAT、端点选择、会话保持、健康探测
控制面 LoxiLB 进程 装载 eBPF 规则,维护会话表,内置 goBGP,暴露 REST API(11111 端口)
K8s 集成 kube-loxilb 监听 Service/EndpointSlice,做 IPAM 和策略计算,通过 REST API 下发规则

这次部署在 k3s 的日志里看到的是 tc: bpf attach OK for ens18,也就是 eBPF 程序挂在 tc hook 上,不是 XDP。具体挂载点取决于版本和部署模式,部署后看日志确认最稳。

从创建 Service 到数据包转发,链路大致是:

sequenceDiagram
    participant User as kubectl
    participant API as K8s API Server
    participant KL as kube-loxilb
    participant LB as LoxiLB 控制面
    participant DP as eBPF 数据面
    participant BGP as goBGP
    participant Peer as BGP 对端

    User->>API: 创建 Service(type=LoadBalancer)<br/>loadBalancerClass: loxilb.io/loxilb
    API-->>KL: Watch Service / EndpointSlice
    KL->>KL: IPAM 分配 VIP<br/>解析 lbmode、usepodnetwork 等注解
    KL->>LB: REST API 下发 LB 规则
    LB->>DP: 更新 BPF Map
    LB->>BGP: 通告 VIP 前缀
    BGP->>Peer: BGP UPDATE(VIP/32)
    Note over DP: 数据包进入 ens18<br/>查 BPF Map 后 DNAT<br/>转发到 NodePort 或 PodIP
实验环境
  • Debian 12 虚拟机,4 vCPU / 5.8 GiB 内存,内核 6.1.0-23-cloud-amd64
  • k3s v1.32.3+k3s1,单节点,containerd 2.0.4
  • LoxiLB v0.9.8.8,kube-loxilb 使用 2026-11-16 的 latest 镜像
  • VIP:10.31.0.244,和节点 10.31.0.144/24 同网段
  • 测试负载:ghcr.io/loxilb-io/nginx:stable,3 个副本

选择 in-cluster 模式,原因是实验环境只有一台机器。LoxiLB 以 DaemonSet 跑在节点上,kube-loxilb 不配 --loxiURL,靠 headless Service 自动发现 LoxiLB。External 模式(LoxiLB 用 Docker 跑在集群外、kube-loxilb 通过 --loxiURL 连接)本次没有实测,命令放在生产化一节作为参考。

VIP 选同网段的空闲地址,部署前先确认没有被占用:

for ip in 10.31.0.244 10.31.0.245 10.31.0.246; do
  ping -c 1 -W 1 "$ip" >/dev/null 2>&1 && echo "$ip used" || echo "$ip free"
done

k3s 已经装好,直接应用 LoxiLB 和 kube-loxilb 的清单。官方 k3s-incluster 示例里的 LoxiLB DaemonSet 长这样,关键参数都保留了:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: loxilb-lb
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: loxilb-app
  template:
    metadata:
      labels:
        app: loxilb-app
    spec:
      hostNetwork: true
      hostPID: true
      dnsPolicy: ClusterFirstWithHostNet
      initContainers:
        - name: mkllb-cgroup
          # 准备 cgroup,略
      containers:
        - name: loxilb-app
          image: ghcr.io/loxilb-io/loxilb:v0.9.8.8
          imagePullPolicy: IfNotPresent
          command:
            - /root/loxilb-io/loxilb/loxilb
            - --bgp
            - --egr-hooks
            - --blacklist=cni[0-9a-z]|veth.|flannel.|cali.|tunl.|vxlan[.]calico|docker|br-
            - --localsockpolicy
          ports:
            - containerPort: 11111
            - containerPort: 179
            - containerPort: 50051
          securityContext:
            privileged: true
            capabilities:
              add: ["SYS_ADMIN"]

完整清单还包括 affinity、tolerations 和 volumes,见文末的官方 k3s in-cluster quick start;这里只摘和网络行为相关的部分。

参数说明:

参数 作用
--bgp 启用内置 goBGP,用于通告 VIP
--egr-hooks 允许同一节点上的 Pod 作为后端
--blacklist 不把 eBPF 程序挂到 CNI、Docker、veth 等接口上
--localsockpolicy 处理本机发起的连接,单节点测试时会影响本机访问 VIP 的行为

--blacklist 里额外加了 docker 和 br-,因为这台机器还跑着 Docker 服务,不希望 LoxiLB 去碰 Docker 网桥。官方示例只列了 CNI 相关接口,按环境补全就行。

kube-loxilb 的启动参数:

args:
  - --cidrPools=defaultPool=10.31.0.244/32
  - --setRoles=0.0.0.0
  - --monitor
参数 说明
--cidrPools VIP 池,这里只留一个地址
--setRoles 单节点仲裁,0.0.0.0 表示由 kube-loxilb 自己选主
--monitor 启用后端存活探测

应用后检查 Pod:

sudo k3s kubectl apply -f loxilb.yml
sudo k3s kubectl apply -f kube-loxilb.yml

sudo k3s kubectl -n kube-system get pods | grep -E 'loxilb|NAME'
# kube-loxilb-85c889d68c-kkjjq   1/1   Running   0   15s
# loxilb-lb-n4khk                1/1   Running   0   15s

如果 kube-loxilb 日志里出现 service cannot be added because there are no loxilb instances,先等几秒。kube-loxilb 启动时 LoxiLB 可能还没就绪,这条错误是发现阶段的正常重试,LoxiLB 的 headless Service 有端点后会自动恢复。

创建 3 个 nginx 副本,每个 Pod 把自己的主机名写进首页,方便看分发结果:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: tcp-onearm-test
spec:
  replicas: 3
  selector:
    matchLabels:
      what: tcp-onearm-test
  template:
    metadata:
      labels:
        what: tcp-onearm-test
    spec:
      containers:
        - name: nginx
          image: ghcr.io/loxilb-io/nginx:stable
          imagePullPolicy: IfNotPresent
          command: ["/bin/sh", "-c"]
          args:
            - echo "pod $HOSTNAME" > /usr/share/nginx/html/index.html && exec nginx -g 'daemon off;'
          ports:
            - containerPort: 80

Service 用官方示例的 onearm 模式,后端走 NodePort:

apiVersion: v1
kind: Service
metadata:
  name: tcp-lb-onearm
  annotations:
    loxilb.io/liveness: "yes"
    loxilb.io/lbmode: "onearm"
spec:
  externalTrafficPolicy: Local
  loadBalancerClass: loxilb.io/loxilb
  selector:
    what: tcp-onearm-test
  ports:
    - port: 56002
      targetPort: 80
      nodePort: 30001
  type: LoadBalancer

loadBalancerClass: loxilb.io/loxilb 是关键。加上这个字段后,Service 会交给 kube-loxilb 处理,不会再落到 k3s 自带的 Klipper 上;Traefik 自己的 Service 不受影响。

sudo k3s kubectl apply -f demo-onearm.yaml
sudo k3s kubectl get svc tcp-lb-onearm
# NAME            TYPE           CLUSTER-IP    EXTERNAL-IP       PORT(S)           AGE
# tcp-lb-onearm   LoadBalancer   10.43.57.16   llb-10.31.0.244   56002:30001/TCP   12s

EXTERNAL-IP 显示成 llb-10.31.0.244,实际 VIP 是后面的地址。从同网段的另一台机器访问:

for i in $(seq 1 12); do
  curl -s http://10.31.0.244:56002/
done | sort | uniq -c
#   3 pod tcp-onearm-test-558d88cd5d-5v7xc
#   4 pod tcp-onearm-test-558d88cd5d-87ntv
#   5 pod tcp-onearm-test-558d88cd5d-ftp47

三个 Pod 都分到了流量。LoxiLB 侧看到的端点不是 PodIP,而是节点的 NodePort:

POD=$(sudo k3s kubectl -n kube-system get pod -l app=loxilb-app -o jsonpath='{.items[0].metadata.name}')
sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- \
  loxicmd get lb -o wide
# 输出节选(省略 SEC IPS、MARK、COUNTERS 等列)
# | 10.31.0.244 | 56002 | tcp | default_tcp-lb-onearm:llb-inst0 | rr | onearm | 10.31.0.144 | 30001 | active |

这条路径里,LoxiLB 只把 VIP 流量送到 10.31.0.144:30001,Pod 之间的分发由 kube-proxy 完成。对单节点没问题,但多节点时 LoxiLB 无法直接感知 Pod 的分布。

如果希望 LoxiLB 直接按 Pod 分发,加 loxilb.io/usepodnetwork: "yes",端点会变成 PodIP + targetPort:

metadata:
  name: tcp-lb-podnet-default
  annotations:
    loxilb.io/liveness: "yes"
    loxilb.io/lbmode: "default"
    loxilb.io/usepodnetwork: "yes"
spec:
  externalTrafficPolicy: Local
  loadBalancerClass: loxilb.io/loxilb
  selector:
    what: tcp-onearm-test
  ports:
    - port: 56004
      targetPort: 80
      nodePort: 30003
  type: LoadBalancer
for i in $(seq 1 12); do
  curl -s http://10.31.0.244:56004/
done | sort | uniq -c
#   4 pod tcp-onearm-test-558d88cd5d-5v7xc
#   4 pod tcp-onearm-test-558d88cd5d-87ntv
#   4 pod tcp-onearm-test-558d88cd5d-ftp47

12 个请求正好 4/4/4。loxicmd get lb 里能看到三个 PodIP 端点:

sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- \
  loxicmd get lb -o wide
# 输出节选(省略部分列)
# | 10.31.0.244 | 56004 | tcp | default_tcp-lb-podnet-default:llb-inst0 | rr | default |
# |             |       |     |                                                 |    |         | 10.42.0.3 | 80 |
# |             |       |     |                                                 |    |         | 10.42.0.4 | 80 |
# |             |       |     |                                                 |    |         | 10.42.0.6 | 80 |

在 LoxiLB 所在节点上直接 curl 10.31.0.244:56004,返回的是 Go 默认的 404 page not found,不是 nginx 的页面。从现象看,是 --localsockpolicy 接管了本机发起的连接,单节点测试时本机访问 PodIP 后端会走本地 socket 策略。

换一台同网段的机器访问就正常。这个现象容易误判成 VIP 或规则没生效,排障时先区分“本机访问”和“外部访问”。

后端 lbmode 外部访问 说明
NodePort onearm 正常 官方示例,单节点可用
PodIP default 正常 12 个请求 4/4/4
PodIP onearm 失败 外部连接超时,原因未定位
PodIP fullnat 失败 外部连接超时,原因未定位

后两行不是配置写错:loxicmd get lb 里规则和端点都在,get ep 也显示 ok,但外部连接就是不通。单节点 + 本地 socket 策略可能是原因之一,本次没有继续深挖。生产环境如果要用 fullnat,建议先在多节点环境验证,或者直接走官方示例的 NodePort 后端。

loxilb.io/liveness: "yes" 会让 LoxiLB 对端点做 TCP/HTTP 探测。这里没有做主动故障注入,只验证了 EndpointSlice 变化时规则会不会跟着更新。

把副本从 3 缩到 2:

sudo k3s kubectl scale deploy tcp-onearm-test --replicas=2
sleep 8
sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- \
  loxicmd get ep
# 输出节选
# | 10.42.0.3   | ... | ok |
# | 10.42.0.4   | ... | ok |

10.42.0.2 从端点列表里消失。再扩回 3,新 Pod 10.42.0.6 会自动加回来。伸缩后端点列表在几秒内更新,本次没有测具体收敛时间。对 HTTP 短连接来说这个速度够用;长连接场景要考虑会话保持和客户端重连。LoxiLB 的 conntrack 在单实例上维护,跨实例故障切换时已有连接大概率会断,本次没有做故障切换测试。

VIP 只在 LoxiLB 节点本地有效,上游路由器不知道 10.31.0.244 在哪。生产环境一般用 BGP 把 VIP 前缀通告给核心路由器,LoxiLB 内置 goBGP,kube-loxilb 负责配置。

kube-loxilb 在原有参数基础上加三个 BGP 参数:

args:
  - --cidrPools=defaultPool=10.31.0.244/32
  - --setRoles=0.0.0.0
  - --monitor
  - --setBGP=65100
  - --extBGPPeers=192.168.200.2:65000
  - --listenBGPPort=1791
参数 说明
--setBGP=65100 LoxiLB 的 AS 号
--extBGPPeers 对端地址和 AS 号,格式 IP:AS
--listenBGPPort=1791 LoxiLB 的 BGP 监听端口;对端占用 179 时改这里

实验环境没有 VyOS,用 BIRD 2.0.12 在一个 network namespace 里扮演上游路由器。veth 用独立的 /30 网段,不要和节点所在的 /24 重叠,否则内核会优先走 veth 的路由,把整个网段的回包黑洞掉。这个问题在调试时真实踩到过,VM 直接失联,只能从 PVE 的 guest agent 进去删路由。

sudo ip netns add bgpns
sudo ip link add veth-bgp type veth peer name veth-bgp-ns
sudo ip link set veth-bgp-ns netns bgpns
sudo ip addr add 192.168.200.1/30 dev veth-bgp
sudo ip link set veth-bgp up
sudo ip netns exec bgpns ip addr add 192.168.200.2/30 dev veth-bgp-ns
sudo ip netns exec bgpns ip link set veth-bgp-ns up
sudo ip netns exec bgpns ip link set lo up
sudo ip netns exec bgpns ip route add 10.31.0.144/32 via 192.168.200.1

BIRD 配置:

router id 192.168.200.2;
protocol device {}
protocol bgp loxilb {
  local as 65000;
  neighbor 10.31.0.144 as 65100 port 1791;
  multihop 2;
  ipv4 {
    import all;
    export none;
  };
}

启动 BIRD,让它只在 netns 里监听:

sudo ip netns exec bgpns bird -c /etc/bird/bgpns.conf \
  -s /run/bird-bgpns.ctl -P /run/bird-bgpns.pid -u root

先看 BGP 邻居:

sudo ip netns exec bgpns birdc -s /run/bird-bgpns.ctl \
  show protocols loxilb
# Name       Proto      Table      State  Since         Info
# loxilb     BGP        ---        up     01:25:08.703  Established

再看 LoxiLB 侧的邻居:

POD=$(sudo k3s kubectl -n kube-system get pod -l app=loxilb-app -o jsonpath='{.items[0].metadata.name}')
sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- loxicmd get bgpneigh
# |     PEER      |  AS   | UP/DOWN  |    STATE    |
# | 192.168.200.2 | 65000 | 00:04:18 | ESTABLISHED |

BIRD 收到的路由:

sudo ip netns exec bgpns birdc -s /run/bird-bgpns.ctl \
  show route
# 10.31.0.244/32  unreachable [loxilb 01:25:48.126 from 10.31.0.144] * (100) [i]

unreachable 是因为 BIRD 没有解析下一跳的路由,不影响 BGP 通告本身。show route all 里能看到 BGP.as_path: 65100 和 BGP.next_hop: 10.31.0.144。

BGP 邻居、路由与 Service VIP
kubectl 看到 VIP,loxicmd 显示 BGP 邻居 ESTABLISHED,BIRD 收到 10.31.0.244/32

撤销测试:把所有使用该 VIP 的 Service 删掉,BIRD 的路由表变空;重新 apply 后路由回来。

sudo k3s kubectl delete svc tcp-lb-onearm tcp-lb-podnet \
  tcp-lb-podnet-default tcp-lb-podnet-fullnat
sleep 6
sudo ip netns exec bgpns birdc -s /run/bird-bgpns.ctl \
  show route
# BIRD 2.0.12 ready.
# Table master4:

sudo k3s kubectl apply -f demo-onearm.yaml
sudo k3s kubectl apply -f demo-podnet-modes.yaml
sleep 8
sudo ip netns exec bgpns birdc -s /run/bird-bgpns.ctl \
  show route
# 10.31.0.244/32  unreachable [loxilb ...] * (100) [i]

这说明 VIP 前缀是跟着 Service 生命周期通告和撤销的,不是静态写死。

BFD 没有实测
LoxiLB 内置 goBGP 支持 BFD,官方文档有 loxicmd create bfd 的用法。本次 BGP 用的是多跳会话,BFD 的单跳和多跳模式需要对齐,没有继续做。生产环境用 BFD 前,建议先在测试环境确认 loxicmd get bfd 和路由器侧的会话状态。

下面是 VyOS 侧的配置,来自官方文档和常见实践,本次没有实际对接,只作为参考:

configure
set protocols bgp system-as '65000'
set protocols bgp parameters router-id '10.31.0.1'
set protocols bgp neighbor 10.31.0.144 remote-as '65100'
set protocols bgp neighbor 10.31.0.144 description 'LoxiLB'
set protocols bgp neighbor 10.31.0.144 address-family ipv4-unicast
set protocols bgp address-family ipv4-unicast maximum-paths ebgp '2'
commit
save

实际部署时还要加 prefix-list,只接受 VIP 网段,避免 LoxiLB 把其他路由泄漏进来。

LoxiLB 支持多种 NAT 模式,选错模式是 VIP 不通的常见原因。下面这张表是模式说明,最后一列标注本次是否实测:

模式 源地址改写 目标地址改写 本次实测
default 不改写 VIP -> PodIP PodIP 后端可用
onearm 改为 LoxiLB 接口 IP VIP -> PodIP / NodePort NodePort 后端可用
fullnat 改为 VIP VIP -> PodIP 未跑通
dsr 不改写 通过封装传递 未测
fullproxy L7 代理 L7 代理 未测

选型建议:

  • 同网段、希望保留客户端源 IP:default + PodIP 后端
  • 单节点或后端用 NodePort:onearm
  • 跨网段、回程路由不好控制:fullnat,但先在目标环境验证
  • 大带宽、回程不想经过 LB:dsr,本次没有环境验证
以下内容未实测
这一节是部署建议,不是本次实验的结论。多节点 HA、External 模式、BFD、VyOS 对接都没有在实验环境验证。

多节点 HA:至少两个 LoxiLB 实例,配合 BGP ECMP 和 BFD。LoxiLB 的 conntrack 不跨实例同步,故障切换后已有连接会断,HTTP 短连接影响不大,长连接需要客户端重连。

External 模式:LoxiLB 用 Docker 跑在集群外的节点上,kube-loxilb 通过 --loxiURL 连接。官方示例:

docker run -d --restart unless-stopped \
  --name loxilb \
  --privileged --net=host \
  ghcr.io/loxilb-io/loxilb:v0.9.8.8 \
  --bgp --egr-hooks

kube-loxilb 的 --loxiURL 指向 LoxiLB 的 11111 端口。External 模式适合把 LB 节点放在 DMZ,本次没有验证。

安全:LoxiLB 的 REST API 默认没有认证,11111 端口只允许 kube-loxilb 所在网段访问。BGP 对端建议配 MD5 和 TTL Security,prefix-list 只放行 VIP 网段。

监控:官方文档提到 LoxiLB 暴露 Prometheus 指标,路径是 /netlox/v1/config/metrics,本次没有接入 Prometheus 验证。重点看 LB 规则数、端点健康、BGP 邻居状态。Blackbox Exporter 对 VIP 做主动拨测也可以补上。

1. kube-loxilb 报 no loxilb instances

启动初期正常,等 LoxiLB Pod 就绪后会自动恢复。如果一直不恢复,检查 loxilb-lb-service 的 Endpoints 是否有地址,以及 kube-loxilb 能不能访问 10.31.0.144:11111。

2. 删除 loxilb Pod 后新 Pod CrashLoopBackOff

LoxiLB 的 DaemonSet 开了 hostPID: true,删 Pod 时 gobgpd 可能作为孤儿进程留在宿主机上,继续占用 1791 和 50052 端口,新 Pod 启动时冲突。排查:

pgrep -a gobgpd
# 356359 gobgpd --api-hosts=127.0.0.1:50052
sudo kill 356359
sudo k3s kubectl -n kube-system delete pod -l app=loxilb-app

杀掉孤儿进程后新 Pod 正常启动。手动删 LoxiLB Pod 前先看一眼 pgrep -a gobgpd,能省不少时间。

3. VIP 分配了但外部访问不通

按顺序检查:

POD=$(sudo k3s kubectl -n kube-system get pod -l app=loxilb-app -o jsonpath='{.items[0].metadata.name}')

# 规则是否下发
sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- \
  loxicmd get lb -o wide

# 端点是否健康
sudo k3s kubectl -n kube-system exec "$POD" -c loxilb-app -- \
  loxicmd get ep

# 服务状态
sudo k3s kubectl get svc <name>

# BGP 对端是否收到路由
sudo ip netns exec bgpns birdc -s /run/bird-bgpns.ctl \
  show route

# 抓包
sudo tcpdump -i ens18 host 10.31.0.244 -nn -c 20

常见原因:loadBalancerClass 拼错、VIP 池耗尽、BGP 没建立、lbmode 和网络拓扑不匹配、端点被标记为 inactive。

4. 本机 curl VIP 返回 404

从现象看,是 --localsockpolicy 接管了本机连接,PodIP 后端在本机访问时可能返回 404。换外部机器验证,或者用 NodePort 后端做本机测试。

5. 部署后整个网段失联

如果给 veth 或 dummy 接口配了和节点相同网段的地址,内核可能优先走新接口的路由,把回包黑洞掉。检查 ip route 里有没有和主网卡同网段、metric 更低的条目。调试 BGP 时 veth 用独立的 /30 网段,能避开这个问题。