APISIX

插件加载流程

插件加载流程

插件内部结构

动态负载均衡 - 图2

APISIX Config

通过修改本地 conf/config.yaml 文件完成对 APISIX 服务本身的基本配置。

  1. apisix:
  2. node_listen: 9080 # APISIX listening port
  3. etcd:
  4. host: "http://127.0.0.1:2379" # etcd address
  5. prefix: "apisix" # apisix configurations prefix
  6. timeout: 60
  7. plugins: # plugin name list
  8. - example-plugin
  9. - limit-req
  10. - limit-count
  11. - ...

注意 不要手工修改 APISIX 自身的 conf/nginx.conf 文件,当服务每次启动时,apisix 会根据 conf/config.yaml 配置自动生成新的 conf/nginx.conf 并自动启动服务。

返回目录

Route

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

Route 中主要包含三部分内容:匹配规则(比如 uri、host、remote_addr 等),插件配置(限流限速等)和上游信息。 请看下图示例,是一些 Route 规则的实例,当某些属性值相同时,图中用相同颜色标识。

动态负载均衡 - 图3

我们直接在 Route 中完成所有参数的配置,优点是容易设置,每个 Route 都相对独立自由度比较高。但当我们的 Route 有比较多的重复配置(比如启用相同的插件配置或上游信息),一旦我们要更新这些相同属性时,就需要遍历所有 Route 并进行修改,给后期管理维护增加不少复杂度。

上面提及重复的缺点在 APISIX 中独立抽象了 ServiceUpstream 两个概念来解决。

下面创建的 Route 示例,是把 URL 为 “/index.html” 的请求代理到地址为 “39.97.63.215:80” 的 Upstream 服务:

  1. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
  2. {
  3. "uri": "/index.html",
  4. "upstream": {
  5. "type": "roundrobin",
  6. "nodes": {
  7. "39.97.63.215:80": 1
  8. }
  9. }
  10. }'
  11. HTTP/1.1 201 Created
  12. Date: Sat, 31 Aug 2019 01:17:15 GMT
  13. Content-Type: text/plain
  14. Transfer-Encoding: chunked
  15. Connection: keep-alive
  16. Server: APISIX web server
  17. {"node":{"value":{"uri":"\/index.html","upstream":{"nodes":{"39.97.63.215:80":1},"type":"roundrobin"}},"createdIndex":61925,"key":"\/apisix\/routes\/1","modifiedIndex":61925},"action":"create"}

当我们接收到成功应答,表示该 Route 已成功创建。

有关 Route 的具体选项,可具体查阅 Admin API 之 Route

返回目录

Service

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

动态负载均衡 - 图4

不同 Route 规则同时绑定到一个 Service 上,这些 Route 将具有相同的上游和插件配置,减少冗余配置。

比如下面的例子,创建了一个启用限流插件的 Service,然后把 id 为 100101 的 Route 都绑定在这个 Service 上。

  1. # create new Service
  2. $ curl http://127.0.0.1:9080/apisix/admin/services/200 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "plugins": {
  5. "limit-count": {
  6. "count": 2,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr"
  10. }
  11. },
  12. "upstream": {
  13. "type": "roundrobin",
  14. "nodes": {
  15. "39.97.63.215:80": 1
  16. }
  17. }
  18. }'
  19. # create new Route and reference the service by id `200`
  20. curl http://127.0.0.1:9080/apisix/admin/routes/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  21. {
  22. "methods": ["GET"],
  23. "uri": "/index.html",
  24. "service_id": "200"
  25. }'
  26. curl http://127.0.0.1:9080/apisix/admin/routes/101 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  27. {
  28. "methods": ["GET"],
  29. "uri": "/foo/index.html",
  30. "service_id": "200"
  31. }'

当然我们也可以为 Route 指定不同的插件参数或上游,比如下面这个 Route 设置了不同的限流参数,其他部分(比如上游)则继续使用 Service 中的配置参数。

  1. curl http://127.0.0.1:9080/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/bar/index.html",
  4. "id": "102",
  5. "service_id": "200",
  6. "plugins": {
  7. "limit-count": {
  8. "count": 2000,
  9. "time_window": 60,
  10. "rejected_code": 503,
  11. "key": "remote_addr"
  12. }
  13. }
  14. }'

注意:当 Route 和 Service 都开启同一个插件时,Route 参数的优先级是高于 Service 的。

返回目录

Plugin

Plugin 表示将在 HTTP 请求/响应生命周期期间执行的插件配置。

Plugin 配置可直接绑定在 Route 上,也可以被绑定在 ServiceConsumer上。而对于同一 个插件的配置,只能有一份是有效的,配置选择优先级总是 Consumer > Route > Service

conf/config.yaml 中,可以声明本地 APISIX 节点都支持哪些插件。这是个白名单机制,不在该 白名单的插件配置,都将会被自动忽略。这个特性可用于临时关闭或打开特定插件,应对突发情况非常有效。

插件的配置可以被直接绑定在指定 Route 中,也可以被绑定在 Service 中,不过 Route 中的插件配置 优先级更高。

一个插件在一次请求中只会执行一次,即使被同时绑定到多个不同对象中(比如 Route 或 Service)。 插件运行先后顺序是根据插件自身的优先级来决定的,例如:example-plugin

插件配置作为 Route 或 Service 的一部分提交的,放到 plugins 下。它内部是使用插件 名字作为哈希的 key 来保存不同插件的配置项。

  1. {
  2. ...
  3. "plugins": {
  4. "limit-count": {
  5. "count": 2,
  6. "time_window": 60,
  7. "rejected_code": 503,
  8. "key": "remote_addr"
  9. },
  10. "prometheus": {}
  11. }
  12. }

并不是所有插件都有具体配置项,比如 prometheus 下是没有任何具体配置项,这时候用一个空的对象 标识即可。

查看 APISIX 已支持插件列表

返回目录

Script

Script 表示将在 HTTP 请求/响应生命周期期间执行的脚本。

Script 配置可直接绑定在 Route 上。

ScriptPlugin 互斥,且优先执行 Script ,这意味着配置 Script 后,Route 上配置的 Plugin 将不被执行。

理论上,在 Script 中可以写任意 lua 代码,也可以直接调用已有插件以重用已有的代码。

Script 也有执行阶段概念,支持 accessheader_filerbody_filterlog 阶段。系统会在相应阶段中自动执行 Script 脚本中对应阶段的代码。

  1. {
  2. ...
  3. "script": "local _M = {} \n function _M.access(api_ctx) \n ngx.log(ngx.INFO,\"hit access phase\") \n end \nreturn _M"
  4. }

返回目录

Upstream

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

动态负载均衡 - 图5

如上图所示,通过创建 Upstream 对象,在 Route 用 ID 方式引用,就可以确保只维护一个对象的值了。

Upstream 的配置可以被直接绑定在指定 Route 中,也可以被绑定在 Service 中,不过 Route 中的配置 优先级更高。这里的优先级行为与 Plugin 非常相似

配置参数

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

名字可选说明
type必填roundrobin 支持权重的负载,chash 一致性哈希,两者是二选一的
nodesk8s_deployment_infoservice_name 三选一哈希表,内部元素的 key 是上游机器地址列表,格式为地址 + Port,其中地址部分可以是 IP 也可以是域名,比如 192.168.1.100:80foo.com:80 等。value 则是节点的权重。当权重值为 0 代表该上游节点失效,不会被选中,可以用于暂时摘除节点的情况。
service_namenodesk8s_deployment_info 三选一用于设置上游服务名,并配合注册中心使用,详细可参考集成服务发现注册中心
k8s_deployment_infonodesservice_name 三选一哈希表
key可选type 等于 chash 是必选项。 key 需要配合 hash_on 来使用,通过 hash_onkey 来查找对应的 node id
hash_on可选hash_on 支持的类型有 vars(Nginx内置变量),header(自定义header),cookieconsumer,默认值为 vars
checks可选配置健康检查的参数,详细可参考health-check
retries可选使用底层的 Nginx 重试机制将请求传递给下一个上游,默认 APISIX 会启用重试机制,根据配置的后端节点个数设置重试次数,如果此参数显式被设置将会覆盖系统默认设置的重试次数。
enable_websocket可选是否启用 websocket(布尔值),默认不启用

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
  4. 设为 consumer 时,key 不需要设置。此时哈希算法采用的 key 为认证通过的 consumer_id
  5. 如果指定的 hash_onkey 获取不到值时,就是用默认值:remote_addr

创建上游对象用例:

  1. curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "type": "roundrobin",
  4. "k8s_deployment_info": {
  5. "namespace": "test-namespace",
  6. "deploy_name": "test-deploy-name",
  7. "service_name": "test-service-name",
  8. "backend_type": "pod",
  9. "port": 8080
  10. }
  11. }'
  12. curl http://127.0.0.1:9080/apisix/admin/upstreams/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  13. {
  14. "type": "chash",
  15. "key": "remote_addr",
  16. "enable_websocket": true,
  17. "nodes": {
  18. "127.0.0.1:80": 1,
  19. "foo.com:80": 2
  20. }
  21. }'

上游对象创建后,均可以被具体 RouteService 引用,例如:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/index.html",
  4. "upstream_id": 2
  5. }'

为了方便使用,也可以直接把上游地址直接绑到某个 RouteService ,例如:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/index.html",
  4. "plugins": {
  5. "limit-count": {
  6. "count": 2,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr"
  10. }
  11. },
  12. "upstream": {
  13. "type": "roundrobin",
  14. "nodes": {
  15. "39.97.63.215:80": 1
  16. }
  17. }
  18. }'

下面是一个配置了健康检查的示例:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/index.html",
  4. "plugins": {
  5. "limit-count": {
  6. "count": 2,
  7. "time_window": 60,
  8. "rejected_code": 503,
  9. "key": "remote_addr"
  10. }
  11. },
  12. "upstream": {
  13. "nodes": {
  14. "39.97.63.215:80": 1
  15. }
  16. "type": "roundrobin",
  17. "retries": 2,
  18. "checks": {
  19. "active": {
  20. "http_path": "/status",
  21. "host": "foo.com",
  22. "healthy": {
  23. "interval": 2,
  24. "successes": 1
  25. },
  26. "unhealthy": {
  27. "interval": 1,
  28. "http_failures": 2
  29. }
  30. }
  31. }
  32. }
  33. }'

更多细节可以参考健康检查的文档

下面是几个使用不同hash_on类型的配置示例:

Consumer

创建一个consumer对象:

  1. curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "username": "jack",
  4. "plugins": {
  5. "key-auth": {
  6. "key": "auth-jack"
  7. }
  8. }
  9. }'

新建路由,打开key-auth插件认证,upstreamhash_on类型为consumer

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "plugins": {
  4. "key-auth": {}
  5. },
  6. "upstream": {
  7. "nodes": {
  8. "127.0.0.1:1980": 1,
  9. "127.0.0.1:1981": 1
  10. },
  11. "type": "chash",
  12. "hash_on": "consumer"
  13. },
  14. "uri": "/server_port"
  15. }'

测试请求,认证通过后的consumer_id将作为负载均衡哈希算法的哈希值:

  1. curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
Cookie

新建路由和Upstreamhash_on类型为cookie

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/hash_on_cookie",
  4. "upstream": {
  5. "key": "sid",
  6. "type ": "chash",
  7. "hash_on ": "cookie",
  8. "nodes ": {
  9. "127.0.0.1:1980": 1,
  10. "127.0.0.1:1981": 1
  11. }
  12. }
  13. }'

客户端请求携带Cookie

  1. curl http://127.0.0.1:9080/hash_on_cookie -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Cookie: sid=3c183a30cffcda1408daf1c61d47b274"
Header

新建路由和Upstreamhash_on类型为headerkeycontent-type

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "uri": "/hash_on_header",
  4. "upstream": {
  5. "key": "content-type",
  6. "type ": "chash",
  7. "hash_on ": "header",
  8. "nodes ": {
  9. "127.0.0.1:1980": 1,
  10. "127.0.0.1:1981": 1
  11. }
  12. }
  13. }'

客户端请求携带content-typeheader

  1. curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"

返回目录

Router

APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Router 来更好匹配自由业务,在性能、自由之间做最适合选择。

在本地配置 conf/config.yaml 中设置最符合自身业务需求的路由。

  • apisix.router.http: HTTP 请求路由。

    • radixtree_uri: (默认)只使用 uri 作为主索引。基于 radixtree 引擎,支持全量和深前缀匹配,更多见 如何使用 router-radixtree
      • 绝对匹配:完整匹配给定的 uri ,比如 /foo/bar/foo/glo
      • 前缀匹配:末尾使用 * 代表给定的 uri 是前缀匹配。比如 /foo*,则允许匹配 /foo//foo/a/foo/b等。
      • 匹配优先级:优先尝试绝对匹配,若无法命中绝对匹配,再尝试前缀匹配。
      • 任意过滤属性:允许指定任何 Nginx 内置变量作为过滤条件,比如 URL 请求参数、请求头、cookie 等。
    • radixtree_host_uri: 使用 host + uri 作为主索引(基于 radixtree 引擎),对当前请求会同时匹配 host 和 uri,支持的匹配条件与 radixtree_uri 基本一致。
  • apisix.router.ssl: SSL 加载匹配路由。

    • radixtree_sni: (默认)使用 SNI (Server Name Indication) 作为主索引(基于 radixtree 引擎)。

返回目录

Consumer

对于 API 网关通常可以用请求域名、客户端 IP 地址等字段识别到某类请求方, 然后进行插件过滤并转发请求到指定上游,但有时候这个深度不够。

动态负载均衡 - 图6

如上图所示,作为 API 网关,需要知道 API Consumer(消费方)具体是谁,这样就可以对不同 API Consumer 配置不同规则。

字段必选说明
usernameConsumer 名称。
plugins该 Consumer 对应的插件配置,它的优先级是最高的:Consumer > Route > Service。对于具体插件配置,可以参考 Plugins 章节。

在 APISIX 中,识别 Consumer 的过程如下图:

动态负载均衡 - 图7

  1. 授权认证:比如有 key-authJWT 等。
  2. 获取 consumer_id:通过授权认证,即可自然获取到对应的 Consumer id,它是 Consumer 对象的唯一识别标识。
  3. 获取 Consumer 上绑定的 Plugin 或 Upstream 信息:完成对不同 Consumer 做不同配置的效果。

概括一下,Consumer 是某类服务的消费者,需与用户认证体系配合才能使用。 比如不同的 Consumer 请求同一个 API,网关服务根据当前请求用户信息,对应不同的 Plugin 或 Upstream 配置。

此外,大家也可以参考 key-auth 认证授权插件的调用逻辑,辅助大家来进一步理解 Consumer 概念和使用。

如何对某个 Consumer 开启指定插件,可以看下面例子:

  1. # 创建 Consumer ,指定认证插件 key-auth ,并开启特定插件 limit-count
  2. $ curl http://127.0.0.1:9080/apisix/admin/consumers/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "username": "jack",
  5. "plugins": {
  6. "key-auth": {
  7. "key": "auth-one"
  8. },
  9. "limit-count": {
  10. "count": 2,
  11. "time_window": 60,
  12. "rejected_code": 503,
  13. "key": "remote_addr"
  14. }
  15. }
  16. }'
  17. # 创建 Router,设置路由规则和启用插件配置
  18. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  19. {
  20. "plugins": {
  21. "key-auth": {}
  22. },
  23. "upstream": {
  24. "nodes": {
  25. "127.0.0.1:1980": 1
  26. },
  27. "type": "roundrobin"
  28. },
  29. "uri": "/hello"
  30. }'
  31. # 发测试请求,前两次返回正常,没达到限速阈值
  32. $ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
  33. ...
  34. $ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
  35. ...
  36. # 第三次测试返回 503,请求被限制
  37. $ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
  38. HTTP/1.1 503 Service Temporarily Unavailable
  39. ...

结合 consumer-restriction 插件,限制jack对该 route 的访问

设置黑名单,禁止jack访问该API

  1. $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3. "plugins": {
  4. "key-auth": {},
  5. "consumer-restriction": {
  6. "blacklist": [
  7. "jack"
  8. ]
  9. }
  10. },
  11. "upstream": {
  12. "nodes": {
  13. "127.0.0.1:1980": 1
  14. },
  15. "type": "roundrobin"
  16. },
  17. "uri": "/hello"
  18. }'
  19. # 反复测试,均返回 403,jack被禁止访问
  20. $ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
  21. HTTP/1.1 403
  22. ...

返回目录

Global Rule

Plugin 只能绑定在 Service 或者 Route 上,如果我们需要一个能作用于所有请求的 Plugin 该怎么办呢? 这时候我们可以使用 GlobalRule 来注册一个全局的 Plugin:

  1. curl -X PUT \
  2. https://{apisix_listen_address}/apisix/admin/global_rules/1 \
  3. -H 'Content-Type: application/json' \
  4. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  5. -d '{
  6. "plugins": {
  7. "limit-count": {
  8. "time_window": 60,
  9. "policy": "local",
  10. "count": 2,
  11. "key": "remote_addr",
  12. "rejected_code": 503
  13. }
  14. }
  15. }'

如上所注册的 limit-count 插件将会作用于所有的请求。

我们可以通过以下接口查看所有的 GlobalRule:

  1. curl https://{apisix_listen_address}/apisix/admin/global_rules -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

返回目录

Debug mode

基本调试模式

设置 conf/config.yaml 中的 apisix.enable_debugtrue,即可开启基本调试模式。

比如对 /hello 开启了 limit-connlimit-count插件,这时候应答头中会有 Apisix-Plugins: limit-conn, limit-count

  1. $ curl http://127.0.0.1:1984/hello -i
  2. HTTP/1.1 200 OK
  3. Content-Type: text/plain
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. Apisix-Plugins: limit-conn, limit-count
  7. X-RateLimit-Limit: 2
  8. X-RateLimit-Remaining: 1
  9. Server: openresty
  10. hello world

高级调试模式

设置 conf/debug.yaml 中的选项,开启高级调试模式。由于 APISIX 服务启动后是每秒定期检查该文件, 当可以正常读取到 #END 结尾时,才认为文件处于写完关闭状态。

根据文件最后修改时间判断文件内容是否有变化,如有变化则重新加载,如没变化则跳过本次检查。 所以高级调试模式的开启、关闭都是热更新方式完成。

名字可选项说明默认值
hook_conf.enable必选项是否开启 hook 追踪调试。开启后将打印指定模块方法的请求参数或返回值false
hook_conf.name必选项开启 hook 追踪调试的模块列表名称
hook_conf.log_level必选项打印请求参数和返回值的日志级别warn
hook_conf.is_print_input_args必选项是否打印输入参数true
hook_conf.is_print_return_value必选项是否打印返回值true

请看下面示例:

  1. hook_conf:
  2. enable: false # 是否开启 hook 追踪调试
  3. name: hook_phase # 开启 hook 追踪调试的模块列表名称
  4. log_level: warn # 日志级别
  5. is_print_input_args: true # 是否打印输入参数
  6. is_print_return_value: true # 是否打印返回值
  7. hook_phase: # 模块函数列表,名字:hook_phase
  8. apisix: # 引用的模块名称
  9. - http_access_phase # 函数名:数组
  10. - http_header_filter_phase
  11. - http_body_filter_phase
  12. - http_log_phase
  13. #END

返回目录