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

5. 驗證插件：升級完成後，可以發送請求測試你自定義的插件是否按照預期工作了。

通過以上步驟，你就可以在使用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