This tutorial shows you how easy it is to build a custom Lua plugin for Kong Gateway. My Kong Lua plugin example will automatically add a custom header to any response sent out, indicating the current plugin version.
[Kong API Gateway](https://konghq.com/kong)Kong API Gateway is built on [OpenResty](https://openresty.org/en)OpenResty, which extends the [NGINX](https://nginx.org/en)NGINX proxy server to run Lua scripts. It sits as a proxy between a client’s requests and routes them to defined services.
With the open source Kong Gateway, developers can build **plugins** on a per-service basis. These plugins help you build policies and Lua functions important to your architecture. You can build plugins in real time, on requests your services receive or on custom responses sent back to the client. These plugins provide an easy way to add advanced functionality and features to your implementation. For example, you could create a plugin to implement logging, rate limiting, authentication and more. Kong even had a customer create a custom plugin for Open Policy Agent.
[Kong Hub](https://docs.konghq.com/hub)Kong Hub has a wide range of existing plugins created by both Kong and third-party plugin authors. A few exciting plugins include:
In addition to using pre-built plugins, you can also build your own. For example, you could create a custom Lua plugin for Kong API Gateway that hooks into the request/response phases or even works with streaming data. Kong's plugin development kit ([PDK](https://docs.konghq.com/gateway-oss/2.0.x/pdk)PDK) allows you to write plugins with functionality ranging from authentication and traffic control to logging and monitoring. Plugins can be written in Lua, [Go](https://docs.konghq.com/gateway-oss/latest/external-plugins/?_ga=2.211379603.760851772.1618239833-852472749.1605808164#developing-go-plugins)Go, [Python](https://docs.konghq.com/gateway-oss/latest/external-plugins/?_ga=2.149898416.760851772.1618239833-852472749.1605808164#developing-python-plugins)Python or [Javascript](https://docs.konghq.com/gateway-oss/latest/external-plugins/?_ga=2.149898416.760851772.1618239833-852472749.1605808164#developing-javascript-plugins)Javascript. The plugin development kit has open source templates and tools designed to get you started.
Kong helps you get started building plugins through [Pongo](https://github.com/Kong/kong-pongo)Pongo, which serves several roles. Pongo provides a framework for you to test your plugin. It also ensures that you configure your system for Kong, including fetching any dependencies. *And* it sets up a test Kong environment so that you can run your plugin in real time.
Pongo requires [docker-compose](https://docs.docker.com/compose)docker-compose and [curl](https://curl.se)curl. After installing those, clone Pongo and install the Pongo CLI (a symlink to a script file) like this:
PATH=$PATH:~/.local/bin
git clone https://github.com/Kong/kong-pongo.git
mkdir -p ~/.local/bin
ln -s $(realpath kong-pongo/pongo.sh) ~/.local/bin/pongoThe [kong-plugin](https://github.com/Kong/kong-plugin)kong-plugin repository provides a simple template to get started writing a custom Lua plugin for Kong API Gateway. Go ahead and clone that repo into a new directory called kong-api-version-plugin:
git clone https://github.com/Kong/kong-plugin.git kong-api-version-pluginIn the kong-api-version-plugin project, there are two directories to focus on:
With those files renamed, type pongo run to get started. Docker will fetch the images necessary to get an environment set up. After some time, your terminal will print lines like these:
Kong version: 2.3.2
[==========] Running tests from scanned files.
[----------] Global test environment setup.
[----------] Running tests from /kong-plugin/spec/api-version/01-unit_spec.lua
...
[----------] Running tests from /kong-plugin/spec/api-version/02-integration_spec.luaOnce those tests pass, the test setup is complete! Next, get access to a local Kong instance. Type pongo shell, which drops you into the Kong container. No need to start the dependencies since they were already started automatically by the pongo run command above. In this prompt, enter the next two lines:
kong migrations bootstrap --force
kong startWhile still in the Kong shell, run curl -i http://localhost:8000/ to ensure that you can communicate with Kong on its default port, 8000. If you get an error that says {“message”:”no Route matched with those values”}, that’s perfectly fine! The critical thing to observe is that Kong handled the request.
Before testing the plugin, you'll need to set up a dummy Service. A Service is an upstream API that Kong considers as a microservice to manage. Since this is an example, I'm going to set up a dummy service that points to any URL. You can use Kong’s Admin API to do this:
curl -i -X POST \
--url http://localhost:8001/services/ \
--data 'name=example-service' \
--data 'url=http://konghq.com'With the Service set up, you'll need to add a route so that the requests can be proxied through Kong:
curl -i -X POST \
--url http://localhost:8001/services/example-service/routes \
--data 'hosts[]=example.com'Last but not least, you'll need to add the plugin to the Service:
curl -i -X POST \
--url http://localhost:8001/services/example-service/plugins/ \
--data 'name=api-version'Next, test this setup with a final cURL call. Only this time, you can ignore the body and just look at the headers:
curl -I -H "Host: example.com" http://localhost:8000/If you see a header with the key name of Bye-World, you’re ready to write some code!
Within kong/plugins/api-version, you’ll see two files:
In handler.lua, you’ll notice several methods that take the form of function plugin:<name>. These methods run during the execution lifecycle of Kong. You can find a complete list of their descriptions [in the API reference documentation](https://docs.konghq.com/gateway-oss/2.0.x/plugin-development/custom-logic/#available-contexts)in the API reference documentation. For this example plugin, I'll concentrate on the plugin:header_filter, since my plugin will send a custom header.
There should already be a line in the plugin that contains a custom header:
kong.response.set_header(plugin_conf.response_header, "this is on the response")When you run curl -i http://127.0.0.1:8000/, you should see a response header with the following line:
Bye-World: this is on the responseAs you might surmise based on the set_header function, plugin_conf.response_header controls the header key, while the header value is explicitly defined here in the plugin:header_filter method.
Change “this is on the response” to read plugin.VERSION, which is a constant set at the very top of the file. In your Kong shell, run kong reload, execute the same curl command and notice that the value changes. Any time you modify your plugin code, you can run kong reload to reload it and iterate quickly on changes.
Next, take a look at schema.lua. There’s a field named response_header with a default value of Bye-World. You could just change this to something like Version and expect it to reflect in the response header. But I'll dig a little deeper. One of the primary use cases of this schema is to allow users to set their own values in their plugin. When adding a plugin to a service, you can set up its configuration by passing some data values.
Here’s an example. First, get a list of all of the Kong plugins:
curl http://localhost:8001/pluginsGrab the id of the api-version plugin, and use it to delete the plugin:
curl -X DELETE http://localhost:8001/plugins/4f249ee9-etcAdd the plugin back. Only this time, set a non-default value for the response_header:
curl -i -X POST \
--url http://localhost:8001/services/example-service/plugins/ \
--data 'name=api-version' \
--data 'config.response_header=Plugin-Version'Make one more call to curl -i http://127.0.0.1:8000/ and notice that while the schema.lua code defines a default of Version, the response is Plugin-Version, just like I set up in my configuration. You can use various properties in a schema, so be sure to check out [the reference documentation](https://docs.konghq.com/gateway-oss/2.3.x/plugin-development/plugin-configuration/#schemalua-specifications)the reference documentation for more information.
The implementation is complete. You can now begin writing tests to ensure the functionality remains consistent.
Pongo comes with its test runner, which loads your plugin in Kong and tests two significant aspects: 1) it provides a unit test to validate the schema, and 2) it provides an integration test that simulates an end-to-end request. It does this by automating all of the steps we went through above:
The logic to perform this setup is available to you automatically by the fixtures and methods available in Pongo. All you’ll need to do is write the test logic. To make requests to this test Kong node, you can use the client.
If your terminal is still in the Kong shell, type exit to return to your command prompt. Then, go ahead and run pongo run one more time. You should receive an error that resembles the following:
/kong-plugin/spec/api-version/02-integration_spec.lua:80: Expected header:
(string) 'bye-world'
But it was not foundIf you scroll down to around line 80, you'll notice that the client makes a request to the Kong node, but in the response, it expects a header value that we changed. To fix this, you'll need to change the existing strings to match what we provided in our handler:
local header_value = assert.response(r).has.header("Version")
assert.equal("0.1", header_value)Another pongo run should confirm that the test now passes.
As well, it's a good idea to add a unit test for any large schema changes you might have made. We didn't really do that in this tutorial. Nonetheless, let's go ahead and add a test in 01-unit_spec.lua that asserts that the response header will have a default value. We can test this by passing nil during the configuration step:
it("provides a default response_header", function()
local ok, err = validate({
request_header = "My-Request-Header",
response_header = nil, })
assert.is_nil(err)
assert.is_truthy(ok)
end)
For a final code cleanup, you can run pongo lint to run [LuaCheck](https://github.com/luarocks/luacheck)LuaCheck. LuaCheck will do a static analysis of the code and report any obvious problems (e.g., accidental global variables, etc.). It's always a good idea to lint your code because Lua is a dynamic language, and you could easily miss typos.
Kong plugins are a powerful way to instantly implement policies and functionality in your [API gateway](https://konghq.com/learning-center/api-gateway/what-is-an-api-gateway)API gateway. With [Pongo](https://github.com/Kong/kong-pongo)Pongo and the [kong-plugin](https://github.com/Kong/kong-plugin)kong-plugin template, Kong provides much of the starting boilerplate for you. In this example, I've only just begun to explore how plugins can allow Kong Gateway to gain expanded capabilities. If you’d like a more in-depth look at some of the things you can build, check out [the Plugin Development Guide](https://docs.konghq.com/gateway/latest/pdk/#plugin-development-kit)the Plugin Development Guide in Kong's documentation.
Check out the following further information:
**Have questions or want to stay in touch with the Kong community? Join us wherever you hang out:**
⭐ [Star us on GitHub](https://github.com/Kong/kong)Star us on GitHub
🐦 [Follow us on Twitter](https://twitter.com/thekonginc)Follow us on Twitter
🍻 [Join our Meetups](https://www.meetup.com/pro/kong)Join our Meetups
In the Kubernetes world, the Ingress API has been the longstanding staple for getting access to your Services from outside your cluster network. Ingress has served us well over the years and can be found present in several dozen different implementa
[](https://konghq.com/blog/engineering/gateway-api-from-early-years-to-ga)
This post is part of our Kong Champions series, where real Kong users walk you through technical challenges, use cases, and new technology they're using in their day-to-day. Sign up here to become a Kong Champion. As a Kong user, I've had the oppo
[](https://konghq.com/blog/engineering/kong-saml-plugin-examples-and-uses)
Kong will crash on the ARM64 platform (the machine with Mac M1/M2 chips or any ARM64 platform). The error message shows the crash is triggered by the SIGILL signal, which means there is an illegal instruction in the Kong binary code. And it turns out
[](https://konghq.com/blog/engineering/sigill-kong-crash-on-arm64)
The release of Kuma 2.3 brings experimental support for GAMMA (Gateway API for Mesh Management and Administration) resources. Kuma has long supported Gateway API with the built-in gateway for ingress traffic but with GAMMA support, users can specify
[](https://konghq.com/blog/engineering/gamma-and-kuma)
A developer portal is a storefront to your APIs (the products) that internal and external developers are trying to consume. The Kong Developer Portal provides a single source of truth for all developers to locate, access and consume services. With
[](https://konghq.com/blog/engineering/customize-kong-developer-portal)
Two of the best (in my opinion) features in Konnect are the ServiceHub and Dev Portal. However, they're also two of the most misunderstood. Aren't they the same thing? Why would you need a ServiceHub vs. Dev Portal? Well, I'm glad you asked! The r
[](https://konghq.com/blog/engineering/service-hub-developer-portal)
Want to learn more about the nuts and bolts of APIOps? Download our eBook, Unlocking the Full Potential of your APIs with APIOps , and learn about the stages of APIOps, get an understanding of the technical assets required, and explore the tooling
[](https://konghq.com/blog/engineering/automating-developer-pipeline-apiops)