Bootstrapping Your Development Environment
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.
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
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:
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:
If you have any questions, post them on Kong Nation.
To stay in touch, join the Kong Community.