Consul enabled upstream balancer. Does exactly what is advertised -- enables nginx to use consul service discovery to forward requests to dynamic upstreams.
Each nginx worker must initialize the library:
lua_shared_dict consul_balancer 4m;
init_worker_by_lua_block {
local consul_balancer = require "n4l.consul_balancer"
consul_balancer.set_shared_dict_name("consul_balancer") # name of shared dictionary to keep cache in
consul_balancer.watch("http://127.0.0.1:8500", {"foo", "bar"})
}
You may define extended attributes in service descriptor:
consul_balancer.watch("http://127.0.0.1:8500", {
"foo", -- short form
{
name="bar", -- mandatory field
service="foo-bar", -- defaults to 'name'
tag="http",
near="_agent",
dc="dc2",
["node-meta"]="key:value",
token="consul-token"
}
})
Attribute explanation is listed in consul docs.
Once the worker is initialised, you can define upstream like this:
upstream upstream_foo {
server 127.0.0.1:666; # Required, because empty upstream block is rejected by nginx (nginx+ can use 'zone' instead)
balancer_by_lua_block {
local consul_balancer = require "n4l.consul_balancer"
consul_balancer.round_robin("foo")
}
}
Upstream usage is normal and follows all expected nginx rules:
location /somefoo {
proxy_pass http://upstream_foo;
}
Due to limitation of 'init_worker_by_lua_*' to run lua cosockets initial lookup is done async from the startup sequence. That leaves a delay, measurable in roundtrip time from consul to nginx, until lua balancer has upstreams to forward requests to.