apisix~lua插件开发与插件注册

开发插件的步骤

在APISIX中,要自定义插件,一般需要按照以下步骤进行操作:

  1. 编写Lua脚本:首先,你需要编写Lua脚本来实现你想要的功能。可以根据APISIX提供的插件开发文档和示例进行编写。

  2. 将Lua脚本放置到APISIX插件目录:将编写好的Lua脚本文件放置到APISIX的插件目录下,一般是/usr/local/apisix/lua-plugins/目录。

  3. 编辑配置文件:修改APISIX的配置文件,启用自定义插件。在conf/config.yaml文件中添加对应的插件配置,指定使用你编写的Lua脚本。

  4. 重启APISIX服务:完成以上步骤后,记得重启APISIX服务使配置生效,可以使用命令apisix restart来重启APISIX。

  5. 测试插件:在完成上述步骤后,你就可以通过发送请求测试你自定义的插件是否按照预期工作了。

总的来说,自定义插件的过程主要包括编写Lua脚本、放置到插件目录、编辑配置文件、重启APISIX服务以及测试插件。详细的开发步骤和示例可以参考APISIX官方文档。

部署到k8s

如果你使用Helm将APISIX部署到Kubernetes中,并且想要添加自定义插件,可以按照以下步骤进行操作:

  1. 编写Lua脚本:首先,按照之前提到的步骤编写Lua脚本,实现你需要的功能。

  2. 创建ConfigMap:将编写好的Lua脚本内容放入一个ConfigMap中,可以使用如下命令创建一个ConfigMap:

    kubectl create configmap my-custom-plugin --from-file=my_plugin.lua
    
  3. 修改Helm Chart模板:编辑APISIX的Helm Chart模板,找到对应的配置文件(一般是values.yaml或者configmap.yaml),在其中添加对应的ConfigMap配置,指定使用你的Lua脚本。

  4. 升级APISIX部署:通过Helm命令升级APISIX的部署,使新的ConfigMap生效:

 helm -n apisix upgrade apisix -f ./apisix/values.override.yaml ./apisix

  1. 验证插件:升级完成后,可以发送请求测试你自定义的插件是否按照预期工作了。

通过以上步骤,你就可以在使用Helm部署的APISIX中添加自定义插件。记得根据实际情况修改对应的文件路径和配置项,确保插件能够成功加载并发挥作用。

对dash board可见自定义插件

1 配置中添加插件

只有添加到配置文件中的插件才可以被apisix使用。在apisix 的conf 目录的config.yaml 中有个plugins字段,将示例插件的插件名"insert-header"添加到该字段下。

2 装载插件

需要对apisix 进行reload。直接运行 apisix reload 就可以装载插件

3 dashboard中添加插件

虽然apisix 提供了管理接口可以通过接口的方式给路由添加插件,但使用dashboard 操作会方便很多。

1、重新生成schema.json.

curl 127.0.0.1:9092/v1/schema > /usr/local/apisix/dashboard/conf/schema.json

2、重启dashboard

kill -9
(ps -ef|grep "/usr/local/apisix/dashboard"|gawk '

OpenResty

OpenResty阶段

在OpenResty中,阶段(phase)指的是请求处理过程中的不同阶段或环节。OpenResty基于Nginx并使用Lua语言进行扩展,通过定义不同的阶段可以在请求处理过程中插入自定义的Lua代码来实现各种功能。

在OpenResty中,请求经过一系列预定义的处理阶段,每个阶段都有对应的处理函数,开发者可以在这些阶段中编写Lua代码来实现各种功能,例如请求重写、访问控制、日志记录等。这些阶段可以被称为请求生命周期中的钩子点,允许开发者在特定的时机执行自定义逻辑。

常见的OpenResty阶段包括:

  • init_by_lua:在Nginx启动时执行,用于初始化Lua代码。
  • init_worker_by_lua:在Worker进程启动时执行,用于初始化Lua代码。
  • ssl_certificate_by_lua:用于SSL证书处理。
  • rewrite_by_lua:用于请求重写。
  • access_by_lua:用于访问控制。
  • content_by_lua:用于生成响应内容。
  • header_filter_by_lua:用于处理响应头。
  • body_filter_by_lua:用于处理响应体。

通过在不同阶段插入Lua代码,开发者可以实现高度定制化的请求处理逻辑,从而满足各种需求,如API网关、反向代理、缓存控制等。因此,OpenResty的阶段机制提供了灵活且强大的扩展能力,使得开发者能够更好地控制请求处理流程。

相关处理器方法

在APISIX中,这些_M开头的方法是OpenResty的阶段处理器,用于对请求或响应进行处理。下面是它们各自的作用:

  • _M.check_schema**:用于定义插件配置的校验规则,可以确保插件配置符合预期的格式和类型。通过定义校验规则,可以在配置插件时进行参数检查,避免配置错误导致的问题。
  • _M.header_filter:用于处理响应头,在API响应返回给客户端之前执行。
  • _M.new:用于创建新的请求或响应对象,可以在此阶段对请求或响应进行初始化操作。
  • _M.incoming:用于处理请求体,在请求被路由到后端服务之前执行。
  • _M.access:用于访问控制,可以在此阶段进行权限验证、IP过滤等操作。
  • _M.rewrite:用于重写请求,可以在此阶段修改请求的URI、参数等信息。
  • _M.api()**:用于注册插件的API接口,使得插件可以通过API方式被外部调用。通过定义API接口,可以让插件暴露特定的功能给用户使用,实现更加灵活的插件扩展和定制
    除了上述提到的预置方法外,APISIX还提供了其他一些预置的方法,例如:
  • _M.balancer:用于负载均衡,可以在此阶段选择合适的后端节点进行请求转发。
  • _M.init_worker:用于初始化Worker进程,在启动时执行一次,通常用于加载配置、初始化数据等操作。
  • _M.log:用于日志记录,可以在此阶段记录请求、响应信息到日志系统。

总结来说,APISIX通过这些预置的方法(阶段处理器)提供了丰富的扩展点,开发者可以根据需求在不同阶段对请求和响应进行定制化处理,实现灵活的API网关功能。

一个完整的插件demo

  • 向响应头输出X-Custom-Header头
-- 定义一个 Lua 函数,用于处理请求
local core      = require("apisix.core")
local ngx = ngx
local ngx_encode_base64 = ngx.encode_base64
local ngx_decode_base64 = ngx.decode_base64
local ngx_time = ngx.time

local schema={} -- 注意,需要先定义它,再使用它

local _M={
    version=0.1,
    priority=1011,
    name = "lind-test",
    schema=schema
}

function _M.access(api_ctx)
    core.log.warn("hit access phase")
end


function _M.header_filter(ctx)
    core.log.warn("hit header_filter phase") -- 在apisix控制台打印日志
    core.response.add_header("X-Custom-Header", "apisix-3.9.1")
end


function _M.body_filter(ctx)
    core.log.warn("hit body_filter phase")
end


function _M.log(ctx)
    core.log.warn("hit log phase")
end

-- 注册插件
return _M

注册插件

values.yaml

  • 找到plugins节点,将现有的config-default.xml中的默认插件添加,避免自定义插件覆盖默认插件的情况
  • 默认插件列表获取方式:http://127.0.0.1:9180/apisix/admin/plugins/list 9180是apisix-admin的容器端口
plugins: ["real-ip","ai","client-control","proxy-control","request-id","zipkin","ext-plugin-pre-req","fault-injection","mocking","serverless-pre-function","cors","ip-restriction","ua-restriction","referer-restriction","csrf","uri-blocker","request-validation","chaitin-waf","multi-auth","openid-connect","cas-auth","authz-casbin","authz-casdoor","wolf-rbac","ldap-auth","hmac-auth","basic-auth","jwt-auth","jwe-decrypt","key-auth","consumer-restriction","forward-auth","opa","authz-keycloak","proxy-cache","body-transformer","proxy-mirror","proxy-rewrite","workflow","api-breaker","limit-conn","limit-count","limit-req","gzip","server-info","traffic-split","redirect","response-rewrite","degraphql","kafka-proxy","grpc-transcode","grpc-web","public-api","prometheus","datadog","loki-logger","elasticsearch-logger","echo","loggly","http-logger","splunk-hec-logging","skywalking-logger","google-cloud-logging","sls-logger","tcp-logger","kafka-logger","rocketmq-logger","syslog","udp-logger","file-logger","clickhouse-logger","tencent-cloud-cls","inspect","example-plugin","aws-lambda","azure-functions","openwhisk","openfunction","serverless-post-function","ext-plugin-post-req","ext-plugin-post-resp"]

values.override.yaml

  • 添加自定义插件
  • 通过ConfigMap的方式将插件内容放到配置文件中
apisix:
  admin:
    type: NodePort
    nodePort: 30087

  customPlugins:
    enabled: true
    luaPath: "/opt/?.lua"
    plugins:
      - name: "lind-test"
        configMap:
          name: "my-plugins-config"
          mounts:
            - key: "lind-test.lua"
              path: "/opt/apisix/plugins/lind-test.lua" #相当于把my-plugins-config下的lind-test.lua这个key,映射到容器下面/opts/custom_plugins目录,apisix/plugins是相对目录(是固定的),文件名还是lind-test.lua

向route添加自定义插件

  • 目前在dashborad中无法看到自定义插件
  • 在/apisix/admin/plugins/list中可以看到插件
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/test",
    "id": 1,
    "plugins": {
        "lind-test": {
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

访问页面

  • http://apisix-gateway/test
  • 将test前缀的请求,转发到upstream,真实地址是127.0.0.1的1980端口指向的服务
  • 在浏览器的响应头中,看到由lind-test插件添加的标识X-Custom-Header