kong/kong-plugin

Simple template to get started with custom Kong plugins

Kong plugin template

This repository contains a very simple Kong plugin template to get you up and running quickly for developing your own plugins.

This template was designed to work with the kong-pongo and kong-vagrant development environments.

Please check out those repos README files for usage instructions. For a complete walkthrough check this blogpost on the Kong website.

Naming and versioning conventions

There are a number "named" components and related versions. These are the conventions:

• Kong plugin name: This is the name of the plugin as it is shown in the Kong Manager GUI, and the name used in the file system. A plugin named my-cool-plugin would have a handler.lua file at ./kong/plugins/my-cool-plugin/handler.lua.

• Kong plugin version: This is the version of the plugin code, expressed in x.y.z format (using Semantic Versioning is recommended). This version should be set in the handler.lua file as the VERSION property on the plugin table.

• LuaRocks package name: This is the name used in the LuaRocks eco system. By convention this is kong-plugin-[KongPluginName]. This name is used for the rockspec file, both in the filename as well as in the contents (LuaRocks requires that they match).

• LuaRocks package version: This is the version of the package, and by convention it should be identical to the Kong plugin version. As with the LuaRocks package name the version is used in the rockspec file, both in the filename as well as in the contents (LuaRocks requires that they match).

• LuaRocks rockspec revision: This is the revision of the rockspec, and it only changes if the rockspec is updated. So when the source code remains the same, but build instructions change for example. When there is a new LuaRocks package version the LuaRocks rockspec revision is reset to 1. As with the LuaRocks package name the revision is used in the rockspec file, both in the filename as well as in the contents (LuaRocks requires that they match).

• LuaRocks rockspec name: this is the filename of the rockspec. This is the file that contains the meta-data and build instructions for the LuaRocks package. The filename is [package name]-[package version]-[package revision].rockspec.

Example

• Kong plugin name: my-cool-plugin

• Kong plugin version: 1.4.2 (set in the VERSION field inside handler.lua)

This results in:

• LuaRocks package name: kong-plugin-my-cool-plugin

• LuaRocks package version: 1.4.2

• LuaRocks rockspec revision: 1

• rockspec file: kong-plugin-my-cool-plugin-1.4.2-1.rockspec

• File handler.lua is located at: ./kong/plugins/my-cool-plugin/handler.lua (and similar for the other plugin files)

kong-plugin's Issues

How do I write my entity_checks for array

Summary

I am developing my own rate-limiting plugins based on the official one.

The origin schema looks like:

fields = {
    { config = {
        type = "record",
        fields = {
          { second = { type = "number", gt = 0 }, },
          { minute = { type = "number", gt = 0 }, },
        }
...
      },
    },

My schema looks like:

    { config = {
        type = "record",
        fields = {
          { plans = {
            type = "array",
            elements = {
              type = "record",
              fields = {
                { second = { type = "number", gt = 0 }, },
                { minute = { type = "number", gt = 0 }, },
              }
            },
          },},
        },
        custom_validator = validate_periods_order,
      },
    },

You can see that the first field is called "plans" and it's type is an array which means I will have config.plans[0].second, config.plans[0].second, ... and the original one was config.second

Below is the origin entity_checks function of rate-limiting, I have no idea how to re-write it to match my schema since it changed from simple record type to array type

entity_checks = {
    { at_least_one_of = { "config.second", "config.minute", "config.hour", "config.day", "config.month", "config.year" } },
    { conditional = {
      if_field = "config.policy", if_match = { eq = "config.redis" },
      then_field = "config.redis_host", then_match = { required = true },
    } },
    { conditional = {
      if_field = "config.policy", if_match = { eq = "config.redis" },
      then_field = "config.redis_port", then_match = { required = true },
    } },
    { conditional = {
      if_field = "config.policy", if_match = { eq = "config.redis" },
      then_field = "config.redis_timeout", then_match = { required = true },
    } },
  },

How to add luamqtt luarocks module in handeler.lua? Actually spend whole day but still not succed.I want to use mqtt protocol with kong

local mqtt= require "resty.http"
local con = require "mqtt"

local plugin = {
PRIORITY = 1000, -- set the plugin priority, which determines plugin execution order
VERSION = "0.1", -- version in X.Y.Z format. Check hybrid-mode compatibility requirements.
}

function plugin:init_worker()
-- your custom code here
kong.log.debug("saying hi from the 'init_worker' handler")

end --]]

-- runs in the 'access_by_lua_block'
function plugin:access(plugin_conf)

-- your custom code here
kong.log.debug("llllllllllllllllllllllllllllllll*************************************************************************************************************************************************************")
kong.log.inspect(mqtt)
kong.log.debug("qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq")
kong.log.inspect(plugin_conf) -- check the logs for a pretty-printed config!
kong.service.request.set_header(plugin_conf.request_header, "this is on a request")

end

return plugin

specs fail in vagrant dev env

I followed the instructions in the kong/kong-vagrant repo but when I run the kong-plugin specs I get the following errors

vagrant@ubuntu-bionic:/kong$ bin/busted /kong-plugin/spec/

0 successes / 0 failures / 2 errors / 0 pending : 4.403546 seconds

Error → /kong-plugin/spec/myplugin/01-access_spec.lua @ 9
Demo-Plugin: myplugin (access) [#postgres] setup
/kong-plugin/spec/myplugin/01-access_spec.lua:15: [postgres] schema violation (name: plugin 'myplugin' not enabled; add it to the 'plugins' configuration property)

Error → /kong-plugin/spec/myplugin/01-access_spec.lua @ 9
Demo-Plugin: myplugin (access) [#cassandra] setup
/kong-plugin/spec/myplugin/01-access_spec.lua:15: [cassandra] schema violation (name: plugin 'myplugin' not enabled; add it to the 'plugins' configuration property)

Rename 'master' branch to 'main'

https://github.com/github/renaming

how to develop multiple plug-ins under a git directory

If I want to develop multiple plug-ins under a git directory and integrate them into the k8s environment, what should I do? Is there an example for reference

entity checks condition of one of multiple options

Hi I am adding JWKS support for the JWT plugin so that when the specified algorithm requires a rsa_public_key, I am adding an option to specify jwks_url. Could someone help defining the entity_checks condition for me? Below is the current code:

entity_checks = {
  { conditional = { if_field = "algorithm",
                    if_match = {
                      match_any = { patterns = { "^RS256$", "^RS384$", "^RS512$" }, },
                    },
                    then_field = "rsa_public_key",
                    then_match = {
                      required = true,
                      custom_validator = validate_ssl_key,
                    },
                  },
  },
},

Thanks.

Coveralls coverage is zero

Hello, thanks for creating this template it helps a lot to start plugin development.

In test GitHub job you provide section to evaluate tests coverage and post it to coveralls.io. After building plugin coverage calculated and posted, but coveralls shows it as 0%.

Steps to reproduce:

1. Generate repo from this template
2. Update .github/workflows/test.yml by removing Kong Enterprice versions
3. Create an account on coveralls.io and add your new repo
4. Kick off GitHub test action
5. Observe coverage in your repo on coveralls.io

Expected result:
step (4): Build successfull
step (5): Coverage greater than 0% shown

Actual result:
step (5): Coverage 0% shown

Going through my steps I've created repo https://github.com/seprokof/kong-plugin , added repo to coveralls.io https://coveralls.io/github/seprokof/kong-plugin and build is https://github.com/seprokof/kong-plugin/actions/runs/5438212946 . I've added little bit of debug info but outputting content of coverage files during the build.

I've checked source of pongo.sh from kong-pongo and saw that you just forward --coverage argument to busted and saw your notice that coverage only calculated for unit tests, but based on content of coverage files I expect to see something greater than zero on coveralls.io.

I detected the only suspicious thing - if you enable verbose output of luacov-coveralls by adding -v switch you will see source_files: 0.

Remove reference to mockbin.org

This comment references mockbin.org which is now disabled. It's unclear if the test uses mockbin.org, but the comment should remove it for plugin developers to avoid confusion. I could not raise a PR due to permissions on the repo.

kong-plugin/spec/myplugin/02-integration_spec.lua

Line 63 in ad362b7

-- now check the request (as echoed by mockbin) to have the header

Testing with strategy off doesn't work

Maybe I'm missing something with the setup, but if the strategy is off, calling make-yaml_file() with out any arguments tries to export the database

kong-plugin/spec/myplugin/02-integration_spec.lua

Line 36 in ad362b7

declarative_config = strategy == "off" and helpers.make_yaml_file() or nil,

and that always throws an error for me

'kong config db_export' only works with a database