Deploy custom plugins

Custom Lua plugins can be stored in a Kubernetes ConfigMap or Secret and mounted in your Kong Gateway Pod.

The examples in this guide use a ConfigMap, but you can replace any references to configmap with secret to use a Secret instead.

If you would like to install a plugin which is available as a rock from Luarocks, then you need to download it, unzip it and create a ConfigMap from all the Lua files of the plugin.

If you already have a real plugin, you can skip this step.

mkdir myheader
echo 'local MyHeader = {}

MyHeader.PRIORITY = 1000
MyHeader.VERSION = "1.0.0"

function MyHeader:header_filter(conf)
  -- do custom logic here
  kong.response.set_header("myheader", conf.header_value)
end

return MyHeader
' > myheader/handler.lua

echo 'return {
  name = "myheader",
  fields = {
    { config = {
        type = "record",
        fields = {
          { header_value = { type = "string", default = "roar", }, },
        },
    }, },
  }
}
' > myheader/schema.lua

The directory should now look like this:

myheader
├── handler.lua
└── schema.lua

1 directory, 2 files

Create a ConfigMap from your directory that will be mounted to your Kong Gateway Pod:

kubectl create configmap kong-plugin-myheader --from-file=myheader -n kong

If your custom plugin includes new entities, you need to create a daos.lua file in your directory and a migration sub-directory containing the scripts to create any database tables and migrate data between different versions (if your entities’ schemas changed between different versions). In this case, the directory should like this:

  myheader
  ├── daos.lua
  ├── handler.lua
  ├── migrations
  │   ├── 000_base_my_header.lua
  │   ├── 001_100_to_110.lua
  │   └── init.lua
  └── schema.lua

  1 directories, 6 files

As a ConfigMap does not support nested directories, you need to create another ConfigMap containing the migrations directory:

kubectl create configmap kong-plugin-myheader-migrations --from-file=myheader/migrations -n kong

Kong provides a way to deploy custom plugins using both Kong Operator and the Kong Ingress Controller Helm chart. This guide shows how to use the Helm chart, but we recommend using Kong Operator if possible. See Kong custom plugin distribution with KongPluginInstallation for more information.

The Kong Ingress Controller Helm chart automatically configures all the environment variables required based on the plugins you inject.

1. Update your values.yaml file with the following contents. Ensure that you add in other configuration values you might need for your installation to be successful.

    gateway:
      plugins:
        configMaps:
          - name: kong-plugin-myheader
            pluginName: myheader
   

   Copied!

   If you need to include the migration scripts to the plugin, configure userDefinedVolumes and userDefinedVolumeMounts in values.yaml to mount the migration scripts to the Kong Gateway pod:

    gateway:
      plugins:
        configMaps:
          - name: kong-plugin-myheader
            pluginName: myheader
      deployment:
        userDefinedVolumes:
          - name: "kong-plugin-myheader-migrations"
            configMap:
              name: "kong-plugin-myheader-migrations"
        userDefinedVolumeMounts:
          - name: "kong-plugin-myheader-migrations"
            mountPath: "/opt/kong/plugins/myheader/migrations" # Should be the path /opt/kong/plugins/<plugin-name>/migrations
   

   Copied!

2. Upgrade Kong Ingress Controller with the new values

    helm upgrade --install kong kong/ingress -n kong --create-namespace --values values.yaml
   

   Copied!

To see your custom plugin in Kong Konnect, you need to register the schema with your control plane:

curl -X POST \
  https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/core-entities/plugin-schemas \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $KONNECT_TOKEN" \
  --data "{\"lua_schema\": $(jq -Rs . './myheader/schema.lua')}"

If you get a “plugin failed schema validation” error, wait until your Kong Gateway Pods have cycled before trying to create a KongPlugin instance

After you have set up Kong Gateway with the custom plugin installed, you can use it like any other plugin by adding the konghq.com/plugins annotation.

1. Create a KongPlugin custom resource:

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: my-custom-plugin
      namespace: kong
      annotations:
        kubernetes.io/ingress.class: kong
    plugin: myheader
    config:
      header_value: my first plugin
    " | kubectl apply -f -
   

   Copied!

   Next, apply the KongPlugin resource by annotating the service resource:

    kubectl annotate -n kong service echo konghq.com/plugins=my-custom-plugin
   

   Copied!

2. Create a Route to the echo service to test your custom plugin:

   Gateway API Ingress

   echo "
    apiVersion: gateway.networking.k8s.io/v1
    kind: HTTPRoute
    metadata:
      name: echo
      namespace: kong
      annotations:
        konghq.com/strip-path: 'true'
    spec:
      parentRefs:
      - name: kong
        namespace: kong
      rules:
      - matches:
        - path:
            type: PathPrefix
            value: /echo
        backendRefs:
        - name: echo
          kind: Service
          port: 1027
    " | kubectl apply -f -
    

   Copied!

   echo "
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: echo
      namespace: kong
      annotations:
        konghq.com/strip-path: 'true'
    spec:
      ingressClassName: kong
      rules:
      - http:
          paths:
          - path: /echo
            pathType: ImplementationSpecific
            backend:
              service:
                name: echo
                port:
                  number: 1027
    " | kubectl apply -f -
    

   Copied!

Once the resource has been reconciled, you’ll be able to call the /echo endpoint and Kong Gateway will route the request to the echo service.

The -i flag returns response headers from the server, and you will see myheader: my first plugin in the output:

curl -i "$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body 

curl -i "$PROXY_IP/echo" \
     --no-progress-meter --fail-with-body