==========================================

Installation guide for Kong custom plugins

---

Kong version 0.10.0

| Latest revision | 2017/03/24 |

Custom plugins for Kong consist of Lua source files that need to be in the file
system of each of your Kong nodes. This guide will provide you with
step-by-step instructions that will make a Kong node aware of your custom
plugin(s).

These steps should be applied to each node in your Kong cluster, so that the
custom plugin(s) are available on each one of them.

Prerequisite: Kong must be installed on the host.

1. Extract the custom plugin’s sources

You were provided with 2 archives containing the sources and documentation
for your plugin. The first one, the .rock file, is a LuaRocks package. The
second one is a regular .tar.gz archive which can be extracted with:

$ tar -xvf kong-plugin-<plugin-name>-<version>.tar.gz

Where is the name of the plugin, and its version
number.

The contents of this archive should be close to the following:

$ tree <plugin-name><plugin-name>├── INSTALL.txt├── README.md├── kong│   └── plugins│       └── <plugin-name>│           ├── handler.lua│           └── schema.lua└── kong-plugin-<plugin-name>-<version>.rockspec

• README.md is the documentation for this plugin: it covers topics such as
  its functionalities, configuration capabilities, usage examples, etc.
• INSTALL.txt is this file.
• kong/plugins/<plugin-name> is a directory containing the Lua sources
  for this plugin. It contains at least 2 files: handler.lua and
  schema.lua.
• kong-plugin-<plugin-name>-<version>.rockspec is a file describing the Lua sources
  in case you wish to install this plugin via LuaRocks, as described later.

2. Install the custom plugin’s sources

For a Kong node to be able to use the custom plugin, the custom plugin’s Lua
sources must be installed on your host’s file system. There are multiple ways
of doing so: via LuaRocks, or manually. Choose one, and jump to section 3.

If your plugin has dependencies (those should be listed in the plugin’s README
file), you should install it via one of the LuaRocks-provided methods. Make
sure LuaRocks can access the necessary online resources (luarocks.org,
github.com or others…). Eventually, consult the “LuaRocks through a proxy”
document at: https://github.com/luarocks/luarocks/wiki/LuaRocks-through-a-proxy

Reminder: regardless of which method you are using to install your plugin’s
sources, you must still do so for each node in your Kong cluster.

1. Via LuaRocks from the provided ‘rock’

   The .rock file is a self contained package that can be locally installed
   or from a remote server.

   If the luarocks utility is installed in your system (this is likely the
   case if you used one of the official installation packages), you can
   install the ‘rock’ in your LuaRocks tree (a directory in which LuaRocks
   installs Lua modules).

   It can be installed by doing:

   $ luarocks install <rock-filename>

   The filename can be a local name, or any of the supported methods, eg.
   http://myrepository.lan/rocks/myplugin-0.1.0-1.all.rock

   This command will also install your plugin’s dependencies if any.

2. Via LuaRocks from the source archive

   If the luarocks utility is installed in your system (this is likely the
   case if you used one of the official installation packages), you can
   install the Lua sources in your LuaRocks tree (a directory in which
   LuaRocks installs Lua modules).

   You can do so by changing the current directory to the extracted archive,
   where the rockspec file is:

   $ cd <plugin-name>

   And then run the following:

   $ luarocks make

   This will install the Lua sources in kong/plugins/<plugin-name> in your
   system’s LuaRocks tree, where all the Kong sources are already present.

   This command will also install your plugin’s dependencies if any.

3. Manually

   A more conservative way of installing your plugin’s sources is
   to avoid “polluting” the LuaRocks tree, and instead, point Kong
   to the directory containing them.

   This is done by tweaking the lua_package_path property of your Kong
   configuration. Under the hood, this property is an alias to the LUA_PATH
   variable of the Lua VM, if you are familiar with it.

   Those properties contain a semicolon-separated list of directories in
   which to search for Lua sources. It should be set like so in your Kong
   configuration file:

   lua_package_path = /<path-to-plugin-location>/?.lua;;

   Where:

   • /<path-to-plugin-location> is the path to the directory containing the
     extracted archive. It should be the location of the kong directory
     from the archive.
   • ? is a placeholder that will be replaced by
     kong.plugins.<plugin-name> when Kong will try to load your plugin. Do
     not change it.
   • ;; a placeholder for the “the default Lua path”. Do not change it.

   Example:

   The plugin something being located on the file system such that the
   handler file is:

   /usr/local/custom/kong/plugins/<something>/handler.lua

   The location of the kong directory is: /usr/local/custom, hence the
   proper path setup would be:

   lua_package_path = /usr/local/custom/?.lua;;

   Multiple plugins:

   If you wish to install two or more custom plugins this way, you can set
   the variable to something like:

   lua_package_path = /path/to/plugin1/?.lua;/path/to/plugin2/?.lua;;

   • ; is the separator between directories.
   • ;; still means “the default Lua path”.

   Note: you can also set this property via its environment variable
   equivalent: KONG_LUA_PACKAGE_PATH.

3. Instruct Kong to load your custom plugin

You must now add the custom plugin’s name to the custom_plugins list in your
Kong configuration (on each Kong node):

custom_plugins = <plugin-name>

If you are using two or more custom plugins, insert commas in between, like so:

custom_plugins = plugin1,plugin2

Note: you can also set this property via its environment variable equivalent:
KONG_CUSTOM_PLUGINS.

Reminder: don’t forget to update the custom_plugins directive for each node
in your Kong cluster.

4. Start Kong

You should now be able to start Kong without any issue. Consult your custom
plugin’s README.md file for instructions on how to enable/configure your plugin
on an API or Consumer object.

To make sure your plugin is being loaded by Kong, you can start Kong with a
debug log level:

log_level = debug

or:

KONG_LOG_LEVEL=debug

Then, you should see the following log for each plugin being loaded:

[debug] Loading plugin <plugin-name>

5. Removing a plugin

There are three steps to completely remove a plugin:

1. remove the plugin from your Kong api configuration. Make sure that it
   is no longer applied globally nor for any api or consumer. This has to be
   done only once for the entire Kong cluster, no restart/reload required.
   This step in itself will make that the plugin is no longer in use. But it
   remains available and it is still possible to re-apply the plugin.

2. remove the plugin from the custom_plugins directive (on each Kong node).
   Make sure to have completed step 1 before doing so. After this step
   it will be impossible for anyone to re-apply the plugin to any Kong
   api, consumer, or even globally. This step requires to restart/reload the
   Kong node to take effect.

3. to remove the plugin thoroughfully, delete the plugin-related files from
   each of the Kong nodes. Make sure to have completed step 2, including
   restarting/reloading Kong, before deleting the files. If you used LuaRocks
   to install the plugin, you can do luarocks remove <plugin-name> to remove
   it.

6. Troubleshooting

Kong can fail to start because of a misconfigured custom plugin for several
reasons:

• “plugin is in use but not enabled” -> you configured a custom plugin from
  another node, and that the plugin configuration is in the database, but the
  current node you are trying to start does not have it in its custom_plugins
  directive. To resolve, add the plugin’s name to the node’s custom_plugins
  directive.

• “plugin is enabled but not installed” -> the plugin’s name is present in the
  custom_plugins directive, but that Kong is unable to load the handler.lua
  source file from the file system. To resolve, make sure that the
  lua_package_path directive is properly set to load this plugin’s Lua sources.

• “no configuration schema found for plugin” -> the plugin is installed,
  enabled in custom_plugins, but Kong is unable to load the schema.lua
  source file from the file system.
  To resolve, make sure that the schema.lua file is present alongside the
  plugin’s handler.lua file.

Feel free to contact [e-mail] for further troubleshooting.