Apache APISIX 自定义插件开发与 Kubernetes 集成实践

2025-05-15 14:50:05作者：管翌锬

前言

在现代 API 网关解决方案中，Apache APISIX 以其高性能和可扩展性脱颖而出。本文将深入探讨如何在 APISIX 中开发自定义插件，并将其部署到 Kubernetes 环境中。我们将通过一个实际的日志插件案例，详细解析整个开发部署流程中的关键点和常见问题。

自定义插件开发基础

APISIX 插件采用 Lua 语言编写，遵循模块化设计原则。一个基本的插件结构包含以下几个核心部分：

插件元信息：定义插件名称、版本和优先级
Schema 验证：描述插件配置的数据结构
生命周期方法：实现插件在不同阶段的行为

以下是一个简单的日志插件实现示例：

local core = require("apisix.core")

local plugin_name = "log"

local _M = {
    version = 0.1,
    priority = 0,
    name = plugin_name,
}

_M.schema = {
    type = "object",
    properties = {},
}

function _M.access(conf, ctx)
    core.log.warn("log plugin triggered!")
end

return _M

这个插件会在请求访问阶段记录一条日志信息。值得注意的是，我们使用了 warn 级别而非 info，这是因为 APISIX 默认日志级别为 warn，使用 info 级别的日志在默认配置下不会显示。

插件优先级的重要性

APISIX 插件系统采用优先级机制决定执行顺序。每个插件都有一个默认优先级数值，数值越大执行越早。在我们的示例中：

serverless-pre-function 插件默认优先级为 10000
我们的日志插件优先级为 0

这意味着如果两个插件同时作用于同一路由，serverless-pre-function 会先执行并可能终止请求处理（如直接返回响应），导致我们的日志插件根本没有机会执行。

解决方案有两种：

修改插件定义：提高插件默认优先级

local _M = {
    version = 0.1,
    priority = 20000, -- 高于 serverless-pre-function
    name = plugin_name,
}

路由配置覆盖：在特定路由中动态调整优先级

plugins:
  log:
    _meta:
      priority: 20000

Kubernetes 部署实践

将自定义插件部署到 Kubernetes 环境需要特别注意文件挂载和配置管理。以下是关键步骤：

1. 创建 ConfigMap 存储插件代码

apiVersion: v1
kind: ConfigMap
metadata:
  name: apisix-custom-plugin-log
data:
  log.lua: |
    -- 插件Lua代码

2. 挂载到 APISIX 容器

volumeMounts:
- name: custom-plugin-log
  mountPath: /usr/local/apisix/apisix/plugins/log.lua
  subPath: log.lua
volumes:
- name: custom-plugin-log
  configMap:
    name: apisix-custom-plugin-log