upstream-fair

Least-busy load balancing for upstreams

dynamic moduleBSD-2-Clausesource

Overview

nginx-upstream-fair replaces round-robin balancing with a least-busy algorithm. It tracks how many requests each backend is currently handling and sends new requests to the server with the least outstanding work.

This suits backends that handle one request at a time or have uneven response times, where round-robin would queue requests behind a slow server. Peer state is kept in shared memory, so all worker processes share the same view of backend load.

The module was written by Grzegorz Nosek, sponsored by EngineYard. The original repository at gnosek/nginx-upstream-fair is unmaintained; this fork carries patches for current nginx releases and dynamic module builds.

Key directives

fairEnables the fair scheduler for an upstream block, picking the backend with the fewest requests in flight.

fair no_rrDrops the round-robin warmup behavior and always picks by load, useful when backends must not receive concurrent requests.

fair weight_mode=idleTreats server weights as concurrency limits, marking a backend busy once it reaches its weight in active requests.

fair weight_mode=peakEnforces server weights as hard caps and returns errors rather than exceeding them, so max_fails and fail_timeout apply.

upstream_fair_shm_sizeSets the size of the shared memory segment that stores peer state across worker processes.

Example

nginx.conf

load_module modules/ngx_http_upstream_fair_module.so; http { upstream backend { fair; server 127.0.0.1:5000; server 127.0.0.1:5001; server 127.0.0.1:5002; } server { location / { proxy_pass http://backend; } } }

Availability

Ships as a dynamic module in libnginx-mod-http-upstream-fair, installed automatically with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.