Deploy Plugins

Once you have a functional custom plugin, you need to deploy it to Kong Gateway in order to use it. There are multiple methods for deploying custom plugins, which one you choose will largely depend on your particular Kong Gateway environment and other technology choices. This section will cover popular deployment options and provide a reference to further instructions.

Prerequisites

This page is the fifth chapter in the Getting Started guide for developing custom plugins. These instructions refer to the previous chapters in the guide and require the same developer tool prerequisites.

Step by Step

A very popular choice for running Kong Gateway is using container runtime systems. Kong builds and verifies Docker images for use in your deployments and provides detailed instructions on Docker deployments. Let’s look at a few options for running your custom plugin in a Kong Gateway container.

One popular option is building a Docker image that adds your custom plugin code and sets the necessary environment directly in the image. This solution requires more steps in the build stage of your deployment pipeline, but simplifies the data plane deployment as configuration and custom code is shipped directly in the data plane image.

Create a Dockerfile

Create a new file at the root of the my-plugin project named Dockerfile with the following contents

FROM kong/kong-gateway:3.10
# Ensure any patching steps are executed as root user
USER root

# Add custom plugin to the image
COPY ./kong/plugins/my-plugin /usr/local/share/lua/5.1/kong/plugins/my-plugin
ENV KONG_PLUGINS=bundled,my-plugin

# Ensure kong user is selected for image execution
USER kong

# Run kong
ENTRYPOINT ["/entrypoint.sh"]
EXPOSE 8000 8443 8001 8444
STOPSIGNAL SIGQUIT
HEALTHCHECK --interval=10s --timeout=10s --retries=10 CMD kong health
CMD ["kong", "docker-start"]

Build Docker image

When building a Docker image you will give it a tag to help identify it. We suggest you tag the image to include information specifying the Kong Gateway version and a version for the plugin. For example, the following will build the custom image, labeling the my-plugin portion of the version as 0.0.1:

docker build -t kong-gateway_my-plugin:3.10-0.0.1 .

Run the custom image

You can now use the Kong Gateway quickstart script to run the custom image and further test the plugin. The quickstart script supports flags that allow for overriding the docker repository (-r), image (-i) and tag (-t). Here is an example command:

curl -Ls https://get.konghq.com/quickstart | \
  bash -s -- -r "" -i kong-gateway_my-plugin -t 3.10-0.0.1

Test the deployed my-plugin plugin

Once the Kong Gateway is running with the custom image, you can manually test the plugin and validate the behavior.

Add a test service:

curl -i -s -X POST http://localhost:8001/services \
    --data name=example_service \
    --data url='https://httpbin.konghq.com'

Associate the custom plugin with the example_service service:

curl -is -X POST http://localhost:8001/services/example_service/plugins \
    --data 'name=my-plugin'

Add a new route you can use to send requests through:

curl -i -X POST http://localhost:8001/services/example_service/routes \
    --data 'paths[]=/mock' \
    --data name=example_route

Test the behavior by proxying a request to the test route and asking curl to show the response headers with the -i flag:

curl -i http://localhost:8000/mock/anything

curl should report HTTP/1.1 200 OK and show us the response headers from the gateway. Included in the set of headers, should be the X-MyPlugin

For example:

HTTP/1.1 200 OK
Content-Type: application/json
Connection: keep-alive
Content-Length: 529
Access-Control-Allow-Credentials: true
Date: Tue, 12 Mar 2024 14:44:22 GMT
Access-Control-Allow-Origin: *
Server: gunicorn/19.9.0
X-MyPlugin: https://httpbin.konghq.com/anything
X-Kong-Upstream-Latency: 97
X-Kong-Proxy-Latency: 1
Via: kong/3.6.1
X-Kong-Request-Id: 8ab8c32c4782536592994514b6dadf55

Other deployment options

Building a custom Docker image is not the only option for deploying a custom plugin.

Kubernetes deployments

Many users choose to run Kong Gateway on Kubernetes. Kong Gateway can be deployed on Kubernetes directly or by using Kong Ingress Controller. In either case, deploying custom plugins on Kubernetes is achieved by adding the custom plugin code to the cluster in a ConfigMap or Secret and mounting it into the Kong Gateway proxy pods. Additionally, the pods must be configured to load the custom plugin code from the mounted volume.

Kong provides a Helm chart which simplifies this process by configuring the necessary environment for the proxy pods based on the plugin you configure. For a non-Helm deployment, you will need to modify the environment directly.

The Custom Plugins documentation page provides instructions on deploying custom plugins using the Kong Helm chart or directly with standard Kubernetes manifests.

Overriding package path

When running Kong Gateway in bare metal or virtual machine environments, overriding the location that the Lua VM looks for packages to include is a common strategy for deploying a custom plugin. Following the same file structure as shown above, you can distribute the source files on the host machines and modify the lua_package_path configuration value to point to this path. This configuration can also be modified using the KONG_LUA_PACKAGE_PATH environment variable.

See the custom plugin installation documentation for more details on this option.

Note: In addition to bare metal or virtual machine environments, this strategy can work for volume mounts on containerized systems.

Building a LuaRocks package

LuaRocks is a package manager for Lua modules. It allows you to create and install Lua modules as self-contained packages called rocks. In order to create a rock package you author a rockspec file that specifies various information about your package. Using the luarocks tooling, you build an archive from the rockspec file and deliver and extract it to your data planes.

See the Packaging sources section of the custom plugin installation page for details on this distribution option.

Custom Plugins on Kong Konnect

Kong Konnect is Kong’s unified API platform as a service. Konnect supports custom plugins with some limitations. With an on-premise deployment, users manage Kong Gateway data planes as well as the control plane and, optionally, the backing database. In Kong Konnect, the control plane and database are fully managed for you which limits support for custom data entities and Admin API extensions in your plugin.

The Manage Plugins section of the Konnect documentation provides more information on deploying custom plugins to Kong Konnect.

What’s Next

Building custom plugins is a great way to extend Kong Gateway’s behavior and enable your business logic at the API gateway layer. However, custom plugin development is best used as a method of last resort. Kong Gateway supports a large number of pre-built plugins that cover many common use cases including serverless plugins that allow for custom business logic programming directly into a pre-built and supported plugin. See the Kong Plugin Hub for the full catalog of supported plugins.

The best way to run Kong Gateway is on Kong Konnect, Kong’s unified API platform as a service. Getting started with Kong Konnect is quick and free, login or sign up today.