このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Setting up custom plugin in Kubernetes environment
This guide goes through steps on installing a custom plugin in Kong without using a Docker build.
Prepare a directory with plugin code
First, we need to create either a ConfigMap or a Secret with the plugin code inside it. 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.
We are going to setup a dummy plugin next. If you already have a real plugin, you can skip this step.
$ mkdir myheader && cd 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
' > handler.lua
$ echo 'return {
name = "myheader",
fields = {
{ config = {
type = "record",
fields = {
{ header_value = { type = "string", default = "roar", }, },
},
}, },
}
}
' > schema.lua
Once we have our plugin code available in a directory, the directory should look something like this:
$ tree myheader
myheader
├── handler.lua
└── schema.lua
0 directories, 2 files
You might have more files inside the directory as well.
Create a ConfigMap or Secret with the plugin code
Next, we are going to create a ConfigMap or Secret based on the plugin code.
Please ensure that this is created in the same namespace as the one in which Kong is going to be installed.
# using ConfigMap; replace `myheader` with the name of your plugin
$ kubectl create configmap kong-plugin-myheader --from-file=myheader -n kong
configmap/kong-plugin-myheader created
# OR using Secret
$ kubectl create secret generic -n kong kong-plugin-myheader --from-file=myheader
secret/kong-plugin-myheader created
Modify configuration
Next, we need to update Kong’s Deployment to load our custom plugin.
Based on your installation method, this step will differ slightly. The next section explains what changes are necessary.
YAML
The following patch is necessary to load the plugin. Notable changes:
- 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, simply mount multiple
ConfigMaps and include the plugin name in the KONG_PLUGINS
environment variable.
Please note that if your plugin code involves database migration then you need to include the below patch to pod definition of your migration Job as well.
Please note that the below is not a complete definition of the Deployment but merely a strategic patch which can be applied to an existing Deployment.
apiVersion: apps/v1
kind: Deployment
metadata:
name: ingress-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
Helm chart
With Helm, this is as simple as adding the following values to
your values.yaml
file:
# values.yaml
plugins:
configMaps: # change this to 'secrets' if you created a secret
- name: kong-plugin-myheader
pluginName: myheader
The chart automatically configures all the environment variables based on the plugins you inject.
Please ensure that you add in other configuration values you might need for your installation to work.
Deploy
Kustomize manifests are provided for illustration purposes only and are not officially supported by Kong. There is no guarantee of backwards compatibility or upgrade capabilities for our Kustomize manifests. For a production setup with Kong support, use the Helm chart.
Once, you have all the pieces in place, you are ready to deploy the Kong Ingress Controller:
# using YAML or kustomize
kustomize build github.com/hbagdi/yaml/kong/kong-custom-plugin | kubectl apply -f -
# or helm
$ helm repo add kong https://charts.konghq.com
$ helm repo update
# Helm 2
$ helm install kong/kong --values values.yaml
# Helm 3
$ helm install kong/kong --generate-name --set ingressController.installCRDs=false --values values.yaml
Once you have setup Kong with the custom plugin installed, you can use it like any other plugin.
First, 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 -
and then can annotate an Ingress or Service resource to instruct Kong on when to execute the plugin:
konghq.com/plugins: my-custom-plugin
Once you have got Kong up and running, configure your custom plugin via KongPlugin resource.
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.