ngx_dynamic_upstream
ngx_dynamic_upstream
is the module for operating upstreams dynamically with HTTP APIs
such as ngx_http_upstream_conf
.
This module also supports stream upstreams manipulation.
Online reconfiguration upstream addresses from DNS by hostname without reloads.
Build status
Requirements
ngx_dynamic_upstream
requires the zone
directive in the upstream
context.
Status
Production ready.
Directives
dynamic_upstream
Syntax | dynamic_upstream |
---|---|
Default | - |
Context | location |
dynamic_state_file
Syntax | dynamic_state_file file |
---|---|
Default | - |
Context | upstream |
Persistent state of upstream.
Example: dynamic_state_file backend.peers;
If you want to add servers in upstream, you MUST create backend.peers file manually and add these servers into it.
Add servers directly into upstream
section is incorrect and you will see fake 0.0.0.0:1 server in list and backend.peers file.
dns_update
Syntax | dns_update 60s [thread pool] |
---|---|
Default | - |
Context | upstream |
Background synchronization hosts addresses by DNS.
dns_add_down
Syntax | dns_add_down on/off |
---|---|
Default | off |
Context | upstream |
Add new peers in down state.
dns_ipv6
Syntax | dns_ipv6 on |
---|---|
Default | - |
Context | upstream |
Include IPv6 addresses.
Quick Start
http {
upstream backends {
zone zone_for_backends 1m;
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
}
# Persistent state
# DON't add servers directly into upstream section
# Add servers into backend.peers file
upstream backends2 {
zone zone_for_backends2 1m;
dynamic_state_file backend.peers;
}
server {
listen 6000;
location /dynamic {
allow 127.0.0.1;
deny all;
dynamic_upstream;
}
location / {
proxy_pass http://backends;
}
}
}
stream {
upstream backends_stream {
zone zone_for_backends_stream 1m;
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
}
server {
listen 6001;
proxy_pass backends_stream;
}
}
DNS background updates
http {
upstream mail {
zone mail 1m;
dns_update 60s;
dns_ipv6 off;
server mail.ru;
server google.com backup;
}
server {
listen 6000;
location /dynamic {
allow 127.0.0.1;
deny all;
dynamic_upstream;
}
location / {
proxy_pass http://backends;
}
}
}
HTTP APIs
You can operate upstreams dynamically with HTTP APIs.
list
$ curl "http://127.0.0.1:6000/dynamic?upstream=mail"
server mail.ru addr=217.69.139.201:80;
server mail.ru addr=94.100.180.201:80;
server mail.ru addr=217.69.139.200:80;
server mail.ru addr=94.100.180.200:80;
server google.com addr=173.194.73.139:80 backup;
server google.com addr=173.194.73.100:80 backup;
server google.com addr=173.194.73.101:80 backup;
server google.com addr=173.194.73.138:80 backup;
server google.com addr=173.194.73.102:80 backup;
server google.com addr=173.194.73.113:80 backup;
$
verbose
$ curl "http://127.0.0.1:6000/dynamic?upstream=mail&verbose="
server mail.ru addr=94.100.180.200:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server mail.ru addr=94.100.180.201:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server mail.ru addr=217.69.139.200:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server mail.ru addr=217.69.139.201:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server google.com addr=64.233.165.101:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
server google.com addr=64.233.165.102:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
server google.com addr=64.233.165.139:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
server google.com addr=64.233.165.138:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
server google.com addr=64.233.165.100:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
server google.com addr=64.233.165.113:80 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 backup;
$
update_parameters
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&server=127.0.0.1:6003&weight=10&max_fails=5&fail_timeout=5&max_conns=10"
server 127.0.0.1:6001 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6002 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6003 weight=10 max_fails=5 fail_timeout=5 max_conns=10 conns=0;
$
The supported parameters are below.
- weight
- max_fails
- fail_timeout
down
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&server=127.0.0.1:6003&down="
server 127.0.0.1:6001 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6002 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6003 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0 down;
$
up
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&server=127.0.0.1:6003&up="
server 127.0.0.1:6001 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6002 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
server 127.0.0.1:6003 weight=1 max_fails=1 fail_timeout=10 max_conns=0 conns=0;
$
add peer
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&add=&server=127.0.0.1:6004"
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
server 127.0.0.1:6004;
$
add host
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&add=&server=localhost:6004"
DNS resolving in progress
$
Peers will be added in background.
add backup peer
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&add=&server=127.0.0.1:6004&backup="
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
server 127.0.0.1:6004 backup;
$
remove peer
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&remove=&server=127.0.0.1:6003"
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6004;
$
remove server
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends&remove=&server=mail.ru"
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6004;
$
add stream
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends_stream&add=&server=127.0.0.1:6004&stream="
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
server 127.0.0.1:6004;
$
add backup stream
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends_stream&add=&server=127.0.0.1:6004&backup=&stream="
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6003;
server 127.0.0.1:6004 backup;
$
remove stream
$ curl "http://127.0.0.1:6000/dynamic?upstream=backends_stream&remove=&server=127.0.0.1:6003&stream="
server 127.0.0.1:6001;
server 127.0.0.1:6002;
server 127.0.0.1:6004;
$
License
See LICENSE.