使用NGINX Plus API动态配置upstream

使用NGINX Plus API动态配置upstream

 

本章将介绍如何配置上游服务器和上游服务器群动态与NGINX加REST API。

• 总览
• 先决条件
• 启用动态配置
• 使用API​​进行动态配置
  • 互动范例
• 配置动态配置的持久性

 

总览

使用NGINX Plus，可以在不重新加载服务器和NGINX配置的情况下即时修改服务器组中上游服务器的配置。这对于以下用途很有用：

• 自动缩放，当您需要添加更多服务器时
• 维护，需要删除服务器，指定备份服务器或暂时关闭服务器时
• 快速设置，当您需要更改上游服务器设置（例如服务器权重，活动连接，启动缓慢，故障超时）时。
• 监视，当您使用一个命令获得服务器或服务器组的状态时

这些更改是通过带有API命令的NGINX Plus REST API接口进行的。

注意：在NGINX Plus版本12（R12）和更早的版本中，使用upstream_conf处理程序执行了动态配置。status现在不赞成使用该API（和扩展的API），而推荐使用NGINX Plus API。

 

先决条件

在使用动态配置功能之前，请确保您具有以下环境：

1. NGINX Plus R13或更高版本
2. 如HTTP负载平衡和TCP / UDP负载平衡中所述，您已经创建了应用程序或Web服务器的上游组。
3. 上游服务器组位于共享内存区域中，如与多个工作进程共享数据中所述

 

启用动态配置

1. 按照将流量代理到一组服务器中所述创建上游服务器组。

   http {
       # ...
       upstream appservers {          
           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 upstream group
           location / {
               proxy_pass http://appservers;
               health_check;
            }
       }
   }

2. 将zone指令包括在upstream块中。该zone伪指令在共享内存中配置区域，并设置区域名称和大小。服务器组的配置保留在此区域中，因此所有工作进程都使用相同的配置：

   http {
       # ...
       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;
       }
   }

3. 通过将api指令包括在location块的专用块中，以读写模式启用NGINX API server。

   我们强烈建议限制进入的位置和PATCH/ POST/ DELETE方法。本示例使用allow和deny指令授予对localhost地址（127.0.0.1）的访问权限，并拒绝对所有其他地址的访问。它还限制访问PATCH/ POST/ DELETE使用方法：HTTP basic authentication

   server {
       location /api {
           limit_except GET {
               auth_basic "NGINX Plus API";
               auth_basic_user_file /path/to/passwd/file;
           }
           api write=on;
           allow 127.0.0.1;
           deny  all;
       }
   }

完整的例子：

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 upstream group
        location / {
            proxy_pass http://appservers;
            health_check;
        }
        
        # Location for dynamic configuration requests
        location /api {
            limit_except GET {
                auth_basic "NGINX Plus API";
                auth_basic_user_file /path/to/passwd/file;
            }
            api write=on;
            allow 127.0.0.1;
            deny  all;
        }
    }
}

 

使用API​​进行动态配置

NGINX Plus REST API支持以下HTTP方法：

• GET –显示有关上游组或其中的单个服务器的信息
• POST –将服务器添加到上游组
• PATCH –修改特定服务器的参数
• DELETE –从上游组中删除服务器

《NGINX模块参考》中介绍了NGINX Plus API的端点和方法。此外，API具有内置的Swagger规范，可用于探索API和了解每种资源的功能。Swagger文档可从访问http://_NGINX-host_/swagger-ui/。

要动态更改上游组的配置，请使用适当的API方法发送HTTP请求。以下示例使用该curl命令，但支持任何发出HTTP请求的机制。所有请求主体和响应均为JSON格式。

URI按此顺序指定以下信息：

• 处理请求的节点的主机名或IP地址（在以下示例中，127.0.0.1）
• api指令出现的位置（api）
• API版本（5）
• 上游组的名称，在NGINX Plus配置层次结构中的位置完整，用斜杠分隔的路径（http/upstreams/appservers）表示

例如，要将新服务器添加到appservers上游组，请发送以下curl命令：

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/5/http/upstreams/appservers/servers'

要从上游组中删除服务器：

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

要为组中down第一台服务器（ID为0）设置参数：

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

 

互动范例

您可以在https://demo.nginx.com/swagger-ui/上以只读模式浏览到NGINX Plus API的Swagger接口。

 

配置动态配置的持久性

使用“ 启用API”中的基本配置， 使用API所做的更改仅存储在共享内存区域中。重新加载NGINX Plus配置文件后，更改将被放弃。

要使更改在配置重载之间保持不变，请将上游服务器列表从该upstream块移至用于存储服务器状态的特殊文件，该文件由state指令定义。对于Linux发行版/var/lib/nginx/state/，推荐的路径是，对于FreeBSD发行版，推荐的路径是/var/db/nginx/state/。

http {
    # ...
    upstream appservers {
        zone appservers 64k;
        state /var/lib/nginx/state/appservers.conf;
        
        # All servers are defined in the state file
        # 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;
    }
}

请记住，只能使用API接口中的配置命令来修改状态文件。不要直接修改文件（例如，使用文本编辑器）。