Set up a custom plugin project

The first step in developing a custom plugin is to create the required files in the expected folder structure.

1. Open a terminal in the directory where you want to create your plugin project.

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

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

   Copied!
3. Create the plugin folder structure:

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

   Copied!

   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. Don’t deviate from these names for this guide.

4. Create empty handler.lua and schema.lua files, which are the minimum required Lua modules for a functioning plugin:

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

   Copied!

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 series, we’ll add configurable values to the table to configure the plugin.

The handler.lua module contains the core logic of your new plugin.

Add 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.

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 to the plugin table, indicating the points at which the plugin logic should be executed.

In this example, we’ll add a response function, which is executed after a response has been received from the 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 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’s 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.