Load Balancer

Stratum ships an L4 load balancer (xdp_lb) designed to run in the eBPF data plane: it distributes TCP and UDP flows across a set of backends using a per-VIP algorithm, maintains a stateful connection table so established flows stay pinned to their backend, and performs health checks to take unhealthy backends out of rotation automatically.

Status: the xdp_lb fast-path program is compiled and verifier-clean, but its standalone datapath attach is not yet wired — this is a known, tracked limitation. The control surface (lb commands, VIP definitions, backend pools, health checks) works, but you should not rely on a fully-working in-kernel L4 load-balancing datapath in production yet. Plan for it as a forthcoming capability, not a shipped one.

On Gateway nodes, VIPs are intended to be reachable from outside the fabric (north-south). On Compute nodes, VIPs are internal — useful for service-mesh style load balancing between endpoints.

Creating a VIP

sudo cenvero-str-ctl lb create \
  --name web-lb \
  --vip 10.20.0.10:80 \
  --protocol tcp \
  --algorithm least-conn \
  --backends 10.20.0.50:80,10.20.0.51:80

List your VIPs:

cenvero-str-ctl lb list

NAME     VIP              PROTO  ALGORITHM    BACKENDS  HEALTHY
web-lb   10.20.0.10:80    tcp    least-conn   2         2/2

Show detail for one VIP, including per-backend connection counts:

cenvero-str-ctl lb show web-lb

Algorithms

Algorithm	Flag	Behaviour
Round-robin	`round-robin`	Distributes new connections evenly in turn. Good default for stateless services.
Least connections	`least-conn`	Sends each new connection to the backend with the fewest active connections. Handles variable-cost requests well.
Weighted round-robin	`weighted`	Like round-robin but each backend has a relative weight (see below). Use when backends have unequal capacity.
Source-hash persistence	`source-hash`	Hashes the client source IP to a backend. The same client always reaches the same backend as long as the backend is healthy — useful for session-affinity without shared state.

Setting weights

sudo cenvero-str-ctl lb create \
  --name api-lb \
  --vip 10.20.0.20:443 \
  --protocol tcp \
  --algorithm weighted \
  --backends "10.20.0.50:443:3,10.20.0.51:443:1"

The trailing :3 and :1 are relative weights — 10.20.0.50 receives three times the new connections of 10.20.0.51.

Health checks

The agent probes backends at a configurable interval. A backend that fails enough consecutive checks is marked unhealthy and removed from the connection pool. It re-enters the pool automatically when it passes a configurable number of consecutive checks.

Configure health checks when creating a VIP or with lb set-health:

sudo cenvero-str-ctl lb set-health web-lb \
  --type tcp \
  --interval 5s \
  --timeout 2s \
  --unhealthy-threshold 3 \
  --healthy-threshold 2

Flag	Description	Default
`--type`	`tcp` (connection probe) or `http` (expects a 2xx response)	`tcp`
`--interval`	Time between probes	`10s`
`--timeout`	Probe timeout	`3s`
`--unhealthy-threshold`	Consecutive failures before marking down	`3`
`--healthy-threshold`	Consecutive successes before marking up	`2`

For HTTP health checks, optionally specify the path and expected status:

sudo cenvero-str-ctl lb set-health api-lb \
  --type http \
  --path /healthz \
  --expect-status 200 \
  --interval 5s

Adding and removing backends live

Backend changes take effect immediately without dropping established connections. The connection table keeps existing flows on their current backend until the flow closes naturally.

# Add a backend
sudo cenvero-str-ctl lb add-backend web-lb --backend 10.20.0.52:80

# Remove a backend (graceful: existing flows finish, new flows skip it)
sudo cenvero-str-ctl lb remove-backend web-lb --backend 10.20.0.50:80

# Force-remove immediately (drops active flows on that backend)
sudo cenvero-str-ctl lb remove-backend web-lb --backend 10.20.0.50:80 --force

North-south VIPs on Gateway nodes

On a Gateway node, VIPs in the fabric subnet are reachable from outside the cluster automatically because the Gateway node announces those routes via BGP. If you want a VIP to have a publicly routable address, assign it from a prefix your BGP session announces:

sudo cenvero-str-ctl lb create \
  --name external-web \
  --vip 203.0.113.10:443 \
  --protocol tcp \
  --algorithm round-robin \
  --backends 10.20.0.50:443,10.20.0.51:443

See BGP Edge Routing for how prefixes are advertised.

Deleting a VIP

sudo cenvero-str-ctl lb delete web-lb

Active connections are torn down immediately. Drain traffic to backends first if zero disruption is required.