Upstream成员_api
1. 功能说明
该模块使用restful API，可以实现动态对http模块和stream模块的upstream的成员server进行添加、删除、修改、查询的功能。
2. 依赖模块
动态upstream_api功能依赖模块:
njet.conf
load_module modules/njt_http_upstream_member_module.so; njet_ctrl.conf
load_module modules/njt_http_upstream_api_module.so; 3. 调用样例
3.1 http模块API说明
http模块可以使用upstream_api功能进行增删改查的操作，以下将介绍具体使用方法和使用效果展示。
查询全部upstream组状态：
GET http://ip+port/api/v1/upstream_api/http/upstreams/查询具体upstream名为backend的upstream组状态：
GET http://ip+port/api/v1/upstream_api/http/upstreams/backend查询具体upstream名为backend的所有server配置：
GET http://ip+port/api/v1/upstream_api/http/upstreams/backend/servers/查询具体upstream名为backend的id为0的server配置：
GET http://ip+port/api/v1/upstream_api/http/upstreams/backend/servers/0向具体upstream名为backend添加一个server：
POST http://ip+port/api/v1/upstream_api/http/upstreams/backend/servers/修改具体upstream名为backend的id为0的server配置：
PATCH http://ip+port/api/v1/upstream_api/http/upstreams/backend/servers/0删除具体upstream名为backend的id为0的server：
DELETE http://ip+port/api/v1/upstream_api/http/upstreams/backend/servers/0重置具体upstream名为backend的upstream状态数据：
DELETE http://ip+port/api/v1/upstream_api/http/upstreams/backend/3.1.1 添加
添加功能支持ip和域名的添加：
ip添加
curl -X POST -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1/servers/ -d '{"server":"192.168.40.101:8080","weight":2,"max_conns":2,"max_fails":"1","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 0,
"server": "192.168.40.101:8080",
"weight": 2,
"max_conns": 2,
"max_fails": 1,
"fail_timeout": "5s",
"slow_start": "5s",
"route": "",
"backup": true,
"down": false
}域名添加
curl -X POST -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/beckend2/servers/ -d '{"server":"www.dev.test.com:8080","weight":1,"max_conns":1,"max_fails":"1","fail_timeout":"1s","slow_start":"1s","backup":false,"down":true}'|jq .
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": false,
"down": true
}3.1.2 查询
查询功能支持多层级查询，首先是upstreams级，能够查找出所有的upstream信息，且无法查询出域名server的父级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/ |jq . {
"backend1": {
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster1"
},
"backend2": {
"peers": [
{
"id": 1,
"server": "192.168.40.101:8080",
"name": "www.dev.test.com:8080",
"backup": false,
"weight": 1,
"state": "down",
"active": 0,
"max_conns": 1,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster2"
}
}upstream级，可以指定查看单个upstream的信息
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster1"
}servers级，可以查看单个upstream的所有server级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers |jq .
[
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": false,
"down": true,
"parent": 0,
"host": "www.dev.test.com:8080"
},
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": false,
"down": true
}
]id级，可以查看单个upstream的单个id级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/1 |jq .
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": false,
"down": true,
"parent": 0,
"host": "www.dev.test.com:8080"
}3.1.3 修改
修改功能可以对server节点的参数进行修改，其中ip格式server节点可以修改server参数，域名server及其子节点server无法修改，且backup参数无法修改
修改ip格式server
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1/servers/0 -d '{"server":"192.168.40.114:8080","weight":1,"max_conns":1,"max_fails":"2","fail_timeout":"1s","slow_start":"1s","backup":false,"down":true}'|jq .
{
"id": 0,
"server": "192.168.40.114:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 2,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": true,
"down": true
}修改域名格式server，父节点server参数修改
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/0 -d '{"server":"www.dev.test2.com:8080","weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"error": {
"status": 400,
"text": "server address is immutable",
"code": "UpstramServerImmutable"
},
"request_id": "730e18137d711d23bb93b1c867c21b89",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}修改域名格式server，子节点server参数修改
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/1 -d '{"server":"192.168.40.114:8080","weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"error": {
"status": 400,
"text": "server address is immutable",
"code": "UpstramServerImmutable"
},
"request_id": "bcda20dbc9276a1e46229e620e5c5813",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}修改域名格式server，只修改父节点基本参数
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/0 -d '{"weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 2,
"max_conns": 2,
"max_fails": 2,
"fail_timeout": "5s",
"slow_start": "5s",
"route": "",
"backup": false,
"down": false
}修改域名格式server，只修改子节点基本参数
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/1 -d '{"weight":1,"max_conns":3,"max_fails":"3","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 3,
"max_fails": 3,
"fail_timeout": "5s",
"slow_start": "5s",
"route": "",
"backup": false,
"down": false,
"parent": 0,
"host": "www.dev.test.com:8080"
}3.1.4 删除
**curl -X DELETE **http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/http1/servers/0 | jq .
删除功能可以针对单个server进行删除，且删除域名格式server父节点时会兼带子节点全部删除，但是删除域名格式server子节点时将无法删除
删除ip格式server
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1/servers/0 |jq .
[]删除域名格式server子节点
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/1 |jq .
{
"error": {
"status": 400,
"text": "server not removeable",
"code": "UpstreamServerImmutable"
},
"request_id": "5399a28db3d4598b821c1c65cb7efa86",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}删除域名格式server父节点
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend2/servers/0 |jq .
[]3.1.5 重置
针对upstream，清空健康检查等数据
使用查询命令查看upstream的数据，可以观察到requests参数有一些数据信息
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"requests": 2,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster1"
}使用清除数据命令进行数据清空
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1 |jq .再次查询upstream的数据，可以看到已经被清空
curl -s http://127.0.0.1:8081/api/v1/upstream_api/http/upstreams/backend1 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"requests": 0,
"responses": {
"1xx": 0,
"2xx": 0,
"3xx": 0,
"4xx": 0,
"5xx": 0,
"codes": {},
"total": 0
},
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster1"
}3.2 stream模块API说明
stream模块可以使用upstream_api功能进行增删改查的操作，以下将介绍具体使用方法和使用效果展示。
查询全部upstream组状态：
GET http://ip+port/api/v1/upstream_api/stream/upstreams/查询具体upstream名为backend的upstream组状态：
GET http://ip+port/api/v1/upstream_api/stream/upstreams/backend查询具体upstream名为backend的所有server配置：
GET http://ip+port/api/v1/upstream_api/stream/upstreams/backend/servers/查询具体upstream名为backend的id为0的server配置：
GET http://ip+port/api/v1/upstream_api/stream/upstreams/backend/servers/0向具体upstream名为backend添加一个server：
POST http://ip+port/api/v1/upstream_api/stream/upstreams/backend/servers/修改具体upstream名为backend的id为0的server配置：
PATCH http://ip+port/api/v1/upstream_api/stream/upstreams/backend/servers/0删除具体upstream名为backend的id为0的server：
DELETE http://ip+port/api/v1/upstream_api/stream/upstreams/backend/servers/0重置具体upstream名为backend的upstream状态数据：
DELETE http://ip+port/api/v1/upstream_api/stream/upstreams/backend/3.2.1 添加
添加功能支持ip和域名的添加：
ip添加
curl -X POST -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3/servers/ -d '{"server":"192.168.40.101:8080","weight":2,"max_conns":2,"max_fails":"1","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 0,
"server": "192.168.40.101:8080",
"weight": 2,
"max_conns": 2,
"max_fails": 1,
"fail_timeout": "5s",
"slow_start": "5s",
"route": "",
"backup": true,
"down": false
}域名添加
curl -X POST -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/ -d '{"server":"www.dev.test.com:8080","weight":1,"max_conns":1,"max_fails":"1","fail_timeout":"1s","slow_start":"1s","backup":false,"down":true}'|jq .
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"route": "",
"backup": false,
"down": true
}3.2.2 查询
查询功能支持多层级查询，首先是upstreams级，能够查找出所有的upstream信息，且无法查询出域名server的父级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/ |jq . {
"backend3": {
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"connecions": 0,
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"zombies": 0,
"zone": "cluster3"
},
"backend4": {
"peers": [
{
"id": 1,
"server": "192.168.40.101:8080",
"name": "www.dev.test.com:8080",
"backup": false,
"weight": 1,
"state": "down",
"active": 0,
"max_conns": 1,
"connecions": 0,
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"zombies": 0,
"zone": "cluster4"
}
}upsteam级，可以指定查看单个upstream的信息
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"connecions": 0,
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"zombies": 0,
"zone": "cluster3"
}servers级，可以查看单个upstream的所有server级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers |jq .
[
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"backup": false,
"down": true,
"parent": 0,
"host": "www.dev.test.com:8080"
},
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"backup": false,
"down": true
}
]id级，可以查看单个upstream的单个id级节点
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/1 |jq .
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 1,
"fail_timeout": "1s",
"slow_start": "1s",
"backup": false,
"down": true,
"parent": 0,
"host": "www.dev.test.com:8080"
}3.2.3 修改
修改功能可以对server节点的参数进行修改，其中ip格式server节点可以修改server参数，域名server及其子节点server无法修改，且backup参数无法修改
修改ip格式server
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3/servers/0 -d '{"server":"192.168.40.114:8080","weight":1,"max_conns":1,"max_fails":"2","fail_timeout":"1s","slow_start":"1s","backup":false,"down":true}'|jq .
{
"id": 0,
"server": "192.168.40.114:8080",
"weight": 1,
"max_conns": 1,
"max_fails": 2,
"fail_timeout": "1s",
"slow_start": "1s",
"backup": true,
"down": true
}修改域名格式server，父节点server参数修改
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/0 -d '{"server":"www.dev.test2.com:8080","weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"error": {
"status": 400,
"text": "server address is immutable",
"code": "UpstramServerImmutable"
},
"request_id": "730e18137d711d23bb93b1c867c21b89",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}修改域名格式server，子节点server参数修改
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/1 -d '{"server":"192.168.40.114:8080","weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"error": {
"status": 400,
"text": "server address is immutable",
"code": "UpstramServerImmutable"
},
"request_id": "bcda20dbc9276a1e46229e620e5c5813",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}修改域名格式server，只修改父节点基本参数
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/0 -d '{"weight":2,"max_conns":2,"max_fails":"2","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 0,
"server": "www.dev.test.com:8080",
"weight": 2,
"max_conns": 2,
"max_fails": 2,
"fail_timeout": "5s",
"slow_start": "5s",
"backup": false,
"down": false
}修改域名格式server，只修改子节点基本参数
curl -X PATCH -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/1 -d '{"weight":1,"max_conns":3,"max_fails":"3","fail_timeout":"5s","slow_start":"5s","backup":true,"down":false}'|jq .
{
"id": 1,
"server": "192.168.40.101:8080",
"weight": 1,
"max_conns": 3,
"max_fails": 3,
"fail_timeout": "5s",
"slow_start": "5s",
"backup": false,
"down": false,
"parent": 0,
"host": "www.dev.test.com:8080"
}3.2.4 删除
删除功能可以针对单个server进行删除，且删除域名格式server父节点时会兼带子节点全部删除，但是删除域名格式server子节点时将无法删除
删除ip格式server
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3/servers/0 |jq .
[]删除域名格式server子节点
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/1 |jq .
{
"error": {
"status": 400,
"text": "server not removeable",
"code": "UpstreamServerImmutable"
},
"request_id": "5399a28db3d4598b821c1c65cb7efa86",
"href": "https://njet.org/en/docs/http/njt_http_api_module.html"
}删除域名格式server父节点
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend4/servers/0 |jq .
[]3.2.5 重置
针对upstream，清空健康检查等数据
使用查询命令查看upstream的数据，可以观察到requests参数有一些数据信息
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"connecions": 4,
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster3"
}使用清除数据命令进行数据清空
curl -X DELETE -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3 |jq .再次查询upstream的数据，可以看到已经被清空
curl -s http://127.0.0.1:8081/api/v1/upstream_api/stream/upstreams/backend3 |jq .
{
"peers": [
{
"id": 0,
"server": "192.168.40.101:8080",
"name": "192.168.40.101:8080",
"backup": true,
"weight": 2,
"state": "up",
"active": 0,
"max_conns": 2,
"connecions": 0,
"sent": 0,
"received": 0,
"fails": 0,
"unavail": 0,
"health_checks": {
"checks": 0,
"fails": 0,
"unhealthy": 0
},
"downtime": 0
}
],
"keepalive": 0,
"zombies": 0,
"zone": "cluster3"
}3.3 upstream server持久化
upstream_api功能可以使用持久化配置来保证增加、删除、修改后数据的持久性，例如重启服务后，之前的配置依然可以使用，且当某个upstream配置了state持久化后，upstream就无法再静态添加server指令想要使用持久化功能，需要添加以下配置。
upstream http1{
zone cluster 64k;
state /home/njet/state/njet_state.file; #state持久化保存文件可以自定义名称
}