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.