Load balancing

Active contributors: borkmann, brb, julianwiedmann, joamaki

Purpose

Cilium implements a full load balancer in eBPF, replacing kube-proxy and adding capabilities like XDP-accelerated north-south LB, Maglev consistent hashing, DSR, and a CRD-based LoadBalancer-IPAM (LB-IPAM). Service translation happens in two main places:

• East-west: socket-LB at connect() time (bpf/bpf_sock.c) — translates the service VIP to a backend before any packet leaves the source pod.
• North-south: per-packet LB in TC and XDP (bpf/lib/lb.h, bpf/bpf_xdp.c).

Directory layout

pkg/loadbalancer/
├── service.go                 # service abstraction
├── manager.go                 # service manager (Hive cell)
├── reconciler/                # statedb-based reconciler programming lb maps
├── ...
pkg/maps/lbmap/                # the actual BPF maps for service v4/v6/affinity/maglev
pkg/maglev/                    # Maglev consistent hashing
pkg/socketlb/                  # cgroup-attached socket LB program management
pkg/lbipam/                    # LB-IPAM controller (LoadBalancer service IP allocation)
pkg/lbipamconfig/              # LB-IPAM config
pkg/kpr/                       # kube-proxy replacement runtime decisions
operator/pkg/lbipam/           # operator-side LB-IPAM controller (the active one)

How service translation works

graph LR
    Pod[Source pod]
    Sock[bpf_sock.c<br/>socket LB at connect]
    LXC[bpf_lxc.c<br/>fallback per-packet]
    LB[lb maps<br/>service + backend slots]
    Maglev[maglev table]
    Backend[Backend pod]

    Pod -->|connect VIP| Sock
    Sock -->|lookup| LB
    LB -->|consistent hash if needed| Maglev
    Sock -->|rewrite to backend| Backend
    Pod -.->|fallback for sockets that bypass cgroup hook| LXC
    LXC -->|same lookup| LB

Service state is materialised in BPF maps (pkg/maps/lbmap/):

• cilium_lb_services_v2 — service VIP → service id.
• cilium_lb_backends — backend id → backend addr.
• cilium_lb_aff_match / cilium_lb_affinity — session affinity.
• cilium_lb_maglev — Maglev consistent-hash lookup tables.

A reconciler (pkg/loadbalancer/reconciler/) watches the StateDB service tables and writes the maps; updates are atomic at the slot level.

Modes and features

Feature	Helm value	What it does
kube-proxy replacement	kubeProxyReplacement	When true, Cilium handles all Service traffic; kube-proxy is no longer needed.
Socket LB	socketLB.enabled	TCP/UDP connect() redirected to backend; avoids per-packet NAT.
XDP LB	loadBalancer.acceleration	Service translation at XDP for line-rate north-south LB.
Maglev	loadBalancer.algorithm	Consistent hashing across backends.
DSR (Direct Server Return)	loadBalancer.mode	Returns traffic directly from backend to client, skipping the LB node on the return path.
LB-IPAM	lbIPAM	Allocates external IPs from CiliumLoadBalancerIPPool for LoadBalancer services.
L2 announcement	l2announcements	Announces LB IPs via gratuitous ARP/NDP.
BGP advertisement	bgpControlPlane.enabled	Announces LB IPs to upstream routers via BGP.

LB-IPAM

operator/pkg/lbipam/ watches CiliumLoadBalancerIPPool (CRD pkg/k8s/apis/cilium.io/v2alpha1/types_lb_ip_pool.go) and assigns IPs from the configured ranges to Service objects of type LoadBalancer. The IP appears in the service's status.loadBalancer.ingress[], and the agent then either:

• Announces it via L2 (gratuitous ARP through pkg/l2announcer/).
• Announces it via BGP (pkg/bgp/).

XDP fast path

bpf/bpf_xdp.c is loaded on the chosen physical NIC when loadBalancer.acceleration: native is set. It performs the same service lookup as the TC path but at XDP — before sk_buff allocation — yielding line-rate LB. SYN packets matching a service VIP are translated and re-injected; non-matching traffic is XDP_PASS-ed to the kernel for normal processing.

Health checks

Backend health checks are derived from the pod readiness signal in Kubernetes. There is no separate active health checker for east-west; for north-south, kubelet readiness is enough. Failed pods are removed from the backend slot map by the reconciler.

Integration points

• Endpoint manager: publishes new pods as backends.
• K8s watchers: pkg/k8s/watchers/service.go, pkg/k8s/watchers/endpointslices.go feed the service tables.
• BGP: advertises VIPs (pkg/bgp/).
• Datapath: pkg/datapath/orchestrator/ chooses which programs (XDP / TC) to attach.

Entry points for modification

• New LB algorithm: extend pkg/loadbalancer/manager.go and the lbmap layout.
• New service annotation: parse it in the K8s watcher and propagate via the StateDB tables.
• DSR refinements: bpf/lib/nat.h and bpf/lib/lb.h.

Key source files

File	Purpose
bpf/bpf_sock.c	Socket LB at connect().
bpf/bpf_xdp.c	XDP LB.
bpf/lib/lb.h	LB lookup helpers.
pkg/loadbalancer/manager.go	Service Hive cell.
pkg/loadbalancer/reconciler/	Map reconciler.
pkg/maps/lbmap/	BPF map definitions.
pkg/maglev/maglev.go	Maglev hashing.
operator/pkg/lbipam/	LB-IPAM controller.

See systems/datapath.md for the broader datapath context.