Algorithms
The routing algorithm is a rule that decides which backend gets the next request (Layer 7) or the next connection (Layer 4). Every algorithm only chooses among backends that pass their health check, and every algorithm respects each backend’s weight.
When to use each algorithm
If you’re not sure, keep Round robin.
Sticky sessions (the Sticky header name field, default X-User-ID) are saved with the load balancer but are not applied to traffic yet, so the API’s sticky_header doesn’t choose the backend either. Don’t rely on a client staying on one backend. Keep session data somewhere every backend can read, such as a database or a shared cache.
How it works
- The load balancer keeps a list of backends that currently pass their health check.
- It applies the weights: a backend with weight
200is chosen twice as often as one with weight100. - The algorithm picks one backend from that weighted list for the request or connection.
- If Automatic retries are on and the attempt fails with a
5xxresponse, a reset or a connection failure, the load balancer tries again, up to the number of Attempts you set.
Weights
Every backend has a Weight from 1 to 1000 (default 100). A backend’s share of traffic is its weight divided by the total of all healthy backends’ weights.
Common uses:
- Bigger servers get more traffic. Give a backend with twice the CPU twice the weight.
- Try a new version on a little traffic (a “canary”): weight
90on the current version and10on the new one. - Take a backend out gently before maintenance: lower its weight to
1with the API so it gets almost no new traffic, then remove it from the list.
If a backend fails its health check, its share is split among the others in proportion to their weights.
Before you begin
- A load balancer, or the details to create one. See Create a load balancer.
- To change the algorithm or weights later, an API token with
load-balancer.write. The portal can’t edit a load balancer.
Set the algorithm in the portal
Set the weights
In Backends, enter a Weight for each row. Leave all weights at 100 for an even split.
Choose the algorithm
Under Routing and health, choose a Routing algorithm: Round robin, Least request, Random or Consistent hash.
Change the algorithm or weights with the API
Send only the part you want to change. This request switches to least request:
To change weights, send the whole backend list with the new weights. Backends you leave out are removed.
For an L4 load balancer, use /networking/load-balancers/l4/LB-ID instead.
Verify
Send a batch of requests and count where they land. If each backend returns its own hostname (for example on a /whoami page), this shows the split:
With round robin and equal weights, the counts are about equal. With weights 90 and 10, about 18 of 20 go to the first backend. Small samples vary; use 100 or more requests for a clearer picture.
Limits
Retries and the request timeout apply to HTTP and HTTPS load balancers. A Layer 4 load balancer forwards the TCP connection as it is.
