This chapter describes how to configure upstream servers and upstream server groups on-the-fly with NGINX Plus REST API.

Table of Contents

Overview

With NGINX Plus, configuration of upstream servers in a server group can be modified on-the-fly with the NGINX Plus REST API interface. You can send an API command to view all servers or a particular server in a group, modify parameters of a particular server, add or remove servers.

Note: in previous versions of NGINX Plus on-the fly configuration was performed with the upstream_conf handler. The old extended status and upstream_conf reconfiguration APIs are now deprecated.

Prerequisites

Prior to starting using the on-the-fly configuration, make sure that you have the following environment:

  1. NGINX Plus R13
  2. You have created upstream server groups with upstream servers. See HTTP Load Balancing and TCP/UDP Load Balancing for more information
  3. Upstream server groups reside in the shared memory zone. See Sharing Data with Multiple Worker Processes for more information

Enabling the API in the Configuration File

To enable the API, create a separate location for API requests in the NGINX configuration file, and specify the api directive in this location:

server {
...
location /api {
api write=on;
}
}

We strongly recommend restricting access to this location, for example, allow access only from the 127.0.0.1 address:

server {
location /api {
api write=on;
allow 127.0.0.1;
deny all;
}
}

An example of API location with upstream server group configuration:

http {
# ...
# Configuration of the server group
upstream appservers {
zone appservers 64k;

server appserv1.example.com weight=5;
server appserv2.example.com:8080 fail_timeout=5s;

server reserve1.example.com:8080 backup;
server reserve2.example.com:8080 backup;
}

server {
# Location that proxies requests to the group
location / {
proxy_pass http://appservers;
health_check;
}

# Location for configuration requests
location /api {
api write=on;
allow 127.0.0.1;
deny all;
}
}
}

In the example, the access to the second location is allowed only from the 127.0.0.1 IP address. Access from all other IP addresses is denied.

Using the API

NGINX Plus REST API supports the following HTTP methods:

  • GET – get information about a particular upstream server or an upstream server group
  • POST – add an upstream server to the server group
  • PATCH – update parameters of a particular upstream server
  • DELETE- delete an upstream server from the server group

Endpoints and methods are described in details in the NGINX reference documentation. In addition, the API is also provided with a Swagger specification that can be used to explore the API and understand the capabilities of each resource. The Swagger documentation is bundled with NGINX Plus and can be accessed by visiting http://nginxhost/swagger-ui/.

To pass a configuration command to NGINX, send an API command by any means, for example, curl. All request bodies and responses are in the JSON format. The API URL should include the API version, the current version is 1.

For example, to add a new server to the server group, send the following curl command:

curl -X POST -d '{
"server": "10.0.0.1:8089",
"weight": 4,
"max_conns": 0,
"max_fails": 0,
"fail_timeout": "10s",
"slow_start": "10s",
"backup": true,
"down": true
}' -s http://127.0.0.1/api/1/http/upstreams/appservers/servers

To remove a server from the server group:

curl -X DELETE -s http://127.0.0.1/api/1/http/upstreams/appservers/servers/0

To modify a parameter of a specific server:

curl -X PATCH -d '{ "down": true }' -s http://127.0.0.1/api/1/http/upstreams/appservers/servers/0

Live Example

You can try NGINX Plus API in the read-only mode at https://demo.nginx.com/swagger-ui/.

Configuring Persistence of On-the-Fly Configuration

The configuration from the previous example allows storing the on-the-fly changes only in the shared memory. These changes will be discarded any time NGINX Plus configuration file is reloaded.

To make these changes persistent across configuration reloads, you will need to move the list of upstream servers from the upstream block to a special file that will keep the state of the upstream servers. The path to the file is set with the state directive. Recommended path for Linux distributions is /var/lib/nginx/state/, for FreeBSD distributions is /var/db/nginx/state/:

http {
# ...
upstream appservers {
zone appservers 64k;
state /var/lib/nginx/state/appservers.conf;

# All these servers should be moved to the file using the upstream_conf API:
# server appserv1.example.com weight=5;
# server appserv2.example.com:8080 fail_timeout=5s;
# server reserve1.example.com:8080 backup;
# server reserve2.example.com:8080 backup;
}
}

Keep in mind that this file can be modified only with configuration commands from the API interface, modifying the file directly should be avoided.