Deploy custom plugins with Kong Operator

Kong Operator can install Kong custom plugins packaged as container images. This guide shows how to package, install, and use a custom plugin in Kong Gateway instances managed by the Kong Operator.

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

This section is optional. The rest of this guide uses a pre-published image, and the following information is provided if you want to package your own custom plugin.

Plugin-related files should be at the root of the image, so the Dockerfile for the plugin would look like this:

echo 'FROM scratch

COPY myheader /
' > Dockerfile

In this example, myheader is a directory that contains handler.lua and schema.lua.

Build the image:

docker build -t myheader:1.0.0 .

Next, push the image to a public or private registry available to the Kubernetes cluster where Kong Operator is running.

docker tag myheader:1.0.0 $YOUR_REGISTRY_ADDRESS/myheader:1.0.0
docker push $YOUR_REGISTRY_ADDRESS/myheader:1.0.0

In this example, the plugin is available in the public registry (Docker Hub) as kong/plugin-example:1.0.0. The following steps use the same source.

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

First, get your control plane ID:

CONTROL_PLANE_ID=$(curl -X GET "https://us.api.konghq.com/v2/control-planes?filter%5Bname%5D%5Beq%5D=gateway-control-plane" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" | jq -r ".data[0].id"
)

Run the following command to upload your schema file to your Konnect 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')}"

1. Install the plugin using the KongPluginInstallation resource. This resource makes the plugin available for instances of Kong Gateway resources:

   echo '
   kind: KongPluginInstallation
   apiVersion: gateway-operator.konghq.com/v1alpha1
   metadata:
     name: custom-plugin-myheader
   spec:
     image: kong/plugin-example:1.0.0
   ' | kubectl apply -f -
   

   Copied!

   Verify that the plugin is fetched and available by examining the status of the KongPluginInstallation resource:

   kubectl get kongplugininstallations.gateway-operator.konghq.com -o jsonpath-as-json='{.items[*].status}'
   

   Copied!

   The output should look like this:

   [
     {
           "conditions": [
                {
                     "lastTransitionTime": "2024-10-09T19:39:39Z",
                     "message": "plugin successfully saved in cluster as ConfigMap",
                     "observedGeneration": 1,
                     "reason": "Ready",
                     "status": "True",
                     "type": "Accepted"
                }
           ],
           "underlyingConfigMapName": "custom-plugin-myheader-hnzf9"
     }
   ]
   

   Copied!

   In case of problems, the respective conditions or respective resources will provide more information.

   The KongPluginInstallation resource creates a ConfigMap with the plugin content. Additional ConfigMaps are created when a plugin is referenced by other resources. The operator automatically manages the lifecycle of all these ConfigMaps.

2. Make the plugin available in a Gateway resource by referencing it in the spec.dataPlaneOptions.spec.pluginsToInstall field of the GatewayConfiguration resource. Plugins can be referenced across namespaces without any additional configuration.

   echo '
   kind: GatewayConfiguration
   apiVersion: gateway-operator.konghq.com/v2beta1
   metadata:
     name: kong
     namespace: default
   spec:
     dataPlaneOptions:
        deployment:
           replicas: 2
           podTemplateSpec:
             spec:
                containers:
                   - name: proxy
                     image: kong/kong-gateway:3.13
        pluginsToInstall:
           - name: custom-plugin-myheader
   ---
   apiVersion: gateway.networking.k8s.io/v1
   kind: GatewayClass
   metadata:
     name: kong
   spec:
     controllerName: konghq.com/gateway-operator
     parametersRef:
        group: gateway-operator.konghq.com
        kind: GatewayConfiguration
        name: kong
        namespace: default
   ' | kubectl apply -f -
   

   Copied!

3. Deploy an example service and expose it by configuring HTTPRoute with the custom plugin:

   kubectl apply -f https://developer.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml
   

   Copied!

   Next, add the HTTPRoute with the custom plugin. The configuration of the plugin is provided with the KongPlugin CRD, where the field plugin is set to the name of the KongPluginInstallation resource.

    echo "
    apiVersion: configuration.konghq.com/v1
    kind: KongPlugin
    metadata:
      name: myheader
      namespace: kong
      annotations:
        kubernetes.io/ingress.class: kong
    plugin: custom-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=myheader
   

   Copied!

Ensure that everything is up and running and make a request to the service.

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

myheader: my-first-plugin

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

myheader: my-first-plugin