Deploy custom plugins
Store the plugin contents in a ConfigMap
and mount the ConfigMap
as a volume on your Pods.
Prerequisites
Kong Konnect
If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.
- The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
-
Set the personal access token as an environment variable:
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
Copied to clipboard!
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.
Create a custom 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
0 directories, 2 files
Create a ConfigMap
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
Deploy your custom plugin
Kong provides a way to deploy custom plugins using both Kong Gateway Operator and the Kong Ingress Controller Helm chart. This guide shows how to use the Helm chart, but we recommend using Kong Gateway 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.
-
Create a
values.yaml
file in your current directory 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 to clipboard!If you need to include the migration scripts to the plugin, configure
userDefinedVolumes
anduserDefinedVolumeMounts
invalues.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 to clipboard! -
Upgrade Kong Ingress Controller with the new values
helm upgrade --install kong kong/ingress -n kong --create-namespace --values values.yaml
Copied to clipboard!
Using custom plugins
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.
-
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 to clipboard!Next, apply the
KongPlugin
resource by annotating theservice
resource:kubectl annotate -n kong service echo konghq.com/plugins=my-custom-plugin
Copied to clipboard! -
Create a Route to the
echo
service to test your custom plugin:
Validate your configuration
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"
curl -i "$PROXY_IP/echo"