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

前言

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

自定义插件开发基础

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

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

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

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 会先执行并可能终止请求处理（如直接返回响应），导致我们的日志插件根本没有机会执行。

解决方案有两种：

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

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

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

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

3. 配置 APISIX 加载插件

在 config.yaml 中声明使用插件：

plugins:
  - log
  # 其他插件...

日志配置优化

默认情况下，APISIX 的日志级别设置为 warn。要查看更多日志信息，可以调整 Nginx 的日志级别：

nginx_config:
  error_log_level: info

但需要注意，info 级别会产生大量日志，在生产环境中应谨慎使用。

常见问题排查

1. 插件未加载：

   • 检查文件路径是否正确挂载
   • 确认插件名称在 config.yaml 中声明
   • 查看 APISIX 启动日志是否有加载错误

2. 插件未执行：

   • 检查插件优先级是否被其他插件覆盖
   • 确认路由配置正确引用了插件
   • 验证插件是否实现了正确的生命周期方法

3. 日志不显示：

   • 确认日志级别设置
   • 检查插件是否真的被执行到
   • 查看 APISIX 的日志输出位置

进阶建议

1. 插件开发：

   • 遵循 APISIX 插件开发规范
   • 实现完整的 Schema 验证
   • 考虑插件性能影响

2. Kubernetes 部署：

   • 使用 Init Container 进行插件预检查
   • 考虑使用 ConfigMap 热重载
   • 实现健康检查接口

3. 监控运维：

   • 集成 Prometheus 监控
   • 设置合理的日志轮转策略
   • 实现插件配置的版本控制

结语

通过本文的实践案例，我们展示了如何在 APISIX 中开发和部署自定义插件。从插件基础结构到 Kubernetes 集成，每个环节都有其技术要点和最佳实践。掌握这些知识后，开发者可以灵活扩展 APISIX 的功能，满足各种业务场景的需求。

在实际生产环境中，建议从简单插件入手，逐步验证各个环节，确保整个系统的稳定性和可靠性。同时，APISIX 活跃的社区和丰富的文档也是解决问题的宝贵资源。