Custom plugin reference

Kong allows you to develop and deploy custom plugins.

Before building custom plugins, it’s’ important to understand how Kong Gateway is built, how it integrates with Nginx, and how the high performance Lua language is used.

Lua development is enabled in Nginx with the lua-nginx-module. Instead of compiling Nginx with this module, Kong Gateway is distributed along with OpenResty, which includes the lua-nginx-module. OpenResty is not a fork of Nginx, but a bundle of modules extending its capabilities.

Kong Gateway is a Lua application designed to load and execute Lua modules, commonly referred to as plugins. Kong Gateway provides a broad plugin development environment including an SDK, database abstractions, migrations, and more.

Plugins consist of Lua modules interacting with request/response objects or network streams to implement arbitrary logic. Kong Gateway provides a Plugin Development Kit (PDK) which is a set of Lua functions that are used
to facilitate interactions between plugins, the Kong Gateway core, and other components.

Consider your plugin as a set of Lua modules. Each file described in this section is a separate module. Kong Gateway will detect and load your plugin’s modules if their names follow this convention:

kong.plugins.<plugin_name>.<module_name>

Your modules need to be accessible through your package.path variable, which can be customized to your needs via the lua_package_path configuration property. However, the preferred way of installing plugins is through LuaRocks, which Kong Gateway natively integrates with.

To make Kong Gateway aware that it has to look for your plugin’s modules, you’ll have to add it to the plugins property in your configuration file, which is a comma-separated list. For example:

plugins = bundled,my-custom-plugin

Or, if you don’t want to load any of the bundled plugins:

plugins = my-custom-plugin

Now, Kong Gateway will try to load several Lua modules from the following namespace:

kong.plugins.my-custom-plugin.<module_name>

Basic plugin modules

In its simplest form, a plugin consists of two mandatory modules:

• handler.lua: This module is the core of your plugin. It’s an interface to implement, in which each function will be run at the desired moment in the lifecycle of a request/connection.
• schema.lua: This module holds the schema of the plugin configuration to be entered by the user, and defines rules on it, so that the user can only enter valid configuration values.

Some plugins, such as the File Log plugin, use only these two modules. However, you can use advanced modules to implement extra functionalities.

To learn how to create a simple plugin with the basic modules, see the getting started guide.

Advanced plugin modules

Some plugins might have to integrate deeper with Kong Gateway: have their own table in the database, expose endpoints in the Admin API, etc. This can be done by adding new modules to your plugin. Below is the structure of a plugin with all optional modules implemented:

complete-plugin
├── api.lua
├── daos.lua
├── handler.lua
├── migrations
│   ├── init.lua
│   └── 000_base_complete_plugin.lua
└── schema.lua

The complete list of modules you can implement is as follows:

The Key Authentication plugin is an example of a plugin with these modules. See the plugin source code for more details.