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 - File Structure

  • 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
  • Cluster
    • Retrieve cluster status
    • Add a node
    • Forcibly remove a node
  • 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
  • Basic plugin modules
  • Advanced plugin modules

Introduction

Note: This chapter assumes that you are familiar with Lua.

Consider your plugin as a set of Lua modules. Each file described in this chapter is to be considered as a separate module. Kong will detect and load your plugin’s modules if their names follow this convention:

"kong.plugins.<plugin_name>.<module_name>"

Your modules of course need to be accessible through your package.path variable, which can be tweaked to your needs by the lua-package-path directive in your Nginx configuration. However, the preferred way of installing plugins is through Luarocks. More on that later in this guide.

To make Kong aware that it has to look for your plugin’s modules, you’ll have to add it to the custom_plugins property in your configuration file, which is a comma-separated list. For example:

custom_plugins = my-custom-plugin # your plugin name here

Now, Kong will try to load the modules described in this chapter. Some of them are mandatory, but the ones that are not will be ignored and Kong will consider you do not make use of it. For example, Kong will load "kong.plugins.my-custom-plugin.handler" to retrieve and execute your plugin’s logic.

Now let’s describe what are the modules you can implement and what their purpose is.


Basic plugin modules

In its purest form, a plugin consists of two mandatory modules:

simple-plugin
├── handler.lua
└── schema.lua

Advanced plugin modules

Some plugins might have to integrate deeper with Kong: have their own table in the database, expose endpoints in the Admin API, etc… Each of those can be done by adding a new module to your plugin. Here is what the structure of a plugin would look like if it was implementing all of the optional modules:

complete-plugin
├── api.lua
├── daos.lua
├── handler.lua
├── hooks.lua
├── migrations
│   ├── cassandra.lua
│   └── postgres.lua
└── schema.lua

Here is the complete list of possible modules to implement and a brief description of what their purpose is. This guide will go in details to let you master each one of them.

Module name Required Description
api.lua No Defines a list of endpoints to be available in the Admin API to interact with entities custom entities handled by your plugin.
daos.lua No Defines a list of DAOs (Database Access Objects) that are abstractions of custom entities needed by your plugin and stored in the datastore.
handler.lua Yes An interface to implement. Each function is to be run by Kong at the desired moment in the lifecycle of a request.
migrations/*.lua No The corresponding migrations for a given datastore. Migrations are only necessary when your plugin has to store custom entities in the database and interact with them through one of the DAOs defined by daos.lua.
hooks.lua No Implements the invalidation event handlers for the datastore entities defined in daos.lua. Required if you are storing entities in the in-memory cache, in order to invalidate them when they are being updated/deleted on the datastore.
schema.lua Yes Holds the schema of your plugin’s configuration, so that the user can only enter valid configuration values.

Next: Write custom logic ›

  • 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