How to debug Kong plugins on Windows and Mac-OS
Kong is an open-source API management system based on NGINX, which aims to secure, manage and extend APIs and Microservices. It is written in Lua and supports a plugin oriented architecture. Debugging of Lua code is supported by different IDEs like ZeroBrane Studio http://studio.zerobrane.com/ and Eclipse Lua http://www.eclipse.org/ldt/ but nevertheless the setup of a development environment supporting debugging of Kong plugins on Windows and Mac-OS machines is not trivial.
This tutorial describes how to create an environment for creating, configuring, testing and debugging of a "Hello-World" Kong plugin both on Windows and Mac-OS. We used Windows 7/64 and Mac-OS "El Capitan", but the description should work also for newer Windows and older Mac-OS versions.
The preferred method is based on the Vagrant distribution of Kong (https://github.com/Mashape/kong-vagrant). Since there is no Windows distribution of Kong this is the only option if you work on Windows. Using Kong Vagrant images requires Lua remote debugging. ZeroBrane Studio currently seems the only IDE supporting this scenario. For Mac-OS we describe as an alternative a brew based installation at the end of this tutorial.
As a prerequisite you need to install Vagrant https://www.vagrantup.com/downloads.html , VirtualBox https://www.virtualbox.org/wiki/Downloads , SoapUI http://www.soapui.org/downloads/latest-release.html and ZeroBrane Studio http://studio.zerobrane.com/download . We experimented with Eclipse Lua LDT https://eclipse.org/ldt/#installation but didn't succeed with remote debugging kong plugins running in a vagrant image.
For windows we need a Unix shell, we recommend installing git https://git-scm.com/download/win which comes with a bash shell for windows which can be started right clicking on a directory in explorer.
Setup a Vagrant Kong Image
Next we follow the documentation in https://github.com/Mashape/kong-vagrant/blob/master/README.md to setup a kong vagrant image using bash either on Windows or MacOS. First start VirtualBox, then open a terminal and run the following commands on your host machine.
Create an empty directory /path/to/kong/clone/ on your machine which later is mounted inside the vagrant image:
The vagrant location of this mounted host folder is /kong.
Clone Kong to your host for debugging in ZeroBrane Studio
We need to do some preparations necessary for debugging our kong plugin:
Now the directory /usr/local/share/lua/5.1 on the vagrant image points to its copy on the host machine. Local changes there will also affect the vagrant kong installation.
Since ZeroBrane Studio can only debug files inside one source file tree (the project location) we need to copy the kong entry point into the mounted lua source tree:
Install ZeroBrane Studio on your Vagrant image
Next we need to install the linux distribution of ZeroBrane Studio in the vagrant image , download https://download.zerobrane.com/ZeroBraneStudioEduPack-1.20-linux.sh and copy it onto the part of the file system shared with the vagrant image. Inside a vagrant ssh execute:
You may see some error messages related to GUI installation you can ignore since we are only interested in the lua/so files required for remote debugging located in /opt/zbstudio/lualibs.
Create a Kong plugin using ZeroBrane Studio
Now, back to the host, start ZeroBrane Studio and set the project directory to /path/to/kong/clone/5.1, our shared copy of the kong lua files (Project/Project Directory/Choose).
Next we create a sample "HelloWorld" plugin as described in http://streamdata.io/blog/developing-an-helloworld-kong-plugin/.
First the plugin configuration located in kong/plugins/helloworld/schema.lua:
Then the handler inheriting from BasePlugin.lua in kong/plugins/helloworld/handler.lua:
And finally the plugin implementation in kong/plugins/helloworld/access.lua:
Note that we added the required path definitions for lua debugging here. You have to replace the IP adress inside the require('mobdebug').start("172.20.0.55") command by your IP adress. To find out your IP adress on Windows use
On MacOs you may use
We placed the require('mobdebug') call inside the "execute method". This is because this method is executed in a separate coroutine, triggered by the Mockbin webservice call. Coroutines are not debugged by default. Alternatively coroutine debugging can be enabled by adding a require('mobdebug').on() call. This has a similar effect then starting debugging from the "execute" method. Coroutine debugging is briefly covered in the ZeroBrane Studio documentation: https://studio.zerobrane.com/doc-lua-debugging#coroutine-debugging.
Next we adapt the plugin configuration section we copied earlier to bin/kong.yml enabling
the new helloworld plugin:
Start kong on the Vagrant image
Now we are ready to start kong inside a vagrant ssh:
Output should be similar to:
If you later want to stop kong use
Register the Mockbin service and the HelloWorld plugin using the Kong API
We are ready to interact with kong using SoapUI at the host. Alternatively you may also use curl, see http://streamdata.io/blog/developing-an-helloworld-kong-plugin/, just note that the API registration command described there is no longer valid. At this page you can also find hints about unit testing kong plugins.
If we check the /apis/ path at the kong API port we see that no API is defined yet:
So we register the mockbin service at https://mockbin.com as managed API inside kong
We can check whether the API was successfully registered:
Apply the HelloWorld plugin to the Mockbin Service
No plugin is bound to the Mockbin API yet:
If we now call the Mockbin service via Kong we get
The returned header is unchanged yet.
We bind our helloworld plugin to https://mockbin.com:
The default configuration (say_hello = true) is used in this case since we didn't transfer a configuration setting.
Call the Mockbin service via Kong
If we now again call the Mockbin service via Kong we get
We see our "Hello-World" header property set by the plugin code.
Now let's reconfigure the plugin (say_hello = false)
The Mockbin service via Kong now delivers
We see "By World!!!" in the returned header.
Debugging the Kong plugin
To enable debugging the plugin we start the ZeroBrane debug server inside ZeroBrane Studio (Project/Start Debugger Server) and set a breakpont inside access.lua (select the line and type F9).
When we now again call the Mockbin service via Kong inside SoapUI execution of the plugin will be interrupted at the break point:
We can step through the code and investigate the call stack and the contents of the variables in ZeroBrane Studio.
Direct installation of Kong (without using Vagrant)
Installation of kong directly in windows is not possible, but on MacOS a brew based installation is supported. First install homebrew, see https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md#installation .
On "El Capitan" you should adjust the access rights:
Then follow https://github.com/Mashape/homebrew-kong :
We observed some openssl related build problems, the following commands did fix it: