Recently, I came across a request from one of our community users looking for a Kong plugin that could look up address details based on a few location search keywords. There are many libraries that support geocoding. I decided to pick up a Python Library as they are simple to use — and the Kong Gateway supports plugins written in Python since version 2.3.
To show the simplicity of using the Kong Python PDK, I’ve picked the GeoPy library, which will allow us to perform GeoCoding within our Kong Plugin.
When making an API request to Kong, the caller should be able to pass location search keywords such as "Trafalgar Square" in the request header. The plugin will use the GeoPy library to lookup the address for the search terms, determine the latitude and longitude for the address, and add them as additional headers to the request before passing it to the upstream.
The Python plugin support in Kong Gateway works by running a Python plugin server as a separate process on the same host as Kong Gateway and passing messages back and forth using Unix Sockets. The same mechanism is used for other external plugins in Kong, such as JS and Go.
In order to make things easier, I've put together a Docker-based environment for you to use. All you require is a machine with Docker and Docker Compose installed. Since it might take a minute or two to download the images and build our environment, I recommend running it now in the background as you keep reading:
The Docker Compose file sets up the following:
The Kong Gateway is configured to start a Python plugin server and load all the plugins in the kong-py-plugin directory. Currently, it contains a single plugin file: py-geocode.py. We start our plugin by importing the required Python libraries:
These Python libraries should be installed using pip in our Dockerfile used to build our Kong image.
Like all well-written plugins, the py-geocode plugin exposes all its parameters via configuration 😎
We also specify the version and priority of the plugin. We start by implementing the plugin object and the phases where we want to implement our custom logic.
There are five phases available for HTTP requests in the life-cycle of a Kong Gateway request:
Since we want to add headers to the request before sending it to the upstream, we do it in the access phase:
We'll also be setting default values for these various headers if they're not set in plugin configuration. After all, we want our plugin to be resilient 💪
Here's a snippet:
Finally, we perform our custom logic that:
We wrap all the logic in a try-except block for proper exception handling. This ensures that our plugin will not crash and burn when it hits an error 👊
The environment we're running uses Kong's declarative configuration capability. This means our Kong configuration is defined as a YAML file. Open up config/kong.yml, and you should see a service defined that proxies to httpbin.org/anything, and exposes a single route on the path "/any" that has our geocoding plugin applied:
The Kong Gateway only allows you to use plugins that are on an allowlist for security purposes. Open up docker-compose.yml and you can see that our plugin "py-geocode" has been enabled:
Finally, we enable the python plugin server using environment variables used to start the gateway container.
At this point the API gateway is ready to run our Python plugin, so let's go ahead and start it:
Once the containers are up, the Kong Gateway's proxy port will be available on port 8000 on our local machine.
Lets try a simple location search, specifying the location search keywords in the HTTP header "x-location-search" which is the default header that our plugin will look at. (We've not specified any plugin configuration in our declarative configuration.)
As you can see, our custom plugin has looked up the location address, latitude, and longitude and added them as upstream headers which are reflected by the httpbin response.
Suppose, we want the plugin to lookup the search keywords in the header "x-search" — and we want the location address to be added to a header "x-location-addr". We can set these in the plugin configuration, because remember: we wrote our plugin to be intelligent. Head over to the declarative configuration in the dbless_config directory and edit kong.yaml to specify these in the plugin configuration:
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, specifying the search location in the ‘x-search' header:
In a few lines of Python code, we have a working Kong Gateway plugin, complete with configuration options and exception handling!
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 making full use of the wide range of libraries provided by the Python ecosystem.
If you're looking for more plugin examples, take a look at the examples directory in the kong-python-pdk.
Questions? Post them on Kong Nation. And stay in touch by joining the Kong Community.
Meet Emily. She’s an API product manager at ACME, Inc., an ecommerce company that runs on dozens of APIs. One morning, her team lead asks a simple question: “Who’s our top API consumer, and which of your APIs are causing the most issues right now?”
It’s been almost a year since we released our Konnect Terraform provider . In that time we’ve seen over 300,000 installs, have 1.7 times as many resources available, and have expanded the provider to include data sources to enable federated managem
In the last two parts of this series, we discussed How to Strengthen a ReAct AI Agent with Kong AI Gateway and How to Build a Single-LLM AI Agent with Kong AI Gateway and LangGraph . In this third and final part, we're going to evolve the AI Agen
In my previous post, we discussed how we can implement a basic AI Agent with Kong AI Gateway. In part two of this series, we're going to review LangGraph fundamentals, rewrite the AI Agent and explore how Kong AI Gateway can be used to protect an LLM
This is part one of a series exploring how Kong AI Gateway can be used in an AI Agent development with LangGraph. The series comprises three parts: Basic ReAct AI Agent with Kong AI Gateway Single LLM ReAct AI Agent with Kong AI Gateway and LangGr
What Is RAG, and Why Should You Use It? RAG (Retrieval-Augmented Generation) is not a new concept in AI, and unsurprisingly, when talking to companies, everyone seems to have their own interpretation of how to implement it. So, let’s start with a r
In February 2024, Kong became the first API platform to launch a dedicated AI gateway, designed to bring production-grade performance, observability, and policy enforcement to GenAI workloads. At its core, Kong’s AI Gateway provides a universal API