~tomleb/nginx-stream-upstream-time-module

NGINX module to load balance based on specified interval
5e8b8340 — Tom Lebreux 1 year, 4 months ago
Fix commands[] coding style
1a34aa67 — Tom Lebreux 1 year, 4 months ago
Fix never unlocking peers mutex
4741257b — Tom Lebreux 1 year, 4 months ago
Add hour_clock= parameter

refs

master
browse  log 

clone

read-only
https://git.sr.ht/~tomleb/nginx-stream-upstream-time-module
read/write
git@git.sr.ht:~tomleb/nginx-stream-upstream-time-module

You can also use your local clone with git send-email.

#NGINX Time module

A module that load balancer stream to peers based on an interval.

#Configuration

Syntax: time [parameters]

Default: -

Context: upstream

Defines the load balancer method for the upstream block. This load balancer selects the server to proxy to based on the interval defined.

interval=string

sets the interval at which each server will be selected.

Default value is weekday.

With the value weekday, each server will be assigned a day of the week, and will load balance during that day of the week. The upstream block must have exactly 7 servers configured. Servers can be repeated.

With the value day, each server will be assigned a day in a month. Since not every month has equal length, some servers will work more than others. The upstream block must have exactly 31 servers configured. Servers can be repeated.

With the value minute, each server will be assigned a minute in the hour. The upstream block must have exactly 60 servers configured. Servers can be repeated.

With the value month, each server will be assigned a month in the year. The upstream block must have exactly 12 servers configured. Servers can be repeated.

With the value hour, each server will be assigned an hour throughout the day. The upstream block must have exactly 12 or 24 servers configured depending on the hour_clock parameter. Servers can be repeated. The hour clock system is defined by the parameter hour_clock described below.

timezone=string

sets the timezone to get the time.

Default value is utc.

With the value utc, the module uses the UTC timezone to get the current time.

With the value local, the module uses the local timezone of the machine to get the current time.

hour_clock=string

sets the time convention for how to specify the number of hours in a day. This parameter can only be used with interval=hour.

Default value is 12.

With the value 12, the module uses the 12-hour clock system in which the 24 hours are divided into two: AM and PM. In this case, this means there must be exactly 12 servers defined, and each of those servers will be used twice per day.

With the value 24, the module uses the 24-hour clock system. When using hour_clock=24, there must be 24 servers defined.

#Example configuration

Here is an example configuration to assign each server a single day of the week. As an example, server 127.0.0.1:9000 will be used on Sundays, server 127.0.0.1:9001 will be used on Mondays, etc.

load_module /path/to/ngx_stream_upstream_time_module.so;

stream {
    upstream {
        time interval=weekday timezone=utc;

        server 127.0.0.1:9000;
        server 127.0.0.1:9001;
        server 127.0.0.1:9002;
        server 127.0.0.1:9003;
        server 127.0.0.1:9004;
        server 127.0.0.1:9005;
        server 127.0.0.1:9006;
    }
}

#Build

To build any module, you need the source code of nginx. On Archlinux, you can install the package nginx-src.

Then, you can run the following command in the source directory of nginx.

export MY_MODULE=<path to module>
eval "./configure --add-dynamic-module=$MY_MODULE $(nginx -V 2>&1 >/dev/null | grep  -o '\--with.*')"

make modules

Note that we used the compilation flag of the installed nginx. If building nginx from source, it's a better idea to use that nginx' flag instead.

#Contribution

This module is more for exploration and fun, but I'll be glad to accept patches.

Make sure to follow NGINX's incredibly good Development Guide.