kong/plugin-example

Kong Gateway Operator 插件分发示例镜像

1. 镜像概述和主要用途

本镜像为 Kong Gateway Operator 提供插件分发的参考实现，旨在演示如何通过 Kubernetes 原生资源管理 Kong Gateway 插件的打包、分发与生命周期控制。镜像包含预配置的插件示例、元数据定义及与 Kong Gateway Operator 集成的必要配置，帮助用户快速理解 Operator 管理插件的工作流程。

2. 核心功能和特性

2.1 插件打包示例

• 包含 Lua 插件（如请求限流、日志转发）的完整目录结构，符合 Kong 插件规范
• 提供插件元数据文件（plugin.yaml），定义插件名称、版本、依赖及配置schema

2.2 Kong Gateway Operator 集成

• 支持通过 Kubernetes CustomResource (KongPlugin) 资源定义插件配置
• 内置与 Operator 状态同步机制，自动上报插件分发状态（就绪/失败）

2.3 配置管理

• 支持插件动态配置更新，无需重启 Kong Gateway 实例
• 提供多版本插件共存示例，支持灰度发布场景

2.4 多环境适配

• 内置环境变量注入机制，支持区分开发/测试/生产环境插件配置
• 兼容 Kong Gateway 2.8+ 及 Kong Gateway Operator 1.5+ 版本

3. 使用场景和适用范围

3.1 典型使用场景

• 插件开发测试：快速验证自定义插件在 Operator 管理模式下的加载与运行效果
• Operator 功能演示：向用户展示如何通过 Operator 实现插件的声明式管理
• 多集群插件分发：验证跨命名空间/集群的插件统一分发能力

3.2 适用范围

• 目标用户：Kong Gateway 用户、Kubernetes 管理员、API 网关插件开发者
• 环境要求：Kubernetes 1.21+ 集群、Kong Gateway Operator 1.5+、Kong Gateway 2.8+

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Kong Gateway Operator（参考 https://docs.konghq.com/gateway-operator/latest/installation/）
• Kubernetes 集群版本 ≥ 1.21，且已配置 kubectl 命令行工具
• 集群内已部署 Kong Gateway 实例（通过 Operator 或独立部署）

4.2 镜像获取

bash
# 从 Docker Hub 拉取镜像
docker pull docker.xuanyuan.run/kong/kong-gateway-operator-plugin-example:latest

# 或从私有仓库拉取（如配置）
docker pull docker.xuanyuan.run/<私有仓库地址>/kong-plugin-example:v1.0.0

4.3 插件分发步骤

4.3.1 配置插件元数据

创建插件元数据文件 plugin-metadata.yaml，定义插件基本信息：

yaml
apiVersion: gateway.konghq.com/v1alpha1
kind: KongPluginMetadata
metadata:
  name: example-rate-limit
  namespace: kong
spec:
  name: rate-limit-example  # 插件名称（需与 Kong 插件目录名一致）
  version: 1.0.0
  type: http  # 插件类型（http/stream）
  configSchema:  # 插件配置项schema
    type: object
    properties:
      limit:
        type: integer
        minimum: 1
      period:
        type: string
        enum: [second, minute, hour]

4.3.2 部署插件资源

通过 KongPlugin 资源定义插件配置及分发目标：

yaml
apiVersion: gateway.konghq.com/v1alpha1
kind: KongPlugin
metadata:
  name: demo-rate-limit
  namespace: kong
spec:
  pluginRef: example-rate-limit  # 关联上述元数据资源
  config:  # 插件运行时配置
    limit: 100
    period: minute
  targetRef:  # 目标网关选择器
    group: gateway.networking.k8s.io
    kind: Gateway
    name: kong-gateway
    namespace: kong

应用资源：

bash
kubectl apply -f plugin-metadata.yaml
kubectl apply -f kong-plugin.yaml

4.3.3 验证分发结果

检查 Operator 状态：

bash
kubectl get kongplugins.gateway.konghq.com demo-rate-limit -o yaml

预期输出中 status 字段显示 phase: Ready，表示插件已成功分发至目标网关。

5. 部署示例

5.1 Kubernetes 资源清单示例（推荐）

插件元数据与配置完整部署清单（plugin-demo.yaml）

yaml
apiVersion: gateway.konghq.com/v1alpha1
kind: KongPluginMetadata
metadata:
  name: example-rate-limit
  namespace: kong
spec:
  name: rate-limit-example
  version: 1.0.0
  type: http
  configSchema:
    type: object
    properties:
      limit: {type: integer, minimum: 1}
      period: {type: string, enum: [second, minute, hour]}
---
apiVersion: gateway.konghq.com/v1alpha1
kind: KongPlugin
metadata:
  name: demo-rate-limit
  namespace: kong
spec:
  pluginRef: example-rate-limit
  config:
    limit: 100
    period: minute
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: kong-gateway
    namespace: kong

部署命令：

bash
kubectl apply -f plugin-demo.yaml

5.2 Docker Compose 简化示例（开发环境）

适用于本地测试 Kong Gateway 与插件集成（非 Operator 环境）：

yaml
version: '3'
services:
  kong:
    image: docker.xuanyuan.run/kong/kong-gateway:3.4
    ports:
      - "8000:8000"  # HTTP 代理端口
      - "8443:8443"  # HTTPS 代理端口
      - "8001:8001"  # Admin API 端口
    environment:
      - KONG_DATABASE=off
      - KONG_DECLARATIVE_CONFIG=/etc/kong/kong.yaml
      - KONG_PLUGINS=bundled,rate-limit-example  # 加载自定义插件
    volumes:
      - ./kong.yaml:/etc/kong/kong.yaml
      - ./plugins/rate-limit-example:/usr/local/kong/plugins/rate-limit-example  # 挂载插件目录

  plugin-example:
    image: docker.xuanyuan.run/kong/kong-gateway-operator-plugin-example:latest
    volumes:
      - ./plugins:/output  # 输出插件示例到本地目录

6. 配置参数说明

6.1 KongPlugin 资源核心参数

6.2 环境变量（容器级）

7. 注意事项

• 本镜像仅用于演示，生产环境需根据实际插件需求修改元数据及配置
• 插件分发依赖 Kong Gateway Operator 1.5+ 版本，低版本需升级 Operator
• 多集群分发需确保目标集群已部署 Kong Gateway Operator 并配置跨集群资源同步（如使用 Fleet/ArgoCD）