Adding custom plugins in Konnect

Note: The UI is not available when using KIC in Konnect. Please use the Konnect API instead.

1. From the Gateway Manager, open a control plane.
2. Open Plugins from the side navigation, then click Add Plugin.
3. Open the Custom Plugins tab, then click Create on the Custom Plugin tile.
4. Upload the schema.lua file for your plugin.
5. Check that your file displays correctly in the preview, then click Save.

Upload the schema.lua file for your plugin using the /plugin-schemas endpoint:

curl -i -X POST \
  https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugin-schemas \
  --header 'Content-Type: application/json' \
  --data "{\"lua_schema\": <your escaped Lua schema>}"

Tip: You can use jq to pass your schema directly from the file instead of manually escaping it:

--data "{\"lua_schema\": $(jq -Rs '.' < REPLACE-PATH-TO-SCHEMA-FILE)}"

You should get an HTTP 201 response.

You can check that your schema was uploaded using the following request:

curl -i -X GET \
  https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugin-schemas

This request returns an HTTP 200 response with the schema for your plugin as a JSON object.

Follow the Kong Gateway plugin deployment and installation instructions to get your plugin set up on each node.

If you are running Kong Gateway on Docker, the plugin needs to be installed inside the Kong Gateway container for each node. Copy or mount the plugin’s source code into the container.

Let’s consider this sample custom plugin. This is composed of a schema.lua and a handler.lua file. On your filesystem, let’s create a similar path structure to the following:

.
└── kong
    └── plugins
        └── example-plugin
            ├── handler.lua
            └── schema.lua

You can do this in one of two ways: mounting the files with docker run, or using a Dockerfile.

To mount and enable this custom plugin on a data plane node:

1. In your control plane, go to Data Plane Nodes, then click New Data Plane Node.
2. Choose Linux (Docker) and Generate a certificate.

3. Copy the generated docker run command and add the following snippet to it:

    -v "/tmp/plugins/kong:/tmp/custom_plugins/kong" \
    -e "KONG_PLUGINS=bundled,example-plugin" \
    -e "KONG_LUA_PACKAGE_PATH=/tmp/custom_plugins/?.lua;;" \
   

   Substitute your own source and target paths, as well as the plugin name.

   A sample quickstart command would look something like this:

    docker run -d \
      -v "/tmp/plugins/kong:/tmp/custom_plugins/kong" \
      -e  "KONG_PLUGINS=bundled,example-plugin" \
      -e "KONG_LUA_PACKAGE_PATH=/tmp/custom_plugins/?.lua;;" \
      -e "KONG_ROLE=data_plane" \
      -e "KONG_DATABASE=off" \
      -e "KONG_VITALS=off" \
      -e "KONG_NGINX_WORKER_PROCESSES=1" \
      -e "KONG_CLUSTER_MTLS=pki" \
      -e "KONG_CLUSTER_CONTROL_PLANE=<example>.cp0.konghq.com:443" \
      -e "KONG_CLUSTER_SERVER_NAME=<example>.cp0.konghq.com" \
      -e "KONG_CLUSTER_TELEMETRY_ENDPOINT=<example>.tp0.konghq.com:443" \
      -e "KONG_CLUSTER_TELEMETRY_SERVER_NAME=<example>.tp0.konghq.com" \
      -e "KONG_CLUSTER_CERT=<cert>" \
      -e "KONG_CLUSTER_CERT_KEY=<key>" \
      -e "KONG_LUA_SSL_TRUSTED_CERTIFICATE=system" \
      -e "KONG_KONNECT_MODE=on" \
      -p 8000:8000 \
      -p 8443:8443 \
      kong/kong-gateway:<version>
   

4. Run the command to start a data plane node with your custom plugin loaded in.

To copy the plugin using a Dockerfile instead, see the Kong Gateway custom plugin docs.