File Structure

    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 lua_package_path configuration property. However, the preferred way of installing plugins is through , 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:

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

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

    Some of these modules are mandatory (e.g. handler.lua), and some are optional, and will allow the plugin to implement some extra-functionalities (e.g. 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.

    • 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:

    2. ├── api.lua
    3. ├── daos.lua
    5. │   ├── init.lua
    6. │   └── 000_base_complete_plugin.lua
    7. └── schema.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.

    The Key-Auth plugin is an example of plugin with this file structure. See the for more details.

    Next Implementing Custom Logic