kong-template

A template repository for getting started with Kong, the cloud-native API gateway.

Description

This setup helps to develop and test multiple kong plugins. It uses kong-pongo to run tests against the plugins and konga for dashboard.

Features

Setup to develop and test multiple kong plugins locally.
Public kong plugins can be submoduled and used.
Supports running tests on individual plugins using kong-pongo
Supports running integration tests across multiple plugins, again using kong-pongo.
Pre-seeded konga configuration for local dashboard access.
Build deployable custom kong image with plugins configured.
Easy make targets for the functionalities defined.
Dockerfile can be used to build kong image with custom plugins.

Directories

The repo has the following important directories:

kong-plugins: This is a repository of all kong custom plugins. Some of them can be submoduled from other public git repositories.
kong-pongo: Tooling to run plugin tests with Kong.

Setup

Clone master branch with submodules

git clone --recurse-submodules -j8 https://github.com/razorpay/kong-template
cd kong-template

To fetch a specific branch

git clone https://github.com/razorpay/kong-template
cd kong-template
git fetch origin <branch>
git submodule init
git submodule update

Initialize using make

make init # This will make pongo executable available in your host's path.
make help # This will print all available make targets.
down                           Brings down kong, cassandra and konga
help                           Shows help.
init                           Initialization: Symblinks kong-pongo's executable to host's path.
lint                           Runs linters for all kong plugins.
test-clean                     Cleans test setup
test-each                      Runs individual tests for each kong plugin.
test-integration               Runs integration tests across all kong plugins.
test                           Runs all tests for all kong plugins.
up                             Brings up kong, cassandra and konga

Export KONG_VERSION environment variable. The version is mentioned in Makefile

export KONG_VERSION=<version>

To change KONG_VERSION

Change KONG_VERSION in Makefile
Export the updated KONG_VERSION environment variable.
Update the kong image version in Dockerfile i.e FROM kong:2.0.x

Bring up kong, cassandra and konga

make up
# Access kong at http://127.0.0.1:8000/
# Access kong admin API at http://127.0.0.1:8001/
# Access konga at http://127.0.0.1:1337/
# Default user credentials for konga: root/root123

Bring down kong, cassandra and konga

make down

Plugin development

All plugins are available under kong-plugins dir.

Including an open-source plugin

Add the open-source plugin as a submodule in kong-template

git submodule add http://github.com/Kong/kong-plugin

Interacting with a plugin

You can cd to any of them and make use of pongo executable to interact with the plugin project and environment e.g. getting into a kong container shell, running linters and tests etc. Refer kong-pongo's readme for various project and environment actions.

After cd-ing to plugin project dir do ensure required components are up

pongo up

And now can get into kong's container shell

pongo shell

From within kong's container shell

# To see all environment variables.
env

# To run one time migrations if any.
kong migrations up
kong migrations bootstrap

# To start kong server
kong start

curl -I localhost:8001 # curl should be preinstalled and if not can do `apk add curl`.
# HTTP/1.1 200 OK
# Server: openresty
# Date: Fri, 27 Mar 2020 11:24:49 GMT
# Content-Type: text/html; charset=UTF-8
# Connection: keep-alive
# Access-Control-Allow-Origin: *
# X-Kong-Admin-Latency: 256

# Reload kong after changes in plugin code.
# This works because `kong-plugins/kong-plugin` is mounted on `/kong-plugin` in container
kong prepare
kong reload

Enabling the plugin

Right now, the steps to enable a plugin in the kong-template container image are manual. This is not automated, as of now, as number of plugins are handful.

Edit the kong.conf configuration file to make the following changes

Add plugin path in lua_package_path as semi-colon separated values. Notice double semi-colons in the end.

lua_package_path=/kong-plugins/kong-plugin/?.lua;;

kong-plugin here is the name of the plugin.

Add the plugin in plugins as comma-separated values

plugins=myplugin