apisix~ApisixPluginConfig的使用

1. ApisixPluginConfig 的作用

• 插件配置复用：将插件配置定义为独立的资源，供多个路由或服务引用。
• 解耦插件与路由：修改插件配置时，只需更新 ApisixPluginConfig，无需逐个修改路由。
• 支持复杂配置：避免在 Ingress 的 Annotations 中编写冗长的 JSON。
• plugin_config_id: 通过这种方式添加的插件，将不会在apisix dashboard上显示，这块需要注意，但插件本身是生效的。

2. 使用步骤

(1) 创建 ApisixPluginConfig 资源

定义插件的具体配置（例如限流插件 limit-count）：

apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
  name: limit-config
spec:
  plugins:
  - name: limit-count
    enable: true
    config:
      _meta:
        disable: false #注意这行是必须的，否则在dashboard的路由>高级特性>插件模板配置中会出现白屏的情况
      count: 100
      time_window: 60
      key: remote_addr
      policy: local

(2) 在 ApisixRoute 或 Ingress 中引用

通过 plugin_config_name 字段关联到路由：

方式一：在 ApisixRoute 中引用

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  name: my-route
spec:
  http:
  - name: rule1
    match:
      hosts: ["example.com"]
      paths: ["/*"]
    backends:
      - serviceName: my-service
        servicePort: 80
    # 引用插件配置
    plugin_config_name: limit-config

注意：如果apisix-ingress中使用了自已的域名，那网关的域名就失效了，这块需要注意一下

方式二：在 Ingress 中通过注解引用

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    k8s.apisix.apache.org/plugin-config-name: "limit-config"  # 指定插件配置名称
spec:
  ingressClassName: apisix
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

3. 验证配置

(1) 检查 ApisixPluginConfig 状态

kubectl get apisixpluginconfig limit-config -o yaml

如果是阿里云容器平台上，它会在自定义资源里出现

apisix-dashboard的路由》高级特性》插件模板会展示你的插件配置

(2) 查看 APISIX 路由详情

通过 Admin API 检查路由是否关联了插件：

curl http://<APISIX_ADMIN_IP>:9180/apisix/admin/routes -H 'X-API-KEY: <ADMIN_KEY>'

预期输出中应包含 limit-count 插件的配置。

4. 优势对比

5. 注意事项

1. 作用域限制：
   • 默认情况下，ApisixPluginConfig 是命名空间级别的资源，需确保路由和插件配置在同一命名空间。若需跨命名空间引用，需配置 APISIX Ingress Controller 的 scope 参数为 cluster。
2. 版本兼容性：
   • 确保 APISIX Ingress Controller 版本支持 ApisixPluginConfig（v2.7+ 推荐使用）。
3. 配置冲突：
   • 如果同时在 ApisixRoute 和 ApisixPluginConfig 中定义了同名插件，ApisixRoute 中的配置会覆盖 ApisixPluginConfig。

6. 高级用法：组合多个插件

可以在一个 ApisixPluginConfig 中定义多个插件：

apiVersion: apisix.apache.org/v2
kind: ApisixPluginConfig
metadata:
  name: global-plugins
spec:
  plugins:
  - name: limit-count
    enable: true
    config:
      _meta:
        disable: false
      count: 200
      time_window: 60
  - name: cors
    enable: true
    config:
       _meta:
         disable: false
      allow_origins: "*"
      allow_methods: "GET,POST"

总结

通过 ApisixPluginConfig 可以实现插件的集中管理和复用，特别适合以下场景：

1. 多个路由需要相同插件配置（如全局限流、鉴权）。
2. 插件配置复杂，需避免在 Ingress 中维护冗长的 JSON。
3. 需要动态更新插件配置而不影响路由定义。

如果此前通过 Ingress Annotations 管理插件，可以逐步迁移到 ApisixPluginConfig，提升配置的可维护性。

作者：仓储大叔，张占岭，
荣誉：微软MVP
QQ：853066980

支付宝扫一扫，为大叔打赏!