開發插件的步驟
在APISIX中,要自定義插件,一般需要按照以下步驟進行操作:
-
編寫Lua腳本:首先,你需要編寫Lua腳本來實現你想要的功能。可以根據APISIX提供的插件開發文檔和示例進行編寫。
-
將Lua腳本放置到APISIX插件目錄:將編寫好的Lua腳本文件放置到APISIX的插件目錄下,一般是
/usr/local/apisix/lua-plugins/
目錄。 -
編輯配置文件:修改APISIX的配置文件,啓用自定義插件。在
conf/config.yaml
文件中添加對應的插件配置,指定使用你編寫的Lua腳本。 -
重啓APISIX服務:完成以上步驟後,記得重啓APISIX服務使配置生效,可以使用命令
apisix restart
來重啓APISIX。 -
測試插件:在完成上述步驟後,你就可以通過發送請求測試你自定義的插件是否按照預期工作了。
總的來說,自定義插件的過程主要包括編寫Lua腳本、放置到插件目錄、編輯配置文件、重啓APISIX服務以及測試插件。詳細的開發步驟和示例可以參考APISIX官方文檔。
部署到k8s
如果你使用Helm將APISIX部署到Kubernetes中,並且想要添加自定義插件,可以按照以下步驟進行操作:
-
編寫Lua腳本:首先,按照之前提到的步驟編寫Lua腳本,實現你需要的功能。
-
創建ConfigMap:將編寫好的Lua腳本內容放入一個ConfigMap中,可以使用如下命令創建一個ConfigMap:
kubectl create configmap my-custom-plugin --from-file=my_plugin.lua
-
修改Helm Chart模板:編輯APISIX的Helm Chart模板,找到對應的配置文件(一般是
values.yaml
或者configmap.yaml
),在其中添加對應的ConfigMap配置,指定使用你的Lua腳本。 -
升級APISIX部署:通過Helm命令升級APISIX的部署,使新的ConfigMap生效:
helm -n apisix upgrade apisix -f ./apisix/values.override.yaml ./apisix
- 驗證插件:升級完成後,可以發送請求測試你自定義的插件是否按照預期工作了。
通過以上步驟,你就可以在使用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