Installation and distribution of custom plugins

Uses: Kong Gateway

Package sources

To package your custom plugin code, we recommend LuaRocks, as it is installed along with Kong Gateway when using one of the official distribution packages. However, you can also use a regular packing strategy, such as tar.

When using LuaRocks, you must create a rockspec file, which specifies the package contents. For an example, see the Kong Gateway plugin template. For more information about the format, see the LuaRocks documentation on rockspecs.

To package your plugin as a rock, run the following commands from within the plugin repository:

Install it locally (based on the .rockspec in the current directory):
```
 luarocks make
```
Pack the installed rock:
```
luarocks pack {plugin-name} {version}
```
This creates a .rock file.

Important: luarocks pack is dependent on the zip utility being installed. More recent images of Kong Gateway have been hardened, and utilities such as zip are no longer available. If this is being performed as part of a custom Docker image, ensure zip is installed before running this command.

To do this without LuaRocks, use tar to pack the .lua plugin files into a .tar.gz archive. You can also include the .rockspec file if you do have LuaRocks on the target systems.

The contents of this archive should look like this:

tree {plugin-name}
{plugin-name}
├── INSTALL.txt
├── README.md
├── kong
│   └── plugins
│       └── {plugin-name}
│           ├── handler.lua
│           └── schema.lua
└── {plugin-name}-{version}.rockspec

Install the plugin

For a Kong Gateway node to be able to use the custom plugin, the custom plugin’s Lua sources must be installed on your host’s file system. You can do this with LuaRocks, Docker, or manually.

Regardless of which method you are using to install your plugin’s sources, you must install it for each node in your Kong Gateway cluster.

Via LuaRocks from the created rock

The .rock file is a self contained package that can be installed locally or from a remote server.

If the luarocks utility is installed in your system, you can install the rock in your LuaRocks tree:

luarocks install {rock-filename}

The filename can be a local name, or any of the supported methods, for example http://myrepository.lan/rocks/my-plugin-0.1.0-1.all.rock.

Via LuaRocks from the source archive

If the luarocks utility is installed in your system, you can install the Lua sources in your LuaRocks tree:

cd {plugin-name}
luarocks make

This will install the Lua sources in kong/plugins/{plugin-name} in your system’s LuaRocks tree, where all the Kong Gateway sources are already present.

Via a Dockerfile or docker run (install and load)

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

Note: Official Kong Gateway images are configured to run as the nobody user. When building a custom image, you must temporarily set the user to root to copy files into the Kong Gateway image.

Here’s an example Dockerfile that shows how to mount your plugin in the Kong Gateway image:

FROM kong/kong-gateway:latest

# Ensure any patching steps are executed as root user
USER root

# Add custom plugin to the image
COPY example-plugin/kong/plugins/example-plugin /usr/local/share/lua/5.1/kong/plugins/example-plugin
ENV KONG_PLUGINS=bundled,example-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"]

You can also include the following in your docker run command:

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

Manually

To avoid polluting the LuaRocks tree, you can point Kong Gateway to the directory containing the plugins.

You can do that with the lua_package_path property of your Kong Gateway configuration.

Those properties contain a semicolon-separated list of directories in which to search for Lua sources:

lua_package_path = /{path-to-plugin-location}/?.lua;;

In this example:

/{path-to-plugin-location} is the path to the directory containing the extracted archive. Replace it with the location of the kong directory from the archive.
? is a placeholder that will be replaced by kong.plugins.{plugin-name} when Kong Gateway tries to load your plugin. Do not change it.
;; a placeholder for the default Lua path. Do not change it.

For example, if the plugin something is located on the file system and the handler file is located at /usr/local/custom/kong/plugins/something/handler.lua, the path setup is:

lua_package_path = /usr/local/custom/?.lua;;

Multiple plugins

If you want to install two or more custom plugins this way, you can set the variable to something like:

lua_package_path = /path/to/plugin1/?.lua;/path/to/plugin2/?.lua;;

In this example:

; is the separator between directories.
;; still means refers to the default Lua path.

You can also set this property via its environment variable equivalent: KONG_LUA_PACKAGE_PATH.

Load the plugin

Add the custom plugin’s name to the plugins list in your Kong Gateway configuration:
```
plugins = bundled,<plugin-name>
```
If you are using two or more custom plugins, insert commas in between:
```
plugins = bundled,plugin1,plugin2
```
If you don’t want to include the bundle plugins, you can remove bundled.

You can also set this property via its environment variable equivalent KONG_PLUGINS.
Make the same update for each node in your Kong Gateway cluster.
Restart Kong Gateway to apply the plugin:
```
 kong restart
```
Or, if you want to apply a plugin without stopping Kong Gateway:
```
 kong prepare
 kong reload
```

Check that the plugin is loaded

To make sure your plugin is being loaded by Kong Gateway, you can start Kong Gateway with the log_level parameter set to debug:

log_level = debug

Then, you should see the following log for each plugin being loaded:

[debug] Loading plugin {plugin-name}

Remove a plugin

There are three steps to completely remove a plugin.

Remove the plugin from any Kong Gateway entity that uses it. Make sure that it is no longer applied globally nor for any Gateway Service, Route, or Consumer. This has to be done only once for the entire Kong Gateway cluster, no restart or reload required.
This step in itself will ensure that the plugin is no longer in use, but it remains available and it’s still possible to re-apply the plugin.
Remove the plugin from the plugins directive on each Kong Gateway node. Make sure to have completed the first step before doing so. After this step it will be impossible to re-apply the plugin. This step requires to restart or reload the Kong Gateway node.
To remove the plugin thoroughly, delete the plugin-related files from each of the Kong Gateway nodes. Before deleting the files, make sure to have completed the previous step, including restarting or reloading Kong Gateway. If you used LuaRocks to install the plugin, you can do luarocks remove {plugin-name} to remove it.

Distribute your plugin

Depending on the platform that Kong Gateway is running on, there are different ways of distributing custom plugins.

LuaRocks

You can use LuaRocks, a package manager for Lua modules. Your module doesn’t have to live inside the Kong Gateway repository, but it can if that’s how you’d like to maintain your Kong Gateway setup.

By defining your modules (and their eventual dependencies) in a rockspec file, you can install those modules on your platform via LuaRocks. You can also upload your module on LuaRocks and make it available to anyone.

This example rockspec uses the builtin build type to define modules in Lua notation and their corresponding file.

For more information about the format, see the LuaRocks documentation on rockspecs.

OCI Artifacts

Kong Gateway plugins can be packaged as generic OCI artifacts and uploaded to an OCI-compliant registry like Docker Hub or Amazon ECR for versioning, storage, and distribution.

The advantage of distributing plugins as OCI artifacts is that users can make use of a number of ecosystem benefits including tooling around building, pushing and pulling, and signing (for secure provenance attestation) of these artifacts. The steps below illustrate a sample flow for packaging, distributing, and verifying a Kong Gateway custom plugin as an OCI artifact.

On the machine where the plugin is developed, run the following steps:

Package the plugin:

tar czf my-plugin.tar.gz ./my-plugin-dir

Use the Cosign tool to generate a key pair for use signing and verifying plugins:
```
cosign generate-key-pair
```
The private key, cosign.key, should be kept secure and is used for signing the plugin artifact. The public key, cosign.pub, should be distributed and used by target machines to validate the downloaded plugin later in the flow.

There are also key-less methods for signing and verifying artifacts with Cosign. More information is available in their documentation.

Login to your OCI-compliant registry. In this case we’ll use Docker Hub:

cat ~/foo_password.txt | docker login --username foo-user --password-stdin

Upload the plugin artifact to the OCI registry using Cosign. This is the equivalent of running docker push {image} when pushing a local Docker image up to a registry.
```
cosign upload blob -f my-plugin.tar.gz docker.io/foo-user/my-plugin
```
The cosign upload command will return the digest of the artifact if it’s successfully uploaded.
Sign the artifact with the key pair generated in step 1:
```
cosign sign --key cosign.key index.docker.io/foo-user/my-plugin@sha256:xxxxxxxxxx
```
The command may prompt for the private key passphrase. It also may prompt to confirm that you consent to the signing information being permanently recorded in Rekor, the transparency log. For more information on Sigstore tooling and flows visit the documentation.

Then, on the Kong Gateway Data Plane nodes, run the following steps:

Ensure the cosign.pub public key is available. Verify the signature of the plugin artifact that you want to pull:
```
cosign verify --key cosign.pub index.docker.io/foo-user/my-plugin@sha256:xxxxxxxxxx
```
The command should succeed if the artifact was verified.
Use the Crane tool to pull the plugin artifact to the machine:
```
crane pull index.docker.io/foo-user/my-plugin@sha256:xxxxxxxxxx my-downloaded-plugin.tar.gz
```
The command should pull the artifact and save it to the working directory.
Unpackage the plugin. The downloaded .tar.gz file will contain a manifest file and another nested .tar.gz. This nested archive contains the plugin directory.
```
tar xvf my-downloaded-plugin.tar.gz
tar xvf xxxxxxxxxxxxxxxxxxxxx.tar.gz
```
Copy the plugin directory to the correct location following the install manually section. If you have not set a custom KONG_LUA_PACKAGE_PATH, copy the plugin to /usr/local/share/lua/5.1/kong/plugins.
Update Kong Gateway’s configuration to load the custom plugin by configuring plugins=bundled,my-downloaded-plugin in kong.conf or set the KONG_PLUGINS environment variable to plugins=bundled,my-downloaded-plugin

Troubleshooting

Kong Gateway can fail to start because of a misconfigured custom plugin for several reasons:

Error	Cause	Solution
`plugin is in use but not enabled`	You configured a custom plugin from another node and that the plugin configuration is in the database, but the current node you are trying to start does not have it in its `plugins` directive.	Add the plugin’s name to the node’s `plugins` directive.
`plugin is enabled but not installed`	The plugin’s name is present in the `plugins` directive, but Kong Gateway can’t load the `handler.lua` source file from the file system.	Make sure that the `lua_package_path` directive is properly set to load this plugin’s Lua sources.
`no configuration schema found for plugin`	The plugin is installed and enabled in the `plugins` directive, but Kong Gateway is unable to load the `schema.lua` source file from the file system.	Make sure that the `schema.lua` file is present alongside the plugin’s `handler.lua` file.