You are browsing unreleased documentation. See the latest documentation here.

Set Up a Plugin Project

The following instructions are written to help you quickly build, test, and run your first Kong Gateway custom plugin with Lua. The remaining pages in this section will provide details on other advanced topics related to plugin development and best practices.

Prerequisites

The following development tools are required to complete this guide:

• Docker (or Docker equivalent) is used to run Kong Gateway and test code
• curl is used to download web resources.
• git is used to install and update software on the host machine.

Step by step

In this chapter, you’ll start by creating a simple Kong Gateway custom plugin project. You’ll create the necessary folders and files and then author a short amount of Lua code to create a basic functioning plugin.

Initialize a new plugin repository

Start by opening a terminal and changing directories to a location where you store source code.

Create a new folder for the plugin and navigate into it:

mkdir -p my-plugin && \
  cd my-plugin

Next, create the plugin folder structure:

Important: The specific tree structure and filenames shown in this guide are important for ensuring the development and execution of your plugin works properly with Kong Gateway. Do not deviate from these names for this guide.

mkdir -p kong/plugins/my-plugin && \
  mkdir -p spec/my-plugin

Plugins are made up of Lua modules defined in individual files.

Start by creating empty handler.lua and schema.lua files, which are the minimum required modules for a functioning plugin:

touch kong/plugins/my-plugin/handler.lua
touch kong/plugins/my-plugin/schema.lua

You now have the base structure for a new plugin. Let’s look at how to author code for these modules.

Initialize the schema module

The schema.lua file defines your plugin’s configuration data model. The following is the minimum structure required for a valid plugin.

Add the following code to the schema.lua file:

 local PLUGIN_NAME = "my-plugin"

 local schema = {
   name = PLUGIN_NAME,
   fields = {
     { config = {
         type = "record",
         fields = {
         },
       },
     },
   },
 }
 
 return schema

This creates an empty base table for the plugin’s configuration. Later in this guide, you’ll add configurable values to the table for configuring the plugin at runtime.

Next, let’s add the handler code for the plugin.

Initialize the handler module

The handler.lua module contains the core logic of your new plugin. Start by putting the following Lua code into the handler.lua file:

 local MyPluginHandler = {
     PRIORITY = 1000,
     VERSION = "0.0.1",
 }

 return MyPluginHandler

This code defines a Lua table specifying a set of required fields for a valid plugin:

• The PRIORITY field sets the static execution order of the plugin, which determines when this plugin is executed relative to other loaded plugins.
• The VERSION field sets the version for this plugin and should follow the major.minor.revision format.

You now have a valid plugin - which currently does nothing.

Next, let’s add logic to the plugin and learn how to validate it.

Add handler logic

Plugin logic is defined to be executed at several key points in the lifecycle of HTTP requests, TCP streams, and Kong Gateway itself.

Inside the handler.lua module, you can add functions with well-known names to the plugin table, indicating the points at which the plugin logic should be executed.

In this example, you’ll add a response function, which is executed after a response has been received from an upstream service but before returning it to the client.

Let’s add a header to the response before returning it to the client. Add the following function implementation to the handler.lua file before the return MyPluginHandler statement:

function MyPluginHandler:response(conf)
    kong.response.set_header("X-MyPlugin", "response")
end

The kong.response module provided in the Kong PDK, provides functions for manipulating the response sent back to the client. The code above sets a new header on all responses with the name X-MyPlugin and value of response.

The full handler.lua file listing now looks like this:

local MyPluginHandler = {
  PRIORITY = 1000,
  VERSION = "0.0.1",
}

function MyPluginHandler:response(conf)
    kong.response.set_header("X-MyPlugin", "response")
end

return MyPluginHandler

Important: The Kong PDK provides a stable interface and set of functions for custom plugin development. It is important to avoid using modules from the Kong Gateway codebase that are not part of the PDK. These modules are not guaranteed to provide a stable interface or behavior and using them in your plugin code may lead to unexpected behavior.

What’s next?

At this stage, you now have a functional plugin for Kong Gateway. However, any development project is incomplete without testing. In the following chapter, you’ll learn how to install testing tools and create automated testing routines.