Plugin Development - Implementing Custom Logic

    A Kong Gateway (OSS) plugin allows you to inject custom logic (in Lua) at several entry-points in the life-cycle of a request/response or a tcp stream connection as it is proxied by Kong Gateway (OSS). To do so, the file must return a table with one or more functions with predetermined names. Those functions will be invoked by Kong Gateway (OSS) at different phases when it processes traffic.

    The first parameter they take is always self. All functions except init_worker can receive a second parameter which is a table with the plugin configuration.

    If you define any of the following functions in your handler.lua file you’ll implement custom logic at various entry-points of Kong Gateway (OSS)’s execution life-cycle:

    • HTTP Module is used for plugins written for HTTP/HTTPS requests

    To reduce unexpected behaviour changes, Kong Gateway (OSS) does not start if a plugin implements both response and either header_filter or body_filter.

    • is used for Plugins written for TCP and UDP stream connections

    All of those functions, except init_worker, take one parameter which is given by Kong Gateway (OSS) upon its invocation: the configuration of your plugin. This parameter is a Lua table, and contains values defined by your users, according to your plugin’s schema (described in the schema.lua module). More on plugins schemas in the next chapter.

    Note that UDP streams don’t have real connections. Kong Gateway (OSS) will consider all packets with the same origin and destination host and port as a single connection. After a configurable time without any packet, the connection is considered closed and the log function is executed.

    Kong Gateway (OSS) processes requests in phases. A plugin is a piece of code that gets activated by Kong Gateway (OSS) as each phase is executed while the request gets proxied.

    Phases are limited in what they can do. For example, the init_worker phase does not have access to the config parameter because that information isn’t available when kong is initializing each worker.

    Kong Gateway (OSS) can process HTTP and stream traffic. Some phases are executed only when processing HTTP traffic, others when processing stream, and some (like init_worker and log) are invoked by both kinds of traffic.

    In addition to functions, a plugin must define two fields:

    • VERSION is an informative field, not used by Kong Gateway (OSS) directly. It usually matches the version defined in a plugin’s Rockspec version, when it exists.
    • PRIORITY is used to sort plugins before executing each of their phases. Plugins with a higher priority are executed first. See the below for more info about this field.

    The following example handler.lua file defines custom functions for all the possible phases, in both http and stream traffic. It has no functionality besides writing a message to the log every time a phase is invoked. Note that a plugin doesn’t need to provide functions for all phases.

    1. local CustomHandler = {
    2.   VERSION  = "1.0.0"
    3.   PRIORITY = 10
    6. function CustomHandler:init_worker()
    7.   -- Implement logic for the init_worker phase here (http/stream)
    8.   kong.log("init_worker")
    9. end
    12. function CustomHandler:preread(config)
    13.   -- Implement logic for the preread phase here (stream)
    14.   kong.log("preread")
    15. end
    17. function CustomHandler:certificate(config)
    18.   -- Implement logic for the certificate phase here (http/stream)
    19.   kong.log("certificate")
    20. end
    22. function CustomHandler:rewrite(config)
    23.   -- Implement logic for the rewrite phase here (http)
    24.   kong.log("rewrite")
    25. end
    27. function CustomHandler:access(config)
    28.   -- Implement logic for the rewrite phase here (http)
    29.   kong.log("access")
    30. end
    32. function CustomHandler:header_filter(config)
    33.   -- Implement logic for the header_filter phase here (http)
    34.   kong.log("header_filter")
    35. end
    37. function CustomHandler:body_filter(config)
    38.   -- Implement logic for the body_filter phase here (http)
    39.   kong.log("body_filter")
    41. function CustomHandler:log(config)
    42.   -- Implement logic for the log phase here (http/stream)
    43.   kong.log("log")
    44. end
    46. -- return the created table, so that Kong can execute it
    47. return CustomHandler

    Note that in the example above we are using Lua’s : shorthand syntax for functions taking self as a first parameter. An equivalent unshortened version of the access function would be:

    The plugin’s logic doesn’t need to be all defined inside the handler.lua file. It can be be split into several Lua files (also called modules). The handler.lua module can use require to include other modules in your plugin.

    For example, the following plugin splits the functionality into three files. access.lua and body_filter.lua return functions. They are in the same folder as handler.lua, which requires and uses them to build the plugin:

    1. -- handler.lua
    2. local access = require "kong.plugins.my-custom-plugin.access"
    3. local body_filter = require "kong.plugins.my-custom-plugin.body_filter"
    5. local CustomHandler = {
    6.   VERSION  = "1.0.0",
    7.   PRIORITY = 10
    8. }
    10. CustomHandler.access = access
    11. CustomHandler.body_filter = body_filter
    13. return CustomHandler
    1. -- body_filter.lua
    2. return function(self, config)
    3.   kong.log("body_filter phase")

    See the source code of the Key-Auth Plugin for an example of a real-life handler code.

    Logic implemented in those phases will most likely have to interact with the request/response objects or core components (e.g. access the cache, and database). Kong Gateway (OSS) provides a (or “PDK”) for such purposes: a set of Lua functions and variables that can be used by Plugins to execute various gateway operations in a way that is guaranteed to be forward-compatible with future releases of Kong Gateway (OSS).

    When you are trying to implement some logic that needs to interact with Kong Gateway (OSS) (e.g. retrieving request headers, producing a response from a plugin, logging some error or debug information), you should consult the Plugin Development Kit Reference.

    Your plugin’s priority can be configured via a property accepting a number in the returned handler table:

    The higher the priority, the sooner your plugin’s phases will be executed in regard to other plugins’ phases (such as :access(), :log(), etc.).

    Open-source or Free mode

    Enterprise

    The following list includes all plugins bundled with open-source Kong Gateway or Kong Gateway running in Free mode.

    The current order of execution for the bundled plugins is:

    The following list includes all plugins bundled with a Kong Gateway Enterprise subscription.

    The current order of execution for the bundled plugins is: