APISIX Plugin Template

This template can be used to create custom Lua plugins for Apache APISIX.
Extended from api7/apisix-plugin-template.

Table of Contents

• APISIX Plugin Template
  • Table of Contents
  • Template Usage
  • Plugin Template Structure
  • Plugin Usage
    • Installation
  • Testing
    • Local Docker
    • CI
  • Examples
  • Learn More

Template Usage

You can use this template by clicking the "Use this template" button on the top.

You can then clone the newly generated repository to your local machine and write your custom code.

Back to TOC

Plugin Template Structure

The template contains the following files:

.
├── .github/         GitHub Actions workflows and Dependabot configuration files
├── apisix           All files in this folder will be copied and will overwrite the original APISIX files
│   └── plugins/     Your custom plugin goes here
├── ci               All files in this folder will be copied and will overwrite the original APISIX
│   └── utils/       CI utils script folder
├── examples/        APISIX examples
├── t/               Test cases
├── LICENSE
├── Makefile
└── README.md

Back to TOC

Plugin Usage

Installation

To install custom plugins in APISIX there are 2 methods:

• placing them alongside other built-in plugins, in ${APISIX_INSTALL_DIRECTORY}/apisix/plugins/ (by default /usr/local/apisix/apisix/plugins/);
• placing them in a custom directory and setting apisix.extra_lua_path to point that directory, in config.yaml.

Back to TOC

Testing

To test your custom plugin, you can:

• enable it on a route or a global rule and try sending a request;
• write tests for it and run these tests in a Docker container locally or in the CI.

Local Docker

TODO

CI

The ci.yml workflow runs the tests cases in the t/ folder and can be triggered by a workflow_dispatch event, from GitHub: Actions | CI.

Back to TOC

Examples

Folder examples/ contains a simple example that shows how to setup APISIX locally on Docker, and load the plugin(s).

For more examples, have a look at github.com/mikyll/apisix-examples.

Back to TOC

Learn More

• APISIX Source Code
• APISIX Deployment Modes
• Developing custom APISIX plugins
• APISIX testing framework
• APISIX debug mode
• NGiNX variables
• APISIX Examples