说明
- NP: NGINX Plus
- AG: Admin Guide
- 会话: session
- 上游: upstream
- 流量:traffic
- 后端:backend
- 区域:zone
目录
1.使用NGINX Plus API动态配置上游
2.总览
3.先决条件
4.启用动态配置
5.使用API进行动态配置
6.互动范例
7.配置动态配置的持久性
1.使用NGINX Plus API动态配置上游
本章介绍如何使用NGINX Plus REST API动态(动态)动态配置上游服务器和上游服务器组。
2.总览
使用NGINX Plus,可以在不重新加载服务器和NGINX配置的情况下即时修改服务器组中上游服务器的配置。 这对于以下用途很有用:
- 自动扩展,当你需要添加更多服务器时
- 维护,当你需要删除服务器,指定备份服务器或暂时关闭服务器时
- 快速设置,当你需要更改上游服务器设置(例如服务器权重,活动连接,启动缓慢,故障超时)时。
- 监视,当你使用一个命令获取服务器或服务器组的状态时
这些更改是通过带有API命令的NGINX Plus REST API接口进行的。
注意:在NGINX Plus版本12(R12)和更早的版本中,动态配置是使用
upstream_conf
处理程序执行的。 现在不赞成使用该API(和扩展status
API),而推荐使用NGINX Plus API。
3.先决条件
在使用动态配置功能之前,请确保你具有以下环境:
- NGINX Plus R13或更高版本
- 如HTTP负载平衡和TCP/UDP负载平衡中所述,你已经创建了应用程序或Web服务器的上游组。
- 上游服务器组位于共享内存区域中,如与多个工作进程共享数据中所述
4.启用动态配置
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.在upstream
块中包含zone指令。 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.通过在server块的专用location块中包含api指令,以读写模式启用NGINX API。
我们强烈建议限制访问该位置以及PATCH
/POST
/DELETE
方法。 本示例使用allow和deny指令来授予对localhost
地址(127.0.0.1
)的访问,并拒绝对所有其他地址的访问。 它还使用HTTP basic authentication验证限制对PATCH
/POST
/DELETE
方法的访问:
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;
}
}
}
5.使用API进行动态配置
NGINX Plus REST API支持以下HTTP方法:
-
GET
– 显示有关上游组或其中的单个服务器的信息 -
POST
– 将服务器添加到上游组 -
PATCH
– 修改特定服务器的参数 -
DELETE
– 从上游组中删除服务器
NGINX Plus API的端点和方法在NGINX模块参考中进行了描述。 此外,API具有内置的Swagger规范,可用于探索API和了解每种资源的功能。 可以从http://_NGINX-host_/swagger-ui/
访问Swagger文档。
要动态更改上游组的配置,请使用适当的API方法发送HTTP请求。 以下示例使用curl
命令,但是支持任何发出HTTP请求的机制。 所有请求主体和响应均为JSON格式。
URI按此顺序指定以下信息:
- 处理请求的节点的主机名或IP地址(在以下示例中为
127.0.0.1
) -
api
指令出现的位置(api
) - API版本(6)
- 上游组的名称,在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/6/http/upstreams/appservers/servers'
要从上游组中删除服务器:
curl -X DELETE -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0'
要为组中第一台服务器(ID为0
)设置down
参数:
curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0'
6.互动范例
你可以在https://demo.nginx.com/swagger-ui/上以只读模式浏览到NGINX Plus API的Swagger接口。
7.配置动态配置的持久性
使用“启用API”中的基本配置,使用API所做的更改仅存储在共享内存区域中。 重新加载NGINX Plus配置文件后,更改将被放弃。
要使更改在配置重新加载期间保持不变,请将上游服务器列表从上游块移动到用于存储服务器状态的特殊文件,该文件由state指令定义。 对于Linux发行版,建议的路径是/var/db/nginx/state/
,对于FreeBSD发行版,建议的路径是/var/lib/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接口中的配置命令来修改状态文件。 不要直接修改文件(例如,使用文本编辑器)。