Lessons learned about Kong plugins.

Original image by Craig R. Kirkby

This is the second installment on a Kong API Gateway related series, if you already know that Kong is want to learn a bit more so you can save some time in the future just continue scrolling, if you are not sure if you should just continue, please do take a look at this article: Deploying Kong API gateway in Kubernetes — All the what, why, where and (some) how questions

At first when we had to choose an api gateway, Kong attracted us because of the large list of built-in plugins that are already available in the product.
So we focused on getting it running in the way we needed, an internal and external ingress controller*.

Once that was completed and we could deploy ingresses internally as well as externally with just changing a word in the annotations of the ingress we thought the hardest part was complete. There was no way that the plugin configuration could take us a week, or at least that’s what we thought.

In this article I will share all the gotchas I wish I was told a month ago.

Online resources

Kong has been out there for quite some time now and there is a lot of material on how to deploying, configuring and testing it. How ever they do not go as far as you probably need to, or at least not as we needed to.

Most of the documentation and online examples, such as articles, videos or even recordings of presentations at big events, just tell you how to configure it using the Kong admin API, which is ok for testing your configuration. There are also a lot of examples on how to tweak Kong using their custom yaml config file, which is of not the best approach in a kubernetes environment.

At this point you are probably starting to panic, well don’t!!! That’s the idea of this article remember.

* there is another article coming on that shortly I will add the link there then

Undertanding how Kong Plugins work

What I like the most about kong plugins is that you can configure a plugins to best suit your needs and then use it in multiple places or the other way around you can configure how the plugin behaves just by changing one config file. How cool is that? How ever if for some reason you need a particular endpoint or set of endpoints to behave differently with the same plugin you can still that to, really it is that flexible.

So, Kong plugins can be associated, according to their documentation at the time of writing this article to

• a (kong) route
• a (kong) service
• a (kong) consumer
• or globally

This translate for most usage into

• a kubernetes ingress, and
• a kong consumer

I spent quite some time trying to link a request-termination plugin to an ingress rule just to learn (the hard way) that it needed to be linked to the consumer instead. If you don't know that a consumer is please refer to this article.

Now that we understand conceptually how configure a plugin to be actually used, lets see how we actually configure and using it

As I mention before and I am just repeating this because this is something very confusing if you are configuring kong plugins in kubernetes for the first time. Here is an example (from their documentation) on how to configure it imperatively via the admin API:

Imperative configuration of a plugin via Kong admin API

And here is how to do the same with the kong custom YAML file, aka DB-less configuration:

DB-less configuration of a plugin

As it can be seen in the images above the configuration needs to be linked to the route (in this case), the service or the consumer.

Porting the Kong Custom YAML to a Kubernetes YAML

So lets try to convert this config into a kubernetes friendly yaml configuration. I could not find a place to learn this right away and having to spend some time trying to get it running made me realize that this was worth an article, anyway, lets get down to business.

Porting Kong custom config to k8s yaml config

At first glace it all does look obvious. But allow me to go line by line anyways.

1. We need to create a kubernetes object type KongPlugin (light green arrow) hitting the endpoint configuration.kong.hq.com/v1 (dark green arrow)
2. We need to give this config a name so we can reference this in the ingress controller configuration, or the Kong consumer configuration. The name in the example is set to our-rate-limiting-config and it is marked with the yellow arrow.
3. The namespace as well as the enabled field are optional, but if you want to store this config in git it is recommended to have that declared. Here it is marked with the blue arrow and we are targeting the default namespace.
4. And we reach the Kong plugin specific config. The name field in the left translate to the plugin on the right, this transformation is marked by the red arrow.
5. Last but no least, the plugin configuration under the config key in the left becomes the config key in the right, but notice that it is placed at the root level of the yaml. And all key-values pairs just moves under this config field.

This configuration is not particularly bound to anything, but it could easily be bound to multiple kubernetes objects (if needed), allowing us to have different type of services for different users or subscriptions.

Binding the plugin to an endpoint

The easiest way to do this is to create an ingress with a regular ingress yaml file and add a kong specific annotation konghq.com/plugin to reference the plugin configuration we just created.

Kubernetes ingress definition yaml referencing the rate-limiting plugin

Binding the plugin to a consumer

Here is how we would normally add a consumer to our kong deployment. In order to apply the rate-limiting plugin configuration setup above, we need to add the same annotation we added in the ingress YAML.

Setting up the rate-limiting plugin for a consumer

And just so you can have the whole picture, here is the secret config we are referencing above, this is how we setup the API key for that consumer.

Setting up the API key for the consumer

Conclusion

Kong comes with a lot super useful plugins ready to use right out of the box. They have a very extensive documentation and community. And I think that with this article, anyone (with a high level understanding on kubernetes) can quickly set up the right plugin to meet their needs.

Thanks for staying with me until this point and clap if you enjoyed it. Feel free to reach me out on @frankmb2.