[| 小人物,大世界

我们渺小,但不卑贱;我们平凡,但不平庸。

Installation guide for Kong custom plugins

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

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 support@mashape.com for further troubleshooting.

阅读更多
个人分类: kong
想对作者说点什么? 我来说一句

NotePad<em>++ PlugIn</em>

2018年05月04日 0B 下载

sql server安装指南

2014年08月14日 1.67MB 下载

没有更多推荐了,返回首页

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭