Skip to content

upstream: Upstream connection load balancing and failover module for nginx-module-lua


If you haven't set up RPM repository subscription, sign up. Then you can proceed with the following steps.

CentOS/RHEL 7 or Amazon Linux 2

yum -y install
yum -y install lua-resty-upstream

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

yum -y install
yum -y install lua5.1-resty-upstream

To use this Lua library with NGINX, ensure that nginx-module-lua is installed.

This document describes lua-resty-upstream v0.10 released on Dec 19 2019.

Upstream connection load balancing and failover module


Experimental, API may change without warning.

Requires ngx_lua > 0.9.5


Create a lua shared dictionary. Define your upstream pools and hosts in init_by_lua, this will be saved into the shared dictionary.

Use the connect method to return a connected tcp socket.

Alternatively pass in a resty module (e.g lua-resty-redis or lua-resty-http) that implements connect() and set_timeout().

Call process_failed_hosts to handle failed hosts without blocking current request.

Use resty.upstream.api to modify upstream configuration during init or runtime, this is recommended!

resty.upstream.http wraps the lua-resty-http from @pintsized.

It allows for failover based on HTTP status codes as well as socket connection status.

lua_shared_dict my_upstream_dict 1m;
init_by_lua '
    upstream_socket  = require("resty.upstream.socket")
    upstream_api = require("resty.upstream.api")

    upstream, configured = upstream_socket:new("my_upstream_dict")
    if not upstream then
    api = upstream_api:new(upstream)

    if not configured then -- Only reconfigure on start, shared mem persists across a HUP
        api:create_pool({id = "primary", timeout = 100})
        api:set_priority("primary", 0)
        api:set_method("primary", "round_robin")
        api:add_host("primary", { id="a", host = "", port = "80", weight = 10 })
        api:add_host("primary", { id="b", host = "", port = "81",  weight = 10 })

        api:create_pool({id = "dr"})
        api:set_priority("dr", 10)
        api:add_host("dr", { host = "", port = "82", weight = 5 })
        api:add_host("dr", { host = "", port = "83", weight = 10 })

        api:create_pool({id = "test", priority = 5})
        api:add_host("primary", { id="c", host = "", port = "82", weight = 10 })
        api:add_host("primary", { id="d", host = "", port = "83", weight = 10 })

init_worker_by_lua 'upstream:init_background_thread()';

server {

    location / {
        content_by_lua '
            local sock, err = upstream:connect()




syntax: upstream, configured = upstream_socket:new(dictionary, id?)

Returns a new upstream object using the provided dictionary name. When called in init_by_lua returns an additional variable if the dictionary already contains configuration. Takes an optional id parameter, this must be unique if multiple instances of upstream.socket are using the same dictionary.


syntax: ok, err = upstream:init_background_thread()

Initialises the background thread, should be called in init_worker_by_lua


syntax: ok, err = upstream:connect(client?, key?)

Attempts to connect to a host in the defined pools in priority order using the selected load balancing method. Returns a connected socket and a table containing the connected host, poolid and pool or nil and an error message.

When passed a socket or resty module it will return the same object after successful connection or nil.

Additionally, hash methods may take an optional key to define how to hash the connection to determine the host. By default ngx.var.remote_addr is used. This value is ignored when the pool's method is round robin.

resty_redis = require('resty.redis')
local redis =

local key = ngx.req.get_headers()["X-Forwarded-For"]

local redis, err = upstream:connect(redis, key)

if not redis then
    ngx.log(ngx.ERR, err)
    ngx.status = 500
    return ngx.exit(ngx.status)

ngx.log(, 'Connected to ' .. .. ':' ..
local ok, err = redis:get('key')


syntax: ok, err = upstream:process_failed_hosts()

Processes any failed or recovered hosts from the current request. Spawns an immediate callback via, does not block current request.


syntax: pools = usptream:get_pools()

Returns a table containing the current pool and host configuration. e.g.

    primary = {
        up = true,
        method = 'round_robin',
        timeout = 100,
        priority = 0,
        hosts = {
            web01 = {
                host = "",
                weight = 10,
                port = "80",
                lastfail = 0,
                failcount = 0,
                up = true,
                healthcheck = true
            web02 = {
                host = "",
                weight = 10,
                port = "80",
                lastfail = 0,
                failcount = 0,
                up = true,
                healthcheck = { interval = 30, path = '/check' }
    secondary = {
        up = true,
        method = 'round_robin',
        timeout = 2000,
        priority = 10,
        hosts = {
            dr01 = {
                host = "",
                weight = 10,
                port = "80",
                lastfail = 0,
                failcount = 0,
                up = true



syntax: ok, err = upstream:save_pools(pools)

Saves a table of pools to the shared dictionary, pools must be in the same format as returned from get_pools


syntax: ok, err = upstream:sort_pools(pools)

Generates a priority order in the shared dictionary based on the table of pools provided


syntax: ok, err = upstream:bind(event, func)

Bind a function to be called when events occur. func should expect 1 argument containing event data.

Returns true on a successful bind or nil and an error message on failure.

local function host_down_handler(event)
    ngx.log(ngx.ERR, "Host: ",, ":",, " in pool '",,'" is down!')
local ok, err = upstream:bind('host_down', host_down_handler)

Event: host_up

Fired when a host changes status from down to up. Event data is a table containing the affected host and pool.

Event: host_down

Fired when a host changes status from up to down. Event data is a table containing the affected host and pool.


These functions allow you to dynamically reconfigure upstream pools and hosts


syntax: api, err = upstream_api:new(upstream)

Returns a new api object using the provided upstream object.


syntax: ok, err = api:set_method(poolid, method)

Sets the load balancing method for the specified pool. Currently randomised round robin and hashing methods are supported.


syntax: ok, err = api:create_pool(pool)

Creates a new pool from a table of options, pool must contain at least 1 key id which must be unique within the current upstream object.

Other valid options are

  • method Balancing method
  • timeout Connection timeout in ms
  • priority Higher priority pools are used later
  • read_timeout
  • keepalive_timeout
  • keepalive_pool
  • status_codes See status_codes

Hosts cannot be defined at this point.

Note: IDs are converted to a string by this function

Default pool values

{ method = 'round_robin', timeout = 2000, priority = 0 }


syntax: ok, err = api:set_priority(poolid, priority)

Priority must be a number, returns nil on error.


syntax: ok, err = api:add_host(poolid, host)

Takes a pool ID and a table of options, host must contain at least host. If the host ID is not specified it will be a numeric index based on the number of hosts in the pool.

Note: IDs are converted to a string by this function


{ host = '', port = 80, weight = 0}


syntax: ok, err = api:remove_host(poolid, host)

Takes a poolid and a hostid to remove from the pool


syntax: ok,err = api:down_host(poolid, host)

Manually marks a host as down, this host will not be revived automatically.


syntax: ok,err = api:up_host(poolid, host)

Manually restores a dead host to the pool


Functions for making http requests to upstream hosts.


This pool option is an array of status codes that indicate a failed request. Defaults to none.

The x character masks a digit

    ['5xx'] = true, -- Matches 500, 503, 524
    ['400'] = true  -- Matches only 400


syntax: httpc, err = upstream_http:new(upstream, ssl_opts?)

Returns a new http upstream object using the provided upstream object.

ssl_opts is an optional table for configuring SSL support. * ssl set to true to enable SSL Handshaking, default false * ssl_verify set to false to disable SSL certificate verification, default true * sni_host a string to use as the sni hostname, default is the request's Host header

lua https_upstream = Upstream_HTTP:new(upstream_ssl, { ssl = true, ssl_verify = true, sni_host = "" })


syntax: ok, err = upstream_http:init_background_thread()

Initialises the background thread, should be called in init_worker_by_lua.

Do not call the init_background_thread method in upstream.socket if using the upstream.http background thread


syntax: res, err_or_conn_info, status? = upstream_api:request(params)

Takes the same parameters as lua-resty-http's request method.

On a successful request returns the lua-resty-http object and a table containing the connected host and pool.

If the request failed returns nil, the error and a suggested http status code

local ok, err, status = upstream_http:request({
        path = "/helloworld",
        headers = {
            ["Host"] = "",
if not ok then
    ngx.status = status
    local host =
    local pool = err.pool


syntax: ok, err = upstream_http:set_keepalive()

Passes the keepalive timeout / pool from the pool configuration through to the lua-resty-http set_keepalive method.


syntax: ok, err = upstream_http:get_reused_times()

Passes through to the lua-resty-http get_reused_times method.


syntax: ok, err = upstream_http:close()

Passes through to the lua-resty-http close method.

HTTP Healthchecks

Active background healthchecks can be enabled by adding the healthcheck parameter to a host.

A value of true will enable the default check, a GET request for /.

The healthcheck parameter can also be a table of parameters valid for lua-resty-http's request method.

With a few additional parameters

  • interval to set the time between healthchecks, in seconds. Must be >= 10s. Defaults to 60s
  • timeout sets the connect timeout for healthchecks. Defaults to pool setting.
  • read_timeout sets the read timeout for healthchecks. Defaults to pool setting.
  • status_codes a table of invalid response status codes. Defaults to pool setting.

Failure for the background check is according to the same parameters as for a frontend request, unless overriden explicitly.

-- Custom check parameters
api:add_host("primary", {
     host =,
     port = 80,
     healthcheck = {
        interval = 30, -- check every 30s
        timeout      = (5*1000), -- 5s connect timeout
        read_timeout = (15*1000), -- 15s connect timeout
        status_codes = {["5xx"] = true, ["403"] = true}, -- 5xx and 403 responses are a fail
        -- resty-http params
        path = "/check",
        headers = {
            ["Host"] = "",
            ["Accept-Encoding"] = "gzip"

-- Default check parameters
api:add_host("primary", {host =, port = 80, healthcheck = true})


You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-upstream.