upsync
The `upsync` directive allows NGINX to dynamically sync upstream server configurations from Consul or Etcd, enabling live updates without service interruptions.
Description
The upsync directive is a powerful feature of the NGINX module that synchronizes upstream server configurations from a key-value store like Consul or Etcd. This synchronization takes place without the need to restart NGINX, thus avoiding any downtime and ensuring continuous service delivery. When issued in the upstream context, this directive requires at least one argument, which specifies the address of the Consul or Etcd server along with the path to the upstream configuration. Additional parameters can be included, such as upsync_timeout, which defines the time limit for the sync operations, and upsync_interval, which sets how often the sync checks occur. Furthermore, the upsync_type parameter identifies the type of store being accessed (e.g., Consul or Etcd).
Upon successful configuration, NGINX can automatically add or remove backend servers as defined in the key-value store, modifying relevant attributes like weight and health checks in real-time. Should a server fail or become unhealthy, it can be seamlessly removed from the upstream without any action needed from the administrator. The module also provides an option to specify a dump path where the current state of upstream configurations can be saved, allowing for manual inspection or rollback if necessary.
Config Example
http {
upstream my_upstream {
upsync 127.0.0.1:8500/v1/kv/upstreams/my_app upsync_timeout=10s upsync_interval=1s upsync_type=consul;
}
server {
listen 80;
location / {
proxy_pass http://my_upstream;
}
}
}Ensure the correct IP address and port for Consul or Etcd are provided, or syncing will fail.
Be aware of the strong_dependency setting as it influences how upstream servers are managed under failed conditions—using it incorrectly may lead to unwanted server removals.
Understand the implications of configuring sync intervals too short, as it can create unnecessary load on both NGINX and the key-value store.