Kong plugins - intro

What is Kong?

Kong is an API Gateway that provides a flexible abstraction layer to securely manage communication between clients and microservices through an API.

Kong is a Lua application running on top of nginx. The flexibility of such solution allows for extend functionality by creating custom plugins (native in Lua or GO, JS etc.) that can interact with the request/response flow, communicate with the upstream, or log processes.

Once Kong is running, every request will reach Kong first, and then it will be proxied to the destination service. Between the request and the response, Kong will execute any plugin that you decide to install. Kong effectively becomes the entry point for all API requests.

Kong Plugins

Kong as an API gateway operates in layer 7 (HTTP) which makes it a universal solution that can operate flexible on many levels. One of them is presented in the Workshop section.

Official plugins are hosted on https://docs.konghq.com/hub/. Their source code is located in the “kong” repository https://github.com/Kong/kong/tree/master/kong/plugins, which can be used as a starting point for creating your own plugins. Plugins are also bundled in any deployed Kong. For more information, see https://docs.konghq.com/gateway/2.8.x/plugin-development/file-structure/. Kong documentation is well maintaned, so it is more convenient to refer to it rather than copy here.

If you want to develop your own plugins, you need to create a proper environment where you can craft them. My choice was docker-compose, which has all Kong related must-have components, such as Kong and Postgres as a datastore. In my stack, I included Konga which is a GUI for Kong. Plugins use mount binding to a Kong container so after a plugin changes, you must execute the docker restart my-kong command.

Workshop

Objective

• I want to receive a response from “my-echoserver”, which is a container without Docker port mapping so ports are not available on localhost
• I want to inspect JWT tokens and:
  • Refuse expired tokens
  • Get specific claim from a token and add it to the response header
• I want to create an Admin API endpoint that will return a static text string

Prepare the Environment

Before you continue, make sure that your environment has the following tools installed:

• docker.io
• docker-compose (version: 1.29 or higher)
• httpie with the bearer extension

NOTE: At the time of creating this post, the latest version of Kong is 2.8 so I included a fixed version in Docker images and documentation links.

Create the docker-compose Environment

To download the repository and start the docker-compose stack, execute the following commands:

Each time you modify a plugin, remember to restart Docker container:

Dependencies (container+port level) are included in below diagram:

To check if your environment is up and running, execute this command:

The output should be:

Check the services, routes and plugins defined in the config file:

In this scenario, you want to enable a plugin that you are “developing” in the plugins directory and create the route /my-route that will query http://my-echoserver NOTE: the traffic occurs between containers.

There is a strict file structure requirement for the Kong plugin. For information, see https://docs.konghq.com/gateway/2.8.x/plugin-development/file-structure/. The plugin logic that handles the traffic flow is included in handler.lua and custom Admin API endpoints in api.lua

The declarative configuration file is used mostly as DB-less. In this workshop, however you we will import the declarative config to Kong postgres database. Alternatively, you can achieve the same results by making API calls

The configuration should be loaded after you start the stack:

To verify if everything is imported to database, execute the following set of commands:

All information that is kept in the Kong datastore can be retrieved through the API:

All Admin API calls can be done in a browser:

If you want to go a step further and visualize the environment in a more readable format, try Konga.

Konga - the Kong GUI

In the previous chapter, you directly verified that the datastore contains information about registered plugins, services, routes. You can get the same information from the Admin API through http requests. Alternatively, you can use the Kong GUI in a browser: http://localhost:1337. To authorize use following credentials: - login admin - password 123123123 Click CONNECTIONS (1) and then Activate to allow connection to the local Kong instance (2). Konga sends the http requests to the Admin API and visualizes it in the browser. Visit (3) for overview of the Kong cluster. Use SERVICES (4) and others panes to verify your local environment setup. You can check command-line and browser way and compare them.

The route defined for your service looks similar to the example:

When all services, routes, plugins are verified, send a request to service that will reach the internal my-echoserver endpoint. Only the Kong container has access to my-echoserver on port 80 (see the diagram).

The basic purpose of the echo-server is to return a response with the whole request. There are some more features that can control its behavior. For information, see the echo-server documentation. You can use some of those features to debug Kong. For example, you can set a specified response time from the echo-server to check how timeouts will impact the application, or specify response headers that will go from in response etc.

INFO: This online tool was used to generate example JWT HS256 tokens.

An expired token, back in the year 2020:

A token that will expire in the year 2050:

Use https://jwt.io to decode tokens and see the payloads.

Use the expired token:

The plugin inspected the claim “exp” in the JWT token and exited due to the expiration time.

When you use a valid token, the custom logic comes into play and the response header contains the claim from the JWT token:

The api.lua contains a new defined Admin API endpoint with the custom logic:

To check if it is working correctly, make a requests to /ping endpoint:

The objective is achieved. It is only a starting point in the topic of the Kong plugins development.

To clean up the environment after the workshop, execute the following command: