使用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。

先决条件

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

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

启用动态配置

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

http {# ...upstream appservers {server weight=5;server :8080 fail_timeout=5s;server :8080 backup;server :8080 backup;}server {# Location that proxies requests to the upstream grouplocation / {proxy_pass http://appservers;health_check;}}}

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

http {# ...upstream appservers {zone appservers 64k;server weight=5;server :8080 fail_timeout=5s;server :8080 backup;server :8080 backup;}}

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

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

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 groupupstream appservers {zone appservers 64k;server weight=5;server :8080 fail_timeout=5s;server :8080 backup;server :8080 backup;}server {# Location that proxies requests to the upstream grouplocation / {proxy_pass http://appservers;health_check;}# Location for dynamic configuration requestslocation /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'

互动范例

您可以在/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 weight=5;# server :8080 fail_timeout=5s;# server :8080 backup;# server :8080 backup;}}

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