In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

  • Products
    Service Control Platform
    Platform Overview Kong Manager Kong Dev Portal Kong Vitals Kong Brain Kong Immunity
    Offerings
    Kong

    The blazingly fast open source microservices API gateway.

    Kong Enterprise

    The next-generation API platform built on top of Kong.

    Kong Cloud

    Kong Enterprise innovation delivered at cloud speed.

  • Solutions
    API Gateway

    Take control of your microservices traffic with the world's most popular API gateway.

    Kubernetes Ingress

    Own your Kubernetes cluster by extending Kong functionality as an ingress controller.

    Service Mesh

    Inject Kong as a sidecar for your services to go from mess to mesh.

  • Open Source
    Install

    Deploy Kong on your environment and platform of choice.


    Kubernetes Ingress

    Own your Kubernetes cluster by extending Kong functionality as an ingress controller.

    GitHub

    Find code or file an issue for Kong’s code/documentation.

    Kong Nation

    Get help from Kong engineers and community members.

    Community

    Join the Kong community to find help or contribute to Kong.


  • Hub
Kong
  • Docs
    Kong Docs + Getting Started

    Use the 5-minute quickstart and installation guide to deploy Kong now.

    Deploy Kong Enterprise

    Use the quickstart and reference materials to launch Kong Enterprise today.

    Master Kong Vitals

    Learn how to implement Vitals and optimize it for your deployment.

    Launch your Dev Portal

    Learn how to create and manage your Kong Dev Portal.

  • Resources
    Connect
    Community Kong Nation GitHub Kong Summit
    Get Support
    Enterprise Support Portal FAQs
    Learn
    Blog Ebooks Webinars Briefs
  • Company
    aboutAbout
    investorsInvestors
    careersCareers
    partnersPartners
    pressPress
    contactContact
  • Request Demo
Request Demo Installation
Products  
  Products
Service Control Platform
Platform Overview Kong Manager Kong Dev Portal Kong Vitals Kong Brain Kong Immunity
Offerings
Kong Kong Enterprise Kong Cloud
Solutions  
  Solutions
API Gateway Kubernetes Ingress Service Mesh
Open Source  
  Open Source
Install GitHub Kong Nation Community
Hub
Docs  
  Docs
Kong Kong Enterprise Kong Vitals Dev Portal
Resources  
  Resources
Connect
Community Kong Nation GitHub Kong Summit
Get Support
Enterprise Support Portal
Learn
Blog Ebooks Webinars Briefs
Company  
  Company
About Investors Careers Partners Press Contact
Edit this Page
Kong Kong Enterprise
Documentation

Plugin Development - Store Configuration

  • 1.0.x (latest)
  • 0.14.x
  • 0.13.x
  • 0.12.x
  • 0.11.x
  • 0.10.x
  • 0.9.x
  • 0.8.x
  • 0.7.x
  • 0.6.x
  • 0.5.x
  • 0.4.x
  • 0.3.x
  • 0.2.x
Getting Started
  • Introduction
  • Five-minute quickstart
  • Adding your API
  • Enabling Plugins
  • Adding Consumers
Guides & References
  • Configuration reference
  • CLI reference
  • Proxy reference
  • Authentication reference
  • Load balancing reference
  • Clustering reference
  • Network & Firewall
  • Public Lua API reference
  • Securing the Admin API
  • Plugin Development Guide
    • Introduction
    • File structure
    • Implement custom logic
    • Plugin configuration
    • Access the datastore
    • Store custom entities
    • Caching custom entities
    • Extending the Admin API
    • Writing tests
    • (un)Install your plugin
Admin API
  • Supported Content Types
  • Information routes
    • Retrieve node information
    • Retrieve node status
  • API Object routes
    • Add API
    • Retrieve API
    • List APIs
    • Update API
    • Update or create API
    • Delete API
  • Consumer Object routes
    • Create Consumer
    • Retrieve Consumer
    • List Consumers
    • Update Consumer
    • Update or create Consumer
    • Delete Consumer
  • Plugin Object routes
    • Add Plugin
    • Retrieve Plugin
    • List all Plugins
    • List Plugins per API
    • Update Plugin
    • Update or Add Plugin
    • Delete Plugin
    • Retrieve Enabled Plugins
    • Retrieve Plugin Schema
  • Certificate Object routes
    • Add Certificate
    • Retrieve Certificate
    • List Certificates
    • Update Certificate
    • Update or Create Certificate
    • Delete Certificate
  • SNI Object routes
    • Add SNI
    • Retrieve SNI
    • List SNIs
    • Update SNI
    • Update or Create SNI
    • Delete SNI
  • Upstream Object routes
    • Add Upstream
    • Retrieve Upstream
    • List all Upstreams
    • Update Upstream
    • Update or create Upstream
    • Delete Upstream
  • Target Object routes
    • Add Target
    • List Targets
    • List Active Targets
    • Delete Target
Maybe you were looking for the Enterprise Documentation instead?
Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Table of Contents

  • Introduction
  • Module
  • schema.lua specifications
  • Describing your configuration schema
    • Examples:

Introduction

Module

"kong.plugins.<plugin_name>.schema"

Most of the time, it makes sense for your plugin to be configurable to answer all of your user’s needs. Your plugin’s configuration is stored in the datastore for Kong to retrieve it and pass it to your handler.lua methods when the plugin is being executed.

The configuration consists of a Lua table in Kong that we call a schema. It contains key/value properties that the user will set when enabling the plugin through the Admin API. Kong provides you with a way of validating the user’s configuration for your plugin.

Your plugin’s configuration is being verified against your schema when a user issues a request to the Admin API to enable or update a plugin on a given API and/or Consumer.

For example, a user performs the following request:

$ curl -X POST http://kong:8001/apis/<api name>/plugins \
    -d "name=my-custom-plugin" \
    -d "config.foo=bar"

If all properties of the config object are valid according to your schema, then the API would return 201 Created and the plugin would be stored in the database along with its configuration ({foo = "bar"} in this case). If the configuration is not valid, the Admin API would return 400 Bad Request and the appropriate error messages.


schema.lua specifications

This module is to return a Lua table with properties that will define how your plugins can later be configured by users. Available properties are:

Property name Lua type Default Description
no_consumer Boolean false If true, it will not be possible to apply this plugin to a specific Consumer. This plugin must be API-wide only. For example: authentication plugins.
fields Table {} Your plugin’s schema. A key/value table of available properties and their rules.
self_check Function nil A function to implement if you want to perform any custom validation before accepting the plugin’s configuration.

The self_check function must be implemented as follows:

-- @param `schema` A table describing the schema (rules) of your plugin configuration.
-- @param `config` A key/value table of the current plugin's configuration.
-- @param `dao` An instance of the DAO (see DAO chapter).
-- @param `is_updating` A boolean indicating whether or not this check is performed in the context of an update.
-- @return `valid` A boolean indicating if the plugin's configuration is valid or not.
-- @return `error` A DAO error (see DAO chapter)

Here is an example of a potential schema.lua file:

return {
  no_consumer = true, -- this plugin will only be API-wide,
  fields = {
    -- Describe your plugin's configuration's schema here.
  },
  self_check = function(schema, plugin_t, dao, is_updating)
    -- perform any custom verification
    return true
  end
}

Describing your configuration schema

The fields property of your schema.lua file described the schema of your plugin’s configuration. It is a flexible key/value table where each key will be a valid configuration property for your plugin, and each value a table describing the rules for that property. For example:

  fields = {
    some_string = {type = "string", required = true},
    some_boolean = {type = "boolean", default = false},
    some_array = {type = "array", enum = {"GET", "POST", "PUT", "DELETE"}}
  }

Here is the list of accepted rules for a property:

Rule Lua type(s) Accepted values Description
type string “id”, “number”, “boolean”, “string”, “table”, “array”, “url”, “timestamp” Validates the type of a property.
required boolean   Default: false. If true, the property must be present in the configuration.
unique boolean   Default: false. If true, the value must be unique (see remark below).
default any   If the property is not specified in the configuration, will set the property to the given value.
immutable boolean   Default: false. If true, the property will not be allowed to be updated once the plugin configuration has been created.
enum table Integer indexed table A list of accepted values for a property. Any value not included in this list will not be accepted.
regex string A valid PCRE regular expression A regex against which to validate the property’s value.
schema table A nested schema definition If the property’s type is table, defines a schema against which to validate those sub-properties.
func function   A function to perform any custom validation on a property. See later examples for its parameters and return values.
  • type: will cast the value retrieved from the request parameters. If the type is not one of the native Lua types, custom verification is performed against it:
    • id: must be a string
    • timestamp: must be a number
    • url: must be a valid URL
    • array: must be an integer-indexed table (equivalent of arrays in Lua). In the Admin API, such an array can either be sent by having several times the property’s key with different values in the request’s body, or comma-delimited through a single body parameter. If using the non-comma-delimited form, note that a maximum of only 100 query parameters can be sent to the admin api at a time.
  • unique: This property does not make sense for a plugin configuration, but is used when a plugin needs to store custom entities in the datastore.
  • schema: if you need to perform deepened validation of nested properties, this field allows you to create a nested schema. Schema verification is recursive. Any level of nesting is valid, but bear in mind that this will affect the usability of your plugin.
  • Any property attached to a configuration object but not present in your schema will also invalidate the said configuration.

Examples:

This schema.lua file for the key-auth plugin defines a default list of accepted parameter names for an API key, and a boolean whose default is set to false:

-- schema.lua
return {
  no_consumer = true,
  fields = {
    key_names = {type = "array", required = true, default = {"apikey"}},
    hide_credentials = {type = "boolean", default = false}
  }
}

Hence, when implementing the access() function of your plugin in handler.lua and given that the user enabled the plugin with the default values, you’d have access to:

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  print(config.key_names) -- {"apikey"}
  print(config.hide_credentials) -- false
end

return CustomHandler

A more complex example, which could be used for an eventual logging plugin:

-- schema.lua

local function server_port(given_value, given_config)
  -- Custom validation
  if given_value > 65534 then
    return false, "port value too high"
  end

  -- If environment is "development", 8080 will be the default port
  if given_config.environment == "development" then
    return true, nil, {port = 8080}
  end
end

return {
  fields = {
    environment = {type = "string", required = true, enum = {"production", "development"}}
    server = {
      type = "table",
      schema = {
        fields = {
          host = {type = "url", default = "http://example.com"},
          port = {type = "number", func = server_port, default = 80}
        }
      }
    }
  }
}

Such a configuration will allow a user to post the configuration to your plugin as follows:

$ curl -X POST http://kong:8001/apis/<api name>/plugins \
    -d "name=<my-custom-plugin>" \
    -d "config.environment=development" \
    -d "config.server.host=http://localhost"

And the following will be available in handler.lua:

-- handler.lua
local BasePlugin = require "kong.plugins.base_plugin"
local CustomHandler = BasePlugin:extend()

function CustomHandler:new()
  CustomHandler.super.new(self, "my-custom-plugin")
end

function CustomHandler:access(config)
  CustomHandler.super.access(self)

  print(config.environment) -- "development"
  print(config.server.host) -- "http://localhost"
  print(config.server.port) -- 8080
end

return CustomHandler

Next: Store custom entities ›

  • Kong
    Star
  • Products
    • Kong
    • Kong Enterprise
    • Kong Cloud
    • Subscriptions
  • Resources
    • Enterprise Support
    • Documentation
    • Partners
    • Webinars
    • Ebooks
  • Company
    • About
    • Investors
    • News
    • Careers Hiring!
    • Kong Summit
    • Contact
  • Open Source
    • Install
    • GitHub
    • Kong Nation
    • Community
  • © Kong Inc. 2019   Terms•Privacy