Apisix（二） Pluginapisix plugin，apisix插件，apisix 插件优先级，apisix插件

一、前言

Apisix提供了统一网关的能力，但是在实际使用中往往需要更多的功能来满足对于微服务的管控，以及对于流量请求的处理，apisix也提供了很多开箱即用的插件来帮助用户实现这些功能。例如：

身份验证类的插件basic-auth，jwt-auth。
安全防护类的插件cors，csrf。
流量控制类的插件limit- count，limit-req等

通过结合这些插件我们可以很发便做到对于请求的安全性，合法性，访问的合理性进行控制，而不需要再去花费更多精力开发这些插件。

并且除了Apisix内置实现的这些插件之外，apisix也支持用户通过lua，java，go等语言开发符合自己业务场景的插件，从而为请求的处理和控制带来更多的便利性。

二、插件介绍

这里主要介绍关于apisix自带插件的相关信息，关于apisix自定义插件可以参考文章Apisix通过jwt-token + 自定义插件实现ops身份认证（文章以go语言实现插件为例, 稍后发布更新链接）。

对于apisix自带插件均使用lua语言进行开发，插件保存在apisix plugins配置目录下，默认路径为/usr/local/apisix/apisix/plugins

在apisix配置目录下有两个配置文件config-default.yaml和config.yaml，这些文件位于conf目录中。如果两个文件中都存在相同的键 (例如plugins)，则config.yaml文件中该键的配置值将覆盖config-default.yaml文件中的配置值。

在实际使用过程中一般不建议修改config-default.yaml，我们需要配置什么东西直接将配置添加到config.yaml即可生效。

对于内部插件而言均使用lua语言进行开发，插件的执行阶段收到openrestry影响主要包含rewrite, access, before_proxy, header_filter, body_filter, and log。

Openrestry lua脚本指令顺序

对于外部插件通过实现plugin接口从而对于http请求不同阶段进行处理。

三、插件合并顺序

相对于 Route、Service、Plugin Config、Consumer 中的插件配置，Global Rules 中的插件总是优先执行。

apisix中可以在consumer，consumer group，router，plugin config，service中均可以配置插件，如果同一个插件在多个阶段均被配置，那么最终apisix会按照合并优先级对这些配置进行合并。

也就是说如果一个插件在不同的阶段配置不论是否相同，最终高合并优先级的配置都会覆盖低合并优先级的配置。合并优先级按照Consumer > Consumer Group > Route > Plugin Config > Service的顺序进行合并，也就是说consumer的合并优先级是最高的，如果所有阶段均有配置同一个插件，那么最终以consumer的配置为主。

暂时无法在飞书文档外展示此内容

四、插件元数据配置

通过 _meta 配置项可以将一些通用的配置应用于插件，例如：是否启用插件，错误响应，优先级，插件filter。

元数据disable, priority, error_response配置示例，在通过priority配置优先级之后，priority值越高插件越早被执行。

{
    "jwt-auth": {
        "_meta": {
            "disable": true,
            "priority": 10000,
            "error_response": {
                "message": "Missing credential in request"
            }
        }
    }
}

filter控制插件执行条件

通过filter属性控制插件的执行条件，以下配置表示只有当请求中携带参数信息version=2的时候，插件才会执行。

{
    "uri": "/get",
    "plugins": {
        "proxy-rewrite": {
            "_meta": {
                "filter": [
                    ["arg_version", "==", "v2"]
                ]
            },
            "uri": "/anything"
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "httpbin.org:80": 1
        }
    }
}

当请求中不带任何参数时，proxy-rewrite 插件不会执行，请求将被转发到上游的 /get。

curl -v /dev/null http://127.0.0.1:9080/get -H"host:httpbin.org"

< HTTP/1.1 200 OK
......
< Server: APISIX/2.15.0
<
{
"args": {},
"headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.79.1",
    "X-Amzn-Trace-Id": "Root=1-62eb6eec-46c97e8a5d95141e621e07fe",
    "X-Forwarded-Host": "httpbin.org"
},
"origin": "127.0.0.1, 117.152.66.200",
"url": "http://httpbin.org/get"
}

2. 当请求中携带参数 version=v2 时，proxy-rewrite 插件执行，请求将被转发到上游的 /anything:

curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org"

< HTTP/1.1 200 OK
......
< Server: APISIX/2.15.0
<
{
"args": {
    "version": "v2"
},
"data": "",
"files": {},
"form": {},
"headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.79.1",
    "X-Amzn-Trace-Id": "Root=1-62eb6f02-24a613b57b6587a076ef18b4",
    "X-Forwarded-Host": "httpbin.org"
},
"json": null,
"method": "GET",
"origin": "127.0.0.1, 117.152.66.200",
"url": "http://httpbin.org/anything?version=v2"
}

五、热加载

APISIX插件支持热加载，无论是新增、删除还是修改插件，都不需要重启服务。执行下面reload接口即可。

curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT

六、插件配置

插件配置可以理解为是apisix提供的一种对于插件应用的管理，当我们需要配置多个插件到不同路由，或者配置相同的插件到多个路由的时候，我们可以通过定义一个plugin config。然后将plugin config应用到对应的router中即可，而不必将相同的plugin信息和配置填写多次。

创建 Plugin config。

curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "desc": "enable limit-count plugin",
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503
        }
    }
}'

2. 创建路由并绑定 Plugin Config 1。

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
    "uris": ["/index.html"],
   "plugin_config_id": 1, 
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

七、总结

通过本文我们了解到

apisix通过提供_mate属性来对插件的启用，失败返回，优先级，插件执行条件进行控制。
apisix中不同组件配置的插件，会根据合并优先级从高到低进行覆盖，并且不同插件可以通过配置priority调整插件执行顺序。
如果需要对于插件进行统一集中管理的时候，可以结合plugin config来简化配置管理。

Apisix（二） Plugin