部署 Lua 自定义插件

当内置插件无法提供所需行为时，自定义 Lua 插件可以扩展网关的请求处理能力。自定义代码在网关内部运行，因此部署前应对其进行审查和测试。

以下流程加载示例 file-proxy 插件，通过 HTTPRoute 或 ApisixRoute 应用该插件，并验证它能够返回静态文件。

前置条件

1. 完成设置 Ingress Controller 和网关。
2. 阅读开发文件代理插件一节，并将 file-proxy.lua 保存为示例自定义插件文件。两个产品路径使用相同的插件代码。

加载自定义插件

所有可能处理该路由的网关 Pod 都必须加载相同的自定义插件代码。请按所用网关产品选择流程。

APISIX

在网关命名空间中，基于自定义插件文件创建 ConfigMap：

kubectl create configmap custom-file-proxy \
  --namespace aic \
  --from-file=file-proxy.lua

在隔离的本地评估环境中，升级 APISIX release 以挂载并启用该插件：

helm upgrade apisix apisix/apisix \
  --version 2.18.0 \
  --namespace aic \
  --reuse-values \
  --set "apisix.customPlugins.enabled=true" \
  --set "apisix.customPlugins.plugins[0].name=file-proxy" \
  --set "apisix.customPlugins.plugins[0].configMap.name=custom-file-proxy" \
  --set "apisix.customPlugins.plugins[0].configMap.mounts[0].key=file-proxy.lua" \
  --set "apisix.customPlugins.plugins[0].configMap.mounts[0].path=/opts/custom_plugins/apisix/plugins/file-proxy.lua" \
  --set "apisix.plugins={prometheus,file-proxy}"

等待网关 Deployment 使用自定义插件完成滚动重启：

kubectl rollout status deployment/apisix --namespace aic

精简的 HTTP 插件列表

apisix.plugins 会替换默认的 HTTP 插件列表。上面的精简示例保留 prometheus 仅用于指标采集，并加入 file-proxy；该设置只适用于隔离的本地评估。apisix.stream_plugins 是独立的 Stream 插件列表，打包提供的 syslog Stream 插件并不依赖 HTTP prometheus 插件。对于现有网关，应将 file-proxy 添加到现有 HTTP 插件列表中，不要移除部署正在使用的任何插件。

API7 企业版

将插件上传到 Ingress Controller 所使用的网关组。Dashboard 操作流程请参阅在 API7 网关中注册插件。

测试自定义插件

下面的示例使用 APISIX 本地评估环境所创建的 aic 命名空间和 apisix Gateway。对于 API7 网关，请将命名空间和 HTTPRoute 的 parentRefs.name 替换为 API7 Dashboard 生成的值。

为进行一次性验证，在网关 Pod 上存储静态 openapi.yaml 文件。APISIX 本地评估环境只有一个网关副本，并使用 apisix Deployment：

kubectl exec -i --namespace aic deployment/apisix \
  -- sh -c 'cat > /usr/local/apisix/openapi.yaml' <<'EOF'
openapi: 3.0.1
info:
  title: OpenAPI Spec
  description: OpenAPI Spec file description.
EOF

对于 API7 网关或多副本部署，请通过部署配置让每个网关 Pod 都能在相同路径访问该文件。将文件写入一个 Pod 不会让其他副本也能访问该文件。

创建带有自定义插件的路由，该插件会使用 openapi.yaml 文件：

Gateway API

file-proxy-route.yaml

apiVersion: v1
kind: Service
metadata:
  namespace: aic
  name: file-proxy-backend
spec:
  type: ExternalName
  externalName: httpbin.org
  ports:
  - name: http
    port: 80
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: file-proxy-plugin-config
spec:
  plugins:
    - name: file-proxy
      config:
        path: /usr/local/apisix/openapi.yaml
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: openapi-file-proxy
spec:
  parentRefs:
  - name: apisix
  rules:
  - matches:
    - path:
        type: Exact
        value: /openapi.yaml
    filters:
    - type: ExtensionRef
      extensionRef:
        group: apisix.apache.org
        kind: PluginConfig
        name: file-proxy-plugin-config
    backendRefs:
    - name: file-proxy-backend
      port: 80

共享 HTTPRoute 包含后端，因为 APISIX Ingress Controller 会为没有后端的规则生成 500 回退响应。API7 Ingress Controller 2.2.1 接受仅包含插件的形式，但保留后端可让示例同时适用于两个产品。file-proxy 插件会在网关向回退后端发送请求之前返回文件。

APISIX CRD

file-proxy-route.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: openapi-file-proxy
spec:
  ingressClassName: apisix
  http:
    - name: openapi-file-proxy
      match:
        paths:
          - /openapi.yaml
      plugins:
      - name: file-proxy
        enable: true
        config:
          path: /usr/local/apisix/openapi.yaml

该插件自行返回响应，因此这个仅包含插件的 ApisixRoute 不需要后端。

将配置应用到集群：

kubectl apply -f file-proxy-route.yaml

对于 APISIX 本地评估环境，将网关 Service 暴露到本地机器。对于 API7 安装，请替换为 API7 Dashboard 生成的网关 Service。

kubectl port-forward --namespace aic svc/apisix-gateway 9080:80 &

向路由发送请求：

curl "http://127.0.0.1:9080/openapi.yaml"

你应收到包含 openapi.yaml 文件内容的响应：

openapi: 3.0.1
info:
  title: OpenAPI Spec
  description: OpenAPI Spec file description.

这表明自定义插件已成功加载并正常工作。