pkg/loadbalancer

Active contributors: brb, joamaki, joestringer, julianwiedmann, borkmann

Purpose

pkg/loadbalancer/ is the userspace control of Cilium's BPF load balancer. It models services, frontends, and backends; reconciles their state into BPF maps; and integrates with kube-proxy replacement, socket LB, XDP LB, and LB-IPAM.

For the feature surface see features/load-balancing.md. This page is about the package.

Layout

pkg/loadbalancer/
├── service.go              # service abstraction
├── manager.go              # service manager Hive cell
├── frontend.go             # frontends + backends
├── backendmap/             # backend slot helpers
├── reconciler/             # statedb table -> lbmap reconciler
├── benchmark/              # micro-benchmarks
├── cells.go                # Hive wiring
└── ...

pkg/maps/lbmap/             # actual BPF maps (services, backends, affinity, maglev)
pkg/maglev/                 # consistent hashing
pkg/socketlb/               # socket LB program lifecycle
pkg/lbipam/                 # LB-IPAM client (agent-side; the controller is in operator/)
operator/pkg/lbipam/        # LB-IPAM controller

Key abstractions

Type	File	Role
Service	pkg/loadbalancer/service.go	A logical service (frontend + backends + flags).
Frontend	pkg/loadbalancer/frontend.go	The (vip, port, proto) tuple advertised to the dataplane.
Backend	pkg/loadbalancer/frontend.go	A reachable target with its addr, port, state.
Manager	pkg/loadbalancer/manager.go	Cell that mediates between K8s watchers and the lb tables.
Reconciler	pkg/loadbalancer/reconciler/	Watches StateDB tables and writes pkg/maps/lbmap/.
MaglevTable	pkg/maglev/maglev.go	Consistent hashing table per service.

StateDB tables

The current implementation uses StateDB tables to hold service state:

• A frontends table keyed by (IP, port, proto).
• A backends table keyed by (svcID, slot).
• A health table for backend liveness from kubelet readiness.

Reconcilers diff the tables against the BPF maps and apply the minimum number of updates per transaction. This avoids blackholing during fan-out updates and gives consistent semantics across multiple writers.

Modes

Mode	Behaviour
Disabled	Cilium does not handle services; an external kube-proxy still runs. Rare in production.
Probe	Default detection; falls back to disabled if the kernel lacks features.
Strict	Cilium handles all service traffic.
Partial	Cilium handles some Service types only (e.g., ClusterIP, NodePort) while leaving others to kube-proxy.

pkg/kpr/ (kube-proxy replacement) tracks the negotiated mode at runtime and exposes it via the agent REST API.

Maglev

Maglev provides consistent hashing for backend selection. pkg/maglev/ builds the lookup table per service; the dataplane uses the table to pick a backend without state.

Integration points

• K8s watchers: services and EndpointSlices feed the manager.
• CiliumLoadBalancerIPPool / LB-IPAM: allocate external IPs for LoadBalancer services.
• BGP: advertises VIPs to upstream routers (pkg/bgp/).
• L2 announcer: announces VIPs via ARP/NDP (pkg/l2announcer/).
• Socket LB: programs run via pkg/socketlb/.

Entry points for modification

• New service annotation: parse it in the K8s watcher under pkg/k8s/watchers/service.go and propagate via the StateDB tables.
• New affinity mode: extend pkg/loadbalancer/service.go and pkg/maps/lbmap/.
• New algorithm (e.g., a different consistent-hash variant): extend pkg/maglev/.

Key source files

File	Purpose
pkg/loadbalancer/service.go	Service type.
pkg/loadbalancer/manager.go	Manager cell.
pkg/loadbalancer/reconciler/	Reconciliation.
pkg/maps/lbmap/lbmap.go	BPF map.
pkg/maglev/maglev.go	Maglev hashing.
operator/pkg/lbipam/	LB-IPAM.