apisix/docs/zh/latest/admin-api.md
kwanhur 96838b9b47
docs(lint): import Chinese copywriting autocorrect linter (#6568)
Co-authored-by: leslie <59061168+leslie-tsang@users.noreply.github.com>
Co-authored-by: 琚致远 <juzhiyuan@apache.org>
2022-03-24 15:19:39 +08:00

68 KiB
Raw Blame History

title
Admin API

描述

Admin API 是为 Apache APISIX 服务的一组 API我们可以将参数传递给 Admin API 以控制 APISIX 节点。更好地了解其工作原理,请参阅 architecture-design 中的文档。

启动 Apache APISIX 时,默认情况下 Admin API 将监听 9080 端口HTTPS 的 9443 端口)。您可以通过修改 conf/config.yaml 文件来改变默认监听的端口。

在下面出现的 X-API-KEY 指的是 conf/config.yaml 文件中的 apisix.admin_key.key,它是 Admin API 的访问 token。

Route

地址/apisix/admin/routes/{id}?ttl=0

说明Route 字面意思就是路由,通过定义一些规则来匹配客户端的请求,然后根据匹配结果加载并执行相应的插件,并把请求转发给到指定 Upstream。

注意:在启用 Admin API 时,它会占用前缀为 /apisix/admin 的 API。因此为了避免您设计 API 与 /apisix/admin 冲突,建议为 Admin API 使用其他端口,您可以在 conf/config.yaml 中通过 port_admin 进行自定义 Admin API 端口。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/routes 获取资源列表
GET /apisix/admin/routes/{id} 获取资源
PUT /apisix/admin/routes/{id} {...} 根据 id 创建资源
POST /apisix/admin/routes {...} 创建资源id 由后台服务自动生成
DELETE /apisix/admin/routes/{id} 删除资源
PATCH /apisix/admin/routes/{id} {...} 标准 PATCH ,修改已有 Route 的部分属性,其他不涉及的属性会原样保留;如果你要删除某个属性,将该属性的值设置为 null 即可删除;特别地,当需要修改属性的值为数组时,该属性将全量更新
PATCH /apisix/admin/routes/{id}/{path} {...} SubPath PATCH通过 {path} 指定 Route 要更新的属性,全量更新该属性的数据,其他不涉及的属性会原样保留。两种 PATCH 的区别可以参考后面的示例

URL 请求参数

名字 可选项 类型 说明 示例
ttl 可选 辅助 超过这个时间会被自动删除,单位:秒 ttl=1

body 请求参数

名字 可选项 类型 说明 示例
uri 必选,不能与 uris 一起使用 匹配规则 除了如 /foo/bar/foo/gloo 这种全量匹配外,使用不同 Router 还允许更高级匹配,更多见 Router "/hello"
uris 必选,不能与 uri 一起使用 匹配规则 非空数组形式,可以匹配多个 uri ["/hello", "/world"]
plugins 可选 Plugin 详见 Plugin
script 可选 Script 详见 Script
upstream 可选 Upstream 启用的 Upstream 配置,详见 Upstream
upstream_id 可选 Upstream 启用的 upstream id详见 Upstream
service_id 可选 Service 绑定的 Service 配置,详见 Service
plugin_config_id 可选,无法跟 script 一起配置 Plugin 绑定的 Plugin config 配置,详见 Plugin config
name 可选 辅助 标识路由名称 route-xxxx
desc 可选 辅助 标识描述、使用场景等。 路由 xxxx
host 可选,不能与 hosts 一起使用 匹配规则 当前请求域名,比如 foo.com;也支持泛域名,比如 *.foo.com "foo.com"
hosts 可选,不能与 host 一起使用 匹配规则 非空列表形态的 host,表示允许有多个不同 host,匹配其中任意一个即可。 ["foo.com", "*.bar.com"]
remote_addr 可选,不能与 remote_addrs 一起使用 匹配规则 客户端请求 IP 地址:192.168.1.101192.168.1.102 以及 CIDR 格式的支持 192.168.1.0/24。特别的APISIX 也完整支持 IPv6 地址匹配:::1fe80::1fe80::1/64 等。 "192.168.1.0/24"
remote_addrs 可选,不能与 remote_addr 一起使用 匹配规则 非空列表形态的 remote_addr,表示允许有多个不同 IP 地址,符合其中任意一个即可。 ["127.0.0.1", "192.0.0.0/8", "::1"]
methods 可选 匹配规则 如果为空或没有该选项,代表没有任何 method 限制,也可以是一个或多个的组合:GETPOSTPUTDELETEPATCHHEADOPTIONSCONNECTTRACE ["GET", "POST"]
priority 可选 匹配规则 如果不同路由包含相同 uri,根据属性 priority 确定哪个 route 被优先匹配,值越大优先级越高,默认值为 0。 priority = 10
vars 可选 匹配规则 由一个或多个[var, operator, val]元素组成的列表,类似这样:[[var, operator, val], [var, operator, val], ...]]。例如:["arg_name", "==", "json"],表示当前请求参数 namejson。这里的 var 与 Nginx 内部自身变量命名是保持一致,所以也可以使用 request_urihost 等。更多细节请参考lua-resty-expr
filter_func 可选 匹配规则 用户自定义的过滤函数。可以使用它来实现特殊场景的匹配要求实现。该函数默认接受一个名为 vars 的输入参数,可以用它来获取 Nginx 变量。 function(vars) return vars["arg_name"] == "json" end
labels 可选 匹配规则 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
timeout 可选 辅助 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。这个配置将会覆盖在 upstream 中 配置的 timeout 选项 {"connect": 3, "send": 3, "read": 3}
enable_websocket 可选 辅助 是否启用 websocket(boolean), 缺省 false
status 可选 辅助 是否启用此路由,缺省 1 1 表示启用,0 表示禁用
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670

有两点需要特别注意:

  • 对于同一类参数比如 uriurisupstreamupstream_idhosthostsremote_addrremote_addrs 等,是不能同时存在,二者只能选择其一。如果同时启用,接口会报错。
  • vars 中,当获取 cookie 的值时cookie name 是区分大小写字母的。例如:var 等于 "cookie_x_foo" 与 var 等于 "cookie_X_Foo" 表示不同的 cookie

route 对象 json 配置内容:

{
    "id": "1",                            # id非必填
    "uris": ["/a","/b"],                  # 一组 URL 路径
    "methods": ["GET","POST"],            # 可以填多个方法
    "hosts": ["a.com","b.com"],           # 一组 host 域名
    "plugins": {},                        # 指定 route 绑定的插件
    "priority": 0,                        # apisix 支持多种匹配方式,可能会在一次匹配中同时匹配到多条路由,此时优先级高的优先匹配中
    "name": "路由 xxx",
    "desc": "hello world",
    "remote_addrs": ["127.0.0.1"],        # 一组客户端请求 IP 地址
    "vars": [["http_user", "==", "ios"]], # 由一个或多个 [var, operator, val] 元素组成的列表
    "upstream_id": "1",                   # upstream 对象在 etcd 中的 id ,建议使用此值
    "upstream": {},                       # upstream 信息对象,建议尽量不要使用
    "timeout": {                          # 为 route 设置 upstream 的连接、发送消息、接收消息的超时时间。
        "connect": 3,
        "send": 3,
        "read": 3
    },
    "filter_func": "",                    # 用户自定义的过滤函数,非必填
}

具体示例:

# 创建一个路由
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "uri": "/index.html",
    "hosts": ["foo.com", "*.bar.com"],
    "remote_addrs": ["127.0.0.0/8"],
    "methods": ["PUT", "GET"],
    "enable_websocket": true,
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
...

# 创建一个有效期为 60 秒的路由,过期后自动删除
$ curl http://127.0.0.1:9080/apisix/admin/routes/2?ttl=60 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "uri": "/aa/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
...


# 给路由增加一个 upstream node
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 1
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}


# 给路由更新一个 upstream node 的权重
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 10
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给路由删除一个 upstream node
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": null
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1981": 10
}


# 替换路由的 methods -- 数组
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '{
    "methods": ["GET", "POST"]
}'
HTTP/1.1 200 OK
...

执行成功后methods 将不保留原来的数据,整个更新为:
["GET", "POST"]


# 替换路由的 upstream nodes -- sub path
$ curl http://127.0.0.1:9080/apisix/admin/routes/1/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'
HTTP/1.1 200 OK
...

执行成功后nodes 将不保留原来的数据,整个更新为:
{
    "127.0.0.1:1982": 1
}


# 替换路由的 methods  -- sub path
$ curl http://127.0.0.1:9080/apisix/admin/routes/1/methods -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '["POST", "DELETE", "PATCH"]'
HTTP/1.1 200 OK
...

执行成功后methods 将不保留原来的数据,整个更新为:
["POST", "DELETE", "PATCH"]


# 禁用路由
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "status": 0
}'
HTTP/1.1 200 OK
...

执行成功后status 将更新为:
{
    "status": 0
}


# 启用路由
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "status": 1
}'
HTTP/1.1 200 OK
...

执行成功后status 将更新为:
{
    "status": 1
}


应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

Service

地址/apisix/admin/services/{id}

说明Service 是某类 API 的抽象(也可以理解为一组 Route 的抽象)。它通常与上游服务抽象是一一对应的,RouteService 之间,通常是 N:1 的关系。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/services 获取资源列表
GET /apisix/admin/services/{id} 获取资源
PUT /apisix/admin/services/{id} {...} 根据 id 创建资源
POST /apisix/admin/services {...} 创建资源id 由后台服务自动生成
DELETE /apisix/admin/services/{id} 删除资源
PATCH /apisix/admin/services/{id} {...} 标准 PATCH ,修改已有 Service 的部分属性,其他不涉及的属性会原样保留;如果你要删除某个属性,将该属性的值设置为 null 即可删除;特别地,当需要修改属性的值为数组时,该属性将全量更新
PATCH /apisix/admin/services/{id}/{path} {...} SubPath PATCH通过 {path} 指定 Service 需要更新的属性,全量更新该属性的数据,其他不涉及的属性会原样保留

body 请求参数

名字 可选项 类型 说明 示例
plugins 可选 Plugin 详见 Plugin
upstream upstream 或 upstream_id 两个选一个 Upstream 启用的 Upstream 配置,详见 Upstream
upstream_id upstream 或 upstream_id 两个选一个 Upstream 启用的 upstream id详见 Upstream
name 可选 辅助 标识服务名称。
desc 可选 辅助 服务描述、使用场景等。
labels 可选 匹配规则 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
enable_websocket 可选 辅助 是否启用 websocket(boolean), 缺省 false.
hosts 可选 匹配规则 非空列表形态的 host,表示允许有多个不同 host,匹配其中任意一个即可。 ["foo.com", "*.bar.com"]
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670

service 对象 json 配置内容:

{
    "id": "1",                # id
    "plugins": {},            # 指定 service 绑定的插件
    "upstream_id": "1",       # upstream 对象在 etcd 中的 id ,建议使用此值
    "upstream": {},           # upstream 信息对象,不建议使用
    "name": "test svc",       # service 名称
    "desc": "hello world",    # service 描述
    "enable_websocket": true, # 启动 websocket 功能
    "hosts": ["foo.com"]
}

具体示例:

# 创建一个 Service
$ curl http://127.0.0.1:9080/apisix/admin/services/201  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    },
    "enable_websocket": true,
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

# 返回结果

HTTP/1.1 201 Created
...


# 给 Service 增加一个 upstream node
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 1
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}


# 给 Service 更新一个 upstream node 的权重
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1981": 10
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给 Service 删除一个 upstream node
$ curl http://127.0.0.1:9080/apisix/admin/services/201 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": null
        }
    }
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将更新为:
{
    "127.0.0.1:1981": 10
}


# 替换 Service 的 upstream nodes
$ curl http://127.0.0.1:9080/apisix/admin/services/201/upstream/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'
HTTP/1.1 200 OK
...

执行成功后upstream nodes 将不保留原来的数据,整个更新为:
{
    "127.0.0.1:1982": 1
}

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

Consumer

地址/apisix/admin/consumers/{username}

说明Consumer 是某类服务的消费者需与用户认证体系配合才能使用。Consumer 使用 username 作为唯一标识,只支持使用 HTTP PUT 方法创建 Consumer。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/consumers 获取资源列表
GET /apisix/admin/consumers/{id} 获取资源
PUT /apisix/admin/consumers {...} 创建资源
DELETE /apisix/admin/consumers/{id} 删除资源

body 请求参数

名字 可选项 类型 说明 示例
username 必需 辅助 Consumer 名称。
plugins 可选 Plugin 该 Consumer 对应的插件配置它的优先级是最高的Consumer > Route > Service。对于具体插件配置可以参考 Plugins 章节。
desc 可选 辅助 consumer 描述
labels 可选 匹配规则 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670

consumer 对象 json 配置内容:

{
    "plugins": {},          # 指定 consumer 绑定的插件
    "username": "name",     # 必填
    "desc": "hello world",  # consumer 描述
}

绑定认证插件有些特别,当它需要与 consumer 联合使用时,需要提供用户名、密码等信息;另一方面,当它与 route/service 绑定时,是不需要任何参数的。因为这时候是根据用户请求数据来反向推出用户对应的是哪个 consumer

示例:

# 创建 Consumer ,指定认证插件 key-auth ,并开启特定插件 limit-count
$ curl http://127.0.0.1:9080/apisix/admin/consumers  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "username": "jack",
    "plugins": {
        "key-auth": {
            "key": "auth-one"
        },
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    }
}'
HTTP/1.1 200 OK
Date: Thu, 26 Dec 2019 08:17:49 GMT
...

{"node":{"value":{"username":"jack","plugins":{"key-auth":{"key":"auth-one"},"limit-count":{"time_window":60,"count":2,"rejected_code":503,"key":"remote_addr","policy":"local"}}},"createdIndex":64,"key":"\/apisix\/consumers\/jack","modifiedIndex":64},"prevNode":{"value":"{\"username\":\"jack\",\"plugins\":{\"key-auth\":{\"key\":\"auth-one\"},\"limit-count\":{\"time_window\":60,\"count\":2,\"rejected_code\":503,\"key\":\"remote_addr\",\"policy\":\"local\"}}}","createdIndex":63,"key":"\/apisix\/consumers\/jack","modifiedIndex":63},"action":"set"}

v2.2 版本之后,同一个 consumer 可以绑定多个认证插件。

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

Upstream

地址/apisix/admin/upstreams/{id}

说明Upstream 是虚拟主机抽象对给定的多个服务节点按照配置规则进行负载均衡。Upstream 的地址信息可以直接配置到 Route(或 Service) 上,当 Upstream 有重复时,就需要用“引用”方式避免重复了。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/upstreams 获取资源列表
GET /apisix/admin/upstreams/{id} 获取资源
PUT /apisix/admin/upstreams/{id} {...} 根据 id 创建资源
POST /apisix/admin/upstreams {...} 创建资源id 由后台服务自动生成
DELETE /apisix/admin/upstreams/{id} 删除资源
PATCH /apisix/admin/upstreams/{id} {...} 标准 PATCH ,修改已有 Upstream 的部分属性,其他不涉及的属性会原样保留;如果你要删除某个属性,将该属性的值设置为 null 即可删除;特别地,当需要修改属性的值为数组时,该属性将全量更新
PATCH /apisix/admin/upstreams/{id}/{path} {...} SubPath PATCH通过 {path} 指定 Upstream 需要更新的属性,全量更新该属性的数据,其他不涉及的属性会原样保留。

body 请求参数

APISIX 的 Upstream 除了基本的负载均衡算法选择外,还支持对上游做主被动健康检查、重试等逻辑,具体看下面表格。

名字 可选项 类型 说明 示例
type 必需 枚举 负载均衡算法
nodes 必需,不能和 service_name 一起用 Node 哈希表或数组。当它是哈希表时,内部元素的 key 是上游机器地址列表,格式为地址 +(可选的)端口,其中地址部分可以是 IP 也可以是域名,比如 192.168.1.100:80foo.com:80等。value 则是节点的权重。当它是数组时,数组中每个元素都是一个哈希表,其中包含 hostweight 以及可选的 portprioritynodes 可以为空,这通常用作占位符。客户端命中这样的上游会返回 502。 192.168.1.100:80
service_name 必需,不能和 nodes 一起用 string 服务发现时使用的服务名,见集成服务发现注册中心 a-bootiful-client
discovery_type 必需,如果设置了 service_name string 服务发现类型,见 集成服务发现注册中心 eureka
key 条件必需 匹配类型 该选项只有类型是 chash 才有效。根据 key 来查找对应的 node id,相同的 key 在同一个对象中,永远返回相同 id目前支持的 Nginx 内置变量有 uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***,其中 arg_*** 是来自 URL 的请求参数,Nginx 变量列表
checks 可选 health_checker 配置健康检查的参数,详细可参考health-check
retries 可选 整型 使用底层的 Nginx 重试机制将请求传递给下一个上游,默认启用重试且次数为后端可用的 node 数量。如果指定了具体重试次数,它将覆盖默认值。0 代表不启用重试机制。
retry_timeout 可选 number 限制是否继续重试的时间,若之前的请求和重试请求花费太多时间就不再继续重试。0 代表不启用重试超时机制。
timeout 可选 超时时间对象 设置连接、发送消息、接收消息的超时时间
hash_on 可选 辅助 hash_on 支持的类型有 varsNginx 内置变量),header(自定义 headercookieconsumer,默认值为 vars
name 可选 辅助 标识上游服务名称、使用场景等。
desc 可选 辅助 上游服务描述、使用场景等。
pass_host 可选 枚举 请求发给上游时的 host 设置选型。 [passnoderewrite] 之一,默认是passpass: 将客户端的 host 透传给上游; node: 使用 upstream node 中配置的 host rewrite: 使用配置项 upstream_host 的值。
upstream_host 可选 辅助 指定上游请求的 host只在 pass_host 配置为 rewrite 时有效。
scheme 可选 辅助 跟上游通信时使用的 scheme。对于 7 层代理,需要是 ['http', 'https', 'grpc', 'grpcs'] 其中的一个。对于 4 层代理,需要是 ['tcp', 'udp', 'tls'] 其中的一个。默认是 'http'。细节见下文。
labels 可选 匹配规则 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
tls.client_cert 可选 https 证书 设置跟上游通信时的客户端证书,细节见下文
tls.client_key 可选 https 证书私钥 设置跟上游通信时的客户端私钥,细节见下文
keepalive_pool.size 可选 辅助 动态设置 keepalive 指令,细节见下文
keepalive_pool.idle_timeout 可选 辅助 动态设置 keepalive_timeout 指令,细节见下文
keepalive_pool.requests 可选 辅助 动态设置 keepalive_requests 指令,细节见下文

type 可以是以下的一种:

  • roundrobin: 带权重的 roundrobin
  • chash: 一致性哈希
  • ewma: 选择延迟最小的节点,计算细节参考 https://en.wikipedia.org/wiki/EWMA_chart
  • least_conn: 选择 (active_conn + 1) / weight 最小的节点。注意这里的 active connection 概念跟 Nginx 的相同:它是当前正在被请求使用的连接。
  • 用户自定义的 balancer需要可以通过 require("apisix.balancer.your_balancer") 来加载。

hash_on 比较复杂,这里专门说明下:

  1. 设为 vars 时,key 为必传参数,目前支持的 Nginx 内置变量有 uri, server_name, server_addr, request_uri, remote_port, remote_addr, query_string, host, hostname, arg_***,其中 arg_*** 是来自 URL 的请求参数,Nginx 变量列表
  2. 设为 header 时,key 为必传参数,其值为自定义的 header name即 "http_key"
  3. 设为 cookie 时,key 为必传参数,其值为自定义的 cookie name即 "cookie_key"。请注意 cookie name 是区分大小写字母的。例如:"cookie_x_foo" 与 "cookie_X_Foo" 表示不同的 cookie
  4. 设为 consumer 时,key 不需要设置。此时哈希算法采用的 key 为认证通过的 consumer_name
  5. 如果指定的 hash_onkey 获取不到值时,就是用默认值:remote_addr

以下特性需要 APISIX 运行于 APISIX-OpenResty

scheme 可以设置成 tls,表示 "TLS over TCP"。

tls.client_cert/key 可以用来跟上游进行 mTLS 通信。 他们的格式和 SSL 对象的 certkey 一样。

keepalive_pool 允许 upstream 对象有自己单独的连接池。 它下属的字段,比如 requests,可以用了配置上游连接保持的参数。 这个特性需要 APISIX 运行于 APISIX-OpenResty

upstream 对象 json 配置内容:

{
    "id": "1",                  # id
    "retries": 1,               # 请求重试次数
    "timeout": {                # 设置连接、发送消息、接收消息的超时时间
        "connect":15,
        "send":15,
        "read":15,
    },
    "nodes": {"host:80": 100},  # 上游机器地址列表,格式为`地址 + 端口`
                                # 等价于 "nodes": [ {"host":"host", "port":80, "weight": 100} ],
    "type":"roundrobin",
    "checks": {},               # 配置健康检查的参数
    "hash_on": "",
    "key": "",
    "name": "upstream-xxx",     # upstream 名称
    "desc": "hello world",      # upstream 描述
    "scheme": "http"            # 跟上游通信时使用的 scheme默认是 `http`
}

具体示例:

示例一:创建一个 upstream 并对 nodes 的数据做修改

# 创建一个 upstream
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
    "type":"roundrobin",
    "nodes":{
        "127.0.0.1:1980": 1
    }
}'
HTTP/1.1 201 Created
...


# 给 Upstream 增加一个 node
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1981": 1
    }
}'
HTTP/1.1 200 OK
...

执行成功后nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 1
}


# 给 Upstream 更新一个 node 的权重
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1981": 10
    }
}'
HTTP/1.1 200 OK
...

执行成功后nodes 将更新为:
{
    "127.0.0.1:1980": 1,
    "127.0.0.1:1981": 10
}


# 给 Upstream 删除一个 node
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "nodes": {
        "127.0.0.1:1980": null
    }
}'
HTTP/1.1 200 OK
...

执行成功后nodes 将更新为:
{
    "127.0.0.1:1981": 10
}


# 替换 Upstream 的  nodes
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/100/nodes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -i -d '
{
    "127.0.0.1:1982": 1
}'
HTTP/1.1 200 OK
...

执行成功后nodes 将不保留原来的数据,整个更新为:
{
    "127.0.0.1:1982": 1
}

示例二:将客户端请求代理到上游 https 服务

1、创建 route 并配置 upstream 的 scheme 为 https

$ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/get",
    "upstream": {
        "type": "roundrobin",
        "scheme": "https",
        "nodes": {
            "httpbin.org:443": 1
        }
    }
}'

执行成功后,请求与上游通信时的 scheme 将为 https

2、 发送请求进行测试。

$ curl http://127.0.0.1:9080/get
{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/7.29.0",
    "X-Amzn-Trace-Id": "Root=1-6058324a-0e898a7f04a5e95b526bb183",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "origin": "127.0.0.1",
  "url": "https://127.0.0.1/get"
}

请求成功,表示代理上游 https 生效了。

注意:

节点可以配置自己的优先级。只有在高优先级的节点不可用或者尝试过,才会访问一个低优先级的节点。

由于默认的优先级是 0我们可以给一些节点配置负数的优先级来作为备份。 举个例子:

{
    "uri": "/hello",
    "upstream": {
        "type": "roundrobin",
        "nodes": [
            {"host": "127.0.0.1", "port": 1980, "weight": 2000},
            {"host": "127.0.0.1", "port": 1981, "weight": 1, "priority": -1}
        ],
        "checks": {
            "active": {
                "http_path": "/status",
                "healthy": {
                    "interval": 1,
                    "successes": 1
                },
                "unhealthy": {
                    "interval": 1,
                    "http_failures": 1
                }
            }
        }
    }
}

节点 127.0.0.2 只有在 127.0.0.1 不可用或者尝试过之后才会被访问。 所以它是 127.0.0.1 的备份。

应答参数

目前是直接返回与 etcd 交互后的结果。

Back to TOC

SSL

地址/apisix/admin/ssl/{id}

说明SSL.

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/ssl 获取资源列表
GET /apisix/admin/ssl/{id} 获取资源
PUT /apisix/admin/ssl/{id} {...} 根据 id 创建资源
POST /apisix/admin/ssl {...} 创建资源id 由后台服务自动生成
DELETE /apisix/admin/ssl/{id} 删除资源

body 请求参数

名字 可选项 类型 说明 示例
cert 必需 证书 https 证书
key 必需 私钥 https 证书私钥
certs 可选 证书字符串数组 当你想给同一个域名配置多个证书时,除了第一个证书需要通过 cert 传递外,剩下的证书可以通过该参数传递上来
keys 可选 私钥字符串数组 certs 对应的证书私钥,注意要跟 certs 一一对应
client.ca 可选 证书 设置将用于客户端证书校验的 CA 证书。该特性需要 OpenResty 1.19+
client.depth 可选 辅助 设置客户端证书校验的深度,默认为 1。该特性需要 OpenResty 1.19+
snis 必需 匹配规则 非空数组形式,可以匹配多个 SNI
labels 可选 匹配规则 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
status 可选 辅助 是否启用此 SSL缺省 1 1 表示启用,0 表示禁用

ssl 对象 json 配置内容:

{
    "id": "1",          # id
    "cert": "cert",     # 证书
    "key": "key",       # 私钥
    "snis": ["t.com"]   # HTTPS 握手时客户端发送的 SNI
}

更多的配置示例见 证书

Back to TOC

Global Rule

地址/apisix/admin/global_rules/{id}

说明:设置全局运行的插件。这一类插件在所有路由级别的插件之前优先运行。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/global_rules 获取资源列表
GET /apisix/admin/global_rules/{id} 获取资源
PUT /apisix/admin/global_rules/{id} {...} 根据 id 创建资源
DELETE /apisix/admin/global_rules/{id} 删除资源
PATCH /apisix/admin/global_rules/{id} {...} 标准 PATCH ,修改已有 Global Rule 的部分属性,其他不涉及的属性会原样保留;如果你要删除某个属性,将该属性的值设置为 null 即可删除;特别地,当需要修改属性的值为数组时,该属性将全量更新
PATCH /apisix/admin/global_rules/{id}/{path} {...} SubPath PATCH通过 {path} 指定 Global Rule 要更新的属性,全量更新该属性的数据,其他不涉及的属性会原样保留。

body 请求参数

名字 可选项 类型 说明 示例
plugins 必需 Plugin 详见 Plugin
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670

Back to TOC

Plugin Config

地址/apisix/admin/plugin_configs/{id}

说明:配置一组可以在路由间复用的插件。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/plugin_configs 获取资源列表
GET /apisix/admin/plugin_configs/{id} 获取资源
PUT /apisix/admin/plugin_configs/{id} {...} 根据 id 创建资源
DELETE /apisix/admin/plugin_configs/{id} 删除资源
PATCH /apisix/admin/plugin_configs/{id} {...} 标准 PATCH ,修改已有 Plugin Config 的部分属性,其他不涉及的属性会原样保留;如果你要删除某个属性,将该属性的值设置为 null 即可删除;特别地,当需要修改属性的值为数组时,该属性将全量更新
PATCH /apisix/admin/plugin_configs/{id}/{path} {...} SubPath PATCH通过 {path} 指定 Plugin Config 要更新的属性,全量更新该属性的数据,其他不涉及的属性会原样保留。

body 请求参数

名字 可选项 类型 说明 示例
plugins 必需 Plugin 详见 Plugin
desc 可选 辅助 标识描述、使用场景等 customer xxxx
labels 可选 辅助 标识附加属性的键值对 {"version":"v2","build":"16","env":"production"}
create_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670
update_time 可选 辅助 单位为秒的 epoch 时间戳,如果不指定则自动创建 1602883670

Back to TOC

Plugin Metadata

地址/apisix/admin/plugin_metadata/{plugin_name}

说明: 插件元数据。

请求方法

Method 请求 URI 请求 body 说明
GET /apisix/admin/plugin_metadata/{plugin_name} 获取资源
PUT /apisix/admin/plugin_metadata/{plugin_name} {...} 根据 plugin name 创建资源
DELETE /apisix/admin/plugin_metadata/{plugin_name} 删除资源

body 请求参数

一个根据插件 ({plugin_name}) 的 metadata_schema 定义的数据结构的 json object 。

例子:

$ curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/example-plugin  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
{
    "skey": "val",
    "ikey": 1
}'
HTTP/1.1 201 Created
Date: Thu, 26 Dec 2019 04:19:34 GMT
Content-Type: text/plain

Back to TOC

Plugin

地址/apisix/admin/plugins/{plugin_name}

说明:  插件

请求方法

名字        请求  uri 请求  body 说明         
GET       /apisix/admin/plugins/list 获取资源列表
GET       /apisix/admin/plugins/{plugin_name} 获取资源
GET /apisix/admin/plugins?all=true 获取所有插件的所有属性

body 请求参数

获取插件  ({plugin_name})  数据结构的  json object 。

例子:

$ curl "http://127.0.0.1:9080/apisix/admin/plugins/list" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
["zipkin","request-id",...]

$ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
{"properties":{"disable":{"type":"boolean"}},"additionalProperties":false,"type":"object"}

地址/apisix/admin/plugins?all=true

说明: 所有插件的所有属性,每个插件包括 name, priority, type, schema, consumer_schemaversion

默认情况下,这个接口只返回 http 插件。如果你需要 stream 插件,需要用 /apisix/admin/plugins?all=true&subsystem=stream

请求方法

Method 请求 URI 请求 body 说明
GET /apisix/admin/plugins?all=true 获取资源

请求参数

名称 说明 默认
subsystem 插件所属的子系统 http

Back to TOC

Stream Route

API/apisix/admin/stream_routes/{id}

DescriptionStream Route 是用于 TCP/UDP 动态代理的路由。参见 TCP/UDP 动态代理 一节。

请求方法

名字 请求 uri 请求 body 说明
GET /apisix/admin/stream_routes 获取资源列表
GET /apisix/admin/stream_routes/{id} 获取资源
PUT /apisix/admin/stream_routes/{id} {...} 根据 id 创建资源
POST /apisix/admin/stream_routes {...} 创建资源id 由后台服务自动生成
DELETE /apisix/admin/stream_routes/{id} 删除资源

body 请求参数

名字 可选项 类型 说明 示例
upstream 可选 Upstream 启用的 Upstream 配置,详见 Upstream
upstream_id 可选 Upstream 启用的 upstream id详见 Upstream
remote_addr 可选 IP/CIDR 过滤选项:如果客户端 IP 匹配,则转发到上游 "127.0.0.1/32" 或 "127.0.0.1"
server_addr 可选 IP/CIDR 过滤选项:如果 APISIX 服务器 IP 与 server_addr 匹配,则转发到上游 "127.0.0.1/32" 或 "127.0.0.1"
server_port 可选 整数 过滤选项:如果 APISIX 服务器 port 与 server_port 匹配,则转发到上游 9090
sni 可选 Host 服务器名称指示 "test.com"

点击 此处,了解更多有关过滤器如何工作的信息。

Back to TOC