/lua-dynamic-upstream

Nginx C module to expose Lua API to ngx_lua for Nginx upstreams

Primary LanguageC

lua-dynamic-upstream

lua_dynamic_upstream - Nginx C module to expose Lua API to ngx_lua for Nginx upstreams

Requirements

  • Requires the zone directive in the upstream context.
  • Requires the lua-nginx-module or OpenResty.

Compatibility

The following versions of Nginx should work with this module:

  • 1.17.x
  • 1.16.x
  • 1.15.x
  • 1.14.x
  • 1.13.x
  • 1.12.x
  • 1.11.x
  • 1.10.x
  • 1.9.x

Status

This module is production ready.

Load balancing methods:

  • round-robin
  • ip-hash
  • hash
  • hash consistent
  • least_conn
  • least_time
  • random
  • queue

Installation

  1. Grab the nginx source code from nginx.org.
  2. then grab the source code of the ngx_lua as well as its dependencies like LuaJIT.
  3. and finally build the source with this module:
curl -fSL http://nginx.org/download/nginx-1.16.0.tar.gz | tar zx
cd nginx-1.16.0/

# assuming your luajit is installed to /opt/luajit:
export LUAJIT_LIB=/opt/luajit/lib

# assuming you are using LuaJIT v2.1:
export LUAJIT_INC=/opt/luajit/include/luajit-2.1

# Here we assume you would install you nginx under /opt/nginx/.
./configure --prefix=/opt/nginx \
    --with-ld-opt="-Wl,-rpath,$LUAJIT_LIB" \
    --add-module=/path/to/lua-nginx-module \
    --add-module=/path/to/lua-dynamic-upstream

make -j2
make install

Functions

  • list_zones
  • describe_zone
  • add_peer
  • remove_peer
  • set_peer_down

list_zones

Return one array of all upstream zone names.

Lua arguments:

No arguments.

ngx.dynamic.list_zones()

Example:

upstream foo {
    zone dynamic_foo 32k;

   server 127.0.0.1:8030;
}

upstream bar {
    zone dynamic_bar 32k;

   server 127.0.0.1:8031;
}

server {
    listen 80;

    location = /dynamic/list {
        default_type text/plain;
        content_by_lua '
            local dynamic = require "ngx.dynamic"
            local zones, err = dynamic.list_zones()
            if not zones then
                ngx.say("unable to list upstream zone names: " .. err)
            else
                ngx.say("Upstream zone names:")
                for i, z in ipairs(zones) do
                    ngx.say("    ", z)
                end
            end
        ';
    }
}

describe_zone

Return one array of object for all peers in upstream zone.

Return peer informations:

  • current_weight
  • effective_weight
  • fail_timeout
  • fails
  • max_fails
  • name - Socket address for the current peer.
  • weight
  • accessed - Timestamp for the last access (in seconds since the Epoch).
  • checked - Timestamp for the last check (in seconds since the Epoch).
  • down - Holds true if the peer has been marked as "down", otherwise this key is not present.
  • conns - Number of active connections to the peer.

Lua arguments:

Required one argument:

  • upstream zone name
ngx.dynamic.describe_zone(zone)

Example:

upstream foo {
    zone dynamic_foo 32k;

   server 127.0.0.1:8030;
   server 127.0.0.1:8031;
}

server {
    listen 80;

    location = /dynamic/describe {
        default_type text/plain;
        content_by_lua '
            local dynamic = require "ngx.dynamic"
            local zones, err = dynamic.describe_zone("dynamic_foo")
            if not zones then
                ngx.say("unable to describe upstream zone: " .. err)
            else
                for i, zone in ipairs(zones) do
                    ngx.say("Peer")
                    for k, v in pairs(zone) do
                        ngx.say("    ",k, " => ", v)
                    end
                end
            end
        ';
    }
}

add_peer

Add new peer in upstream zone.

Lua arguments:

Required six arguments:

  • upstream zone name
  • ip:port
  • weight
  • max_fails
  • fail_timeout
  • down
    • true - Offline
    • nil - Online
ngx.dynamic.add_peer(zone, server, weight, max_fails, fail_timeout, down)

Example:

upstream foo {
    zone dynamic_foo 32k;

   server 127.0.0.1:8030;
}

server {
    listen 80;

    location = /dynamic/add {
        default_type text/plain;
        content_by_lua '
            local dynamic = require "ngx.dynamic"
            local ok, err = dynamic.add_peer("dynamic_foo", "127.0.0.1:8031", 1, 1, 10, nil)
            if not ok then
                ngx.say("unable to add peer: " .. err)
            else
                ngx.say("success to add peer")
            end
        ';
    }
}

remove_peer

Remove peer in upstream zone.

Lua arguments:

Required two arguments:

  • upstream zone name
  • ip:port
ngx.dynamic.remove_peer(zone, server)

Example:

upstream foo {
    zone dynamic_foo 32k;

   server 127.0.0.1:8030;
   server 127.0.0.1:8031;
}

server {
    listen 80;

    location /dynamic/remove {
        default_type text/plain;
        content_by_lua '
            local dynamic = require "ngx.dynamic"
            local ok, err = dynamic.remove_peer("dynamic_foo", "127.0.0.1:8030")
            if not ok then
                ngx.say("unable to remove peer: " .. err)
            else
                ngx.say("success to remove peer")
            end
        ';
    }
}

set_peer_down

Set peer down or up.

Lua arguments:

Required three arguments:

  • upstream zone name
  • ip:port
  • down
    • true - Offline
    • nil - Online
ngx.dynamic.set_peer_down(zone, server, down)

Example:

upstream foo {
    zone dynamic_foo 32k;

   server 127.0.0.1:8030;
   server 127.0.0.1:8031;
}

server {
    listen 80;

    location /dynamic/down {
        default_type text/plain;
        content_by_lua '
            local dynamic = require "ngx.dynamic"
            local ok, err = dynamic.remove_peer("set_peer_down", "127.0.0.1:8031", true)
            if not ok then
                ngx.say("unable to set peer down: " .. err)
            else
                ngx.say("success to set peer down")
            end
        ';
    }
}

About

This module meets the needs of the lua-upstream-nginx-module module, building on it and also based on the ngx_dynamic_upstream module.

See Also