You are browsing documentation for an outdated version.
See the latest documentation here.
Plugin Development - File Structure
Note: This chapter assumes that you are familiar with
Consider your plugin as a set of Lua
modules. Each file described in
this chapter is to be considered as a separate module. Kong will detect and
load your plugin’s modules if their names follow this convention:
Your modules need to be accessible through your
variable, which can be tweaked to your needs via the
However, the preferred way of installing plugins is through
LuaRocks, which Kong natively integrates with.
More on LuaRocks-installed plugins later in this guide.
To make Kong 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 # your plugin name here
Or, if you don’t want to load any of the bundled plugins:
plugins = my-custom-plugin # your plugin name here
Now, Kong will try to load several Lua modules from the following namespace:
Some of these modules are mandatory (e.g.
handler.lua), and some are
optional, and will allow the plugin to implement some extra-functionalities
api.lua to extend the Admin API endpoints).
Now let’s describe exactly what are the modules you can implement and what
their purpose is.
Basic plugin modules
In its purest form, a plugin consists of two mandatory modules:
handler.lua: the core of your plugin. It is an interface to implement, in
which each function will be run at the desired moment in the lifecycle of a
request / connection.
schema.lua: your plugin probably has to retain some configuration entered
by the user. This module holds the schema of that configuration and defines
rules on it, so that the user can only enter valid configuration values.
Advanced plugin modules
Some plugins might have to integrate deeper with Kong: have their own table in
the database, expose endpoints in the Admin API, etc. Each of those can be
done by adding a new module to your plugin. Here is what the structure of a
plugin would look like if it was implementing all of the optional modules:
│ ├── init.lua
│ └── 000_base_complete_plugin.lua
Here is the complete list of possible modules to implement and a brief
description of what their purpose is. This guide will go in details to let you
master each one of them.
||Defines a list of endpoints to be available in the Admin API to interact with the custom entities handled by your plugin.
||Defines a list of DAOs (Database Access Objects) that are abstractions of custom entities needed by your plugin and stored in the datastore.
||An interface to implement. Each function is to be run by Kong at the desired moment in the lifecycle of a request / connection.
||The database migrations (e.g. creation of tables). Migrations are only necessary when your plugin has to store custom entities in the database and interact with them through one of the DAOs defined by daos.lua.
||Holds the schema of your plugin’s configuration, so that the user can only enter valid configuration values.
The Key-Auth plugin is an example of plugin with this file structure.
See its source code for more details.