Set up a custom plugin project
Create a new repository for your plugin and add the following files in the repository:
kong/plugins/<plugin-name>/handler.lua
kong/plugins/<plugin-name>/schema.lua
Prerequisites
(Optional) Lua
While not required, an understanding of the Lua language is helpful for this series.
Initialize a new plugin repository
The first step in developing a custom plugin is to create the required files in the expected folder structure.
-
Open a terminal in the directory where you want to create your plugin project.
- Create a new folder for the plugin and navigate into it:
mkdir -p my-plugin && \ cd my-plugin
- Create the plugin folder structure:
mkdir -p kong/plugins/my-plugin && \ mkdir -p spec/my-plugin
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.
- Create empty
handler.lua
andschema.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
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 series, we’ll add configurable values to the table to configure the plugin.
Initialize the handler module
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 themajor.minor.revision
format.
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 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.