このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Custom Plugins
Install a custom plugin in Kong without using a Docker build.
The recommended way to install custom plugins is with Kong Gateway Operator. See Kong custom plugin distribution with KongPluginInstallation for more information.
Create a custom plugin
For details about plugin development for Kong Gateway, see the Plugin Development guide.
-
Create a directory with plugin code.
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:
tree myheader
myheader ├── handler.lua └── schema.lua 0 directories, 2 files
-
Create a
ConfigMap
orSecret
with the plugin code. If you’re not sure which option is correct, use aConfigMap
.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 or secret from all the Lua files of the plugin.
The results should look like this:
Deploying custom plugins
Helm
The easiest way to use custom plugins with Kong is via the Helm chart. The chart automatically configures all the environment variables based on the plugins you inject.
-
Create a
values.yaml
file with the following contents. Ensure that you add in other configuration values you might need for your installation to be successful. -
Install Kong Ingress Controller.
helm repo add kong https://charts.konghq.com helm repo update helm install kong kong/ingress -n kong --create-namespace --values values.yaml
Non-Helm
The following examples assume that you have a deployment named
proxy-kong
. Change this to the name of your deployment as needed.
-
Modify configuration to update Kong’s Deployment to load the custom plugin.
The following patch is necessary to load the plugin.
- The plugin code is mounted into the pod via
volumeMounts
andvolumes
configuration property. -
KONG_PLUGINS
environment variable is set to include the custom plugin along with all the plugins that come in Kong by default. -
KONG_LUA_PACKAGE_PATH
environment variable directs Kong to look for plugins in the directory where we are mounting them.
If you have multiple plugins, mount multiple ConfigMaps and include the plugin name in the
KONG_PLUGINS
environment variable. - The plugin code is mounted into the pod via
Note that if your plugin code involves database migration then you need to include the following patch to pod definition of your migration Job as well. This is not a complete definition of the Deployment but a strategic patch which can be applied to an existing Deployment.
apiVersion: apps/v1
kind: Deployment
metadata:
name: proxy-kong
namespace: kong
spec:
template:
spec:
containers:
- name: proxy
env:
- name: KONG_PLUGINS
value: bundled,myheader
- name: KONG_LUA_PACKAGE_PATH
value: "/opt/?.lua;;"
volumeMounts:
- name: kong-plugin-myheader
mountPath: /opt/kong/plugins/myheader
volumes:
- name: kong-plugin-myheader
configMap:
name: kong-plugin-myheader
Using custom plugins
-
After you have setup Kong with the custom plugin installed, you can use it like any other plugin. Create a KongPlugin custom resource:
echo ' apiVersion: configuration.konghq.com/v1 kind: KongPlugin metadata: name: my-custom-plugin config: header_value: "my first plugin" plugin: myheader ' | kubectl apply -f -
-
Add the
konghq.com/plugins
annotation to your Service, Ingress or Gateway API route to instruct Kong to execute the plugin:konghq.com/plugins: my-custom-plugin
Plugins in other languages
When deploying custom plugins in other languages, especially Golang, the built binary is larger than the size limit of ConfigMap. In such cases, consider using an init container to pull large binaries from remotes like S3 buckets, or build a custom image that includes plugin runtimes and the plugin itself.
To read more about building a custom image, see use external plugins in container and Kubernetes.