Building a Kong Gateway Plugin with JavaScript
We recently sat down to discuss the language for the next Kong Gateway Plugin Development Kit (PDK). Given the number of JavaScript developers in the world and the variety of libraries and debugging tools available, there was only one logical choice. I'm excited to share that with the Kong Gateway (OSS) 2.4 release, that functionality is now available to you all!
To show the power of the new JavaScript PDK, we're going to implement a plugin that adds X-Clacks-Overhead, a non-standardized HTTP header based on the work of Terry Pratchett to all responses.
Bootstrapping Your Development Environment
The JavaScript plugin support in Kong Gateway works by running a Node.js server on the same machine as Kong Gateway and passing messages back and forth using msgpack.
This means that we need a development environment that can run both the Kong Gateway and a Node.js process. You can configure this on your local machine, but to make things easier, I've put together a docker–based environment for you to use.
It might take a minute or two to download the images and build our Node.js environment. I recommend running it now in the background as you keep reading:
Creating Your First Plugin
The configuration provided in the environment we created reads all plugins from the plugins directory. It's currently empty as we have not created our first plugin yet.
The JavaScript PDK uses the name of the JS file as the name of the plugin. Let's go ahead and create a file called clacks.js in the plugins directory with the following contents:
The kong object passed into the access method is an instance of the JavaScript PDK provided by the plugin server. This means that we do not need to require kong-pdk in our plugins, as it is automatically made available.
There are five phases available for HTTP requests in the life-cycle of a Kong Gateway request:
- certificate – Executed once per request when the connection is SSL/TLS enabled
- rewrite – Performed before the API gateway does any routing
- access – All routing is done, and the plugin knows which service the request is bound to. This is the last phase before the API gateway makes a request to upstream
- response – Allows you to manipulate the response from the upstream. Implementing this phase has a performance penalty as it enables request buffering
- log – Executed after the request has been completed
Enable the Plugin
The environment we're running uses Kong's declarative config capability. That means that we need to update the config file to enable our new plugin. Open up config/kong.yml, and you should see a service defined that proxies to mockbin.org:
As our file name was clacks.js, our plugin will be called clacks. Let's enable the plugin in the definition now:
Kong Gateway only allows you to use plugins that are on an allowlist for security purposes, so we'll also need to add clacks to that list. Open up docker-compose.yml and edit the value of KONG_PLUGINS so that it looks like the following:
Making a Request
At this point the API gateway is ready to run our new plugin, so let's go ahead and start it:
The docker-compose.yml file forwards the API gateway port to our local machine. That means we can make requests to localhost:8000 to test our service.
I can see the X-Clacks-Overhead header in the response, which means that our plugin works as intended!
Making It Configurable
The custom JavaScript plugin we built today is a simple plugin that does one thing and does it well. I want to take a moment to show you how you can make that behavior customizable using plugin configuration too.
There is an ongoing discussion based on RFC 6648 about if custom headers need an X- prefix. Let's make our plugin configurable so that people can decide if they want to use the X- prefix.
Plugin configuration is controlled using the Schema property in module.exports at the end of clacks.js. Let's add an entry to define a use_prefix option that's a boolean with a default value of true:
Any configuration provided to the plugin is passed in using the constructor. Let's go ahead and capture that in clacks.js so that we can use it in our access method and update access so that it only adds the X- prefix if use_prefix is true:
If we run our plugin now, it will behave the same way as it did with a hardcoded X- prefix. Let's update our API gateway config in config/kong.yml to set use_prefix to false.
If we restart our API gateway by pressing Ctrl+C then running docker-compose up again, we should now be able to make a request to localhost:8000 and see Clacks-Overhead header without the X- prefix:
Conclusion
Just 20 lines of Javascript, and we have a working Kong Gateway plugin, complete with configuration options!
What we've built together is a trivial plugin, but using the environment provided and what you've learned about Kong's configuration, you can go ahead and build plugins to your heart’s content.
If you're looking for more plugin examples, take a look at some demo plugins:
- Convert GitHub API responses from JSON to YAML (config)
- Extract a Pokemon evolution chain from PokeAPI (config)
If you have any questions, post them on Kong Nation.
To stay in touch, join the Kong Community.
Once you've successfully set up a custom Kong plugin with JavaScript, you may find these other tutorials helpful: