Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.9.x (latest)
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
    • FAQ
    • Changelog
    • Architecture
    • Custom Resources
    • Deployment Methods
    • Kong for Kubernetes with Kong Enterprise
    • High-Availability and Scaling
    • Resource Classes
    • Security
    • Ingress Resource API Versions
    • Kong Ingress on Minikube
    • Kong for Kubernetes
    • Kong for Kubernetes Enterprise
    • Kong for Kubernetes with Kong Enterprise
    • Kong Ingress on AKS
    • Kong Ingress on EKS
    • Kong Ingress on GKE
    • Admission Controller
    • Getting Started with KIC
    • Upgrading from KIC 1.3.x
    • Getting Started using Istio
      • Using the KongPlugin Resource
      • Using the KongIngress Resource
      • Using KongConsumer and Credential Resources
      • Using the KongClusterPlugin Resource
      • Using the TCPIngress Resource
      • Using the UDPIngress Resource
    • Using the ACL and JWT Plugins
    • Using cert-manager with Kong
    • Configuring a Fallback Service
    • Using an External Service
    • Configuring HTTPS Redirects for Services
    • Using Redis for Rate Limiting
    • Integrate KIC with Prometheus/Grafana
    • Configuring Circuit-Breaker and Health-Checking
    • Setting up a Custom Plugin
    • Using Ingress with gRPC
    • Setting up Upstream mTLS
    • Exposing a TCP-based Service
    • Exposing a UDP-based Service
    • Using the mTLS Auth Plugin
    • Configuring Custom Entities
    • Using the OpenID Connect Plugin
    • Rewriting Hosts and Paths
    • Preserving Client IP Address
    • KIC Annotations
    • CLI Arguments
    • Custom Resource Definitions
    • Plugin Compatibility
    • Version Compatibility
    • Troubleshooting
    • Prometheus Metrics

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Prepare a directory with plugin code
  • Create a ConfigMap or Secret with the plugin code
  • Modify configuration
    • YAML
    • Helm chart
    • Deploy
    • Plugins in other languages
Kubernetes Ingress Controller
2.0.x
  • Home
  • Kubernetes Ingress Controller
  • Guides
  • Setting up custom plugin in Kubernetes environment
You are browsing documentation for an outdated version. See the latest documentation here.

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

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 and volumes configuration property.
  • KONG_PLUGINS environment variable is set to include the custom plugin alongwith 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 Kubernetes 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.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023