Deploy Lua Custom Plugins

Custom Lua plugins extend gateway request processing when built-in plugins do not provide the required behavior. Because custom code runs inside the gateway, review and test it before deployment.

The workflow below loads the example file-proxy plugin, applies it with HTTPRoute or ApisixRoute, and verifies that it returns a static file.

Prerequisites

1. Complete Set Up Ingress Controller and Gateway.
2. Review the Develop File Proxy Plugin section and save file-proxy.lua as an example custom plugin file. Both product paths use the same plugin code.

Load Custom Plugin

Every gateway pod that can serve the route must load the same custom plugin code. Use the workflow for your gateway product.

APISIX

Create a ConfigMap in the gateway namespace from the custom plugin file:

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

For an isolated local evaluation, upgrade the APISIX release to mount and enable the plugin:

helm upgrade apisix apisix/apisix \
  --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}"

Wait for the gateway Deployment to finish restarting with the custom plugin:

kubectl rollout status deployment/apisix --namespace aic

Reduced Plugin List

The apisix.plugins value replaces the default HTTP plugin list. The reduced list above keeps prometheus, which the packaged syslog stream plugin requires, and is intended only for the isolated local evaluation. For an existing gateway, add file-proxy to its existing HTTP plugin list without removing any plugins the deployment uses.

API7 Enterprise

Upload the plugin to the gateway group used by the Ingress Controller. Follow Register the Plugin in API7 Gateway for the Dashboard workflow.

Test Custom Plugin

The examples below use the aic namespace and apisix Gateway created by the APISIX local evaluation. For API7 Gateway, replace the namespace and the HTTPRoute parentRefs.name with the values generated by API7 Dashboard.

For one-time verification, store a static openapi.yaml file on the gateway pod. The APISIX local evaluation has one gateway replica and uses the 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

For API7 Gateway or a deployment with multiple replicas, make the file available at the same path on every gateway pod through your deployment configuration. Writing the file to one pod does not make it available to the other replicas.

Create a route with the custom plugin that uses the openapi.yaml file:

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

The shared HTTPRoute includes a backend because APISIX Ingress Controller generates a 500 fallback for a rule without one. API7 Ingress Controller accepts the plugin-only shape in this version, but the backend keeps the example portable across both products. The file-proxy plugin returns the file before the gateway sends a request to the fallback backend.

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

The plugin returns the response itself, so this plugin-only ApisixRoute does not require a backend.

Apply the configuration to your cluster:

kubectl apply -f file-proxy-route.yaml

For the APISIX local evaluation, expose the gateway Service on your local machine. For an API7 installation, substitute the gateway Service generated by API7 Dashboard.

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

Send a request to the route:

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

You should receive a response with the content of the file openapi.yaml:

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

This verifies that the custom plugin is loaded and working correctly.