API 动态更新 Upstream

今天和大家聊聊 API 动态更新 Upstream 功能，它可以动态的添加、修改、或移除上游服务器组中的节点，且无需重新加载服务器或 NGINX 配置，下面就详细来看一下吧。

解决了什么问题

通常情况下，我们要更新 Upstream 的 Server 成员及属性信息，我们需要如下步骤：

1、更新 Upstream 的配置，需要编辑 NGINX 的配置文件，如下：

http {
    # 创建upstream group（包含server成员）
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 down;
    }       
}

2、配置更新后，重载配置，以保证配置生效，如上操作无法实现动态更新，即时性较差。

而通过 API 动态更新 Upstream，就可以解决如上的问题。

哪些场景会用到该功能呢？

自动扩容：当需要往 Upstream group 中添加更多的 server 时；
服务器成员维护：当你需要移除一个 server，或指定一个 server 为备份服务器时，或暂时关闭一个 server 停止提供服务时；
快速设置服务器属性：诸如当你需要改变服务器权重、活动连接、缓慢启动、故障超时等属性需求时。
服务器状态监控：当需要用一个命令来获得服务器或服务器组的状态时。

如何启用动态 Upstream API

通过以下代码配置 Upstream 列表以及反向代理，并且开启 API 动态：

用 API 指令开启 / 关闭 NGINX API， write=on 表示以读写模式打开。write 默认不写，代表 off，仅支持查询操作。

动态 API 更新 Upstream 应用例子

1、动态添加 Server

可以以 IP 地址形式动态添加 server，执行如下命令：

curl -v -X POST -s http://192.168.40.111:8181/zxlapi/7/http/upstreams/cluster1/servers -d '{"server": "192.168.40.135:8080"}'|jq .

返回结果如下图：

也可以以域名方式动态添加：

curl -v -X POST -s http://192.168.40.111:8181/zxlapi/7/http/upstreams/cluster1/servers -d '{"server": "serv110.tmzy.com:8080"}'|jq .

以域名方式添加的 server 不同之处在于，域名方式添加的 server 会作为父 server 存在，它也会占用一个 server id, 其下可能关联一个或更多个子 server。

2、动态修改 server修改

命令参考如下：

curl -v -X PATCH -s http://192.168.40.111：8181/zxlapi/7/http/upstreams/cluster1/servers/6 -d '{"backup": false, "weight": 10 }' |jq .

修改后随即会返回修改的 server 的基本信息，不包括健康状况，请求响应等信息。

注意，以域名形式添加的 server，父 server 和子 server 都支持修改，互不影响。

3、动态删除 server

删除命令参考如下：

curl -X DELETE -s http://192.168.40.111:8181/zxlapi/7/http/upstreams/cluster1/servers/1 |jq .

以 IP 形式添加的 server，执行删除命令后，随即返回结果就可以看见成功删除了一条。

以域名形式添加的 server，执行删除父 server 命令后，父 server 和其下所有子 server 会一并删除。

以域名形式添加的 server，执行删除子 server 命令后，要进行提示校验，不允许删除子 server。

4、查询 server

命令参考如下：

curl -v http://192.168.40.111:8181/zxlapi/7/http/upstreams/cluster1/servers/ server_id | jq .

以域名方式添加的子 server 的查询返回结果如下：

会比 IP 形式添加的 server 多出 parent 和 host 两个字段。

5、动态配置的持久化

通过 API 所做的更改，在配置文件被重新加载时，这些改变会被丢弃，那想让动态修改永久生效怎么办？可以通过 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;
       
    }
}

注意：state 状态文件只能通过 API 方式进行修改，不要去直接修改该文件。