Enable Custom Plugin

Users can extend the functionality of API7 Gateway by writing custom plugins, and injecting their own code into API7 Gateway's daily workflow. Examples are integrating additional protocols or systems, ultimately achieving centralized management at the gateway level.

This guide provides a step-by-step tutorial on enabling your custom plugin in API7 Gateway after development.

Prerequisites

1. Install API7 Enterprise.
2. Install jq:

yum install jq -y

3. Have your custom plugin .lua file ready. Here is an example echo-test plugin, which is modified from the echo plugin:

wget https://raw.githubusercontent.com/apache/apisix/master/apisix/plugins/echo.lua
cp echo.lua echo-test.lua

vim echo-test.lua

local plugin_name = "echo-test" <- modify this line with a new name

local _M = {
    version = 0.1,
    priority = 413,        <- modify this line with a new priority
    name = plugin_name,
    schema = schema,
    type = "other"         <- add this line with a string value
} 

Add the Custom Plugin to the Data Plane

Load the Custom Plugin File

mkdir -p /usr/local/apisix/custom_plugins/apisix/plugins
mv echo-test.lua /usr/local/apisix/custom_plugins/apisix/plugins

Verify that the custom plugin file is at the appropriate directory:

ls -al /usr/local/apisix/custom_plugins/apisix/plugins/echo-test.lua

Get response like this:

-rw-r--r--. 1 root root 3306 Jun 30 10:52 /usr/local/apisix/custom_plugins/apisix/plugins/echo-test.lua

Edit Plugin Configuration of the Data Plane

info

Ensure the configuration file has the appropriate privileges: rw- r-- r-- (644) for editing.

Add the custom plugin to the plugins section:

vim /usr/local/apisix/conf/config.yaml

...
  - datadog
  - echo
  - echo-test                      # priority: 413  <- add the custom plugin as a new line
...
  - http-logger
  - splunk-hec-logging

Add new line at the end of the apisix section:

vim /usr/local/apisix/conf/config.yaml

...
apisix:
  node_listen: 80
  enable_admin: false
  enable_ipv6: false
  ssl:
    listen_port: 443
  lua_module_hook: "apisix.enterprise.init"
  control:
    ip: 0.0.0.0 
    port: 9092                                                 <- make sure the port is 9092
  extra_lua_path: "/usr/local/apisix/custom_plugins/?.lua"     <- add the new line

Restart API7 Data Plane

For Docker installation:

docker restart api7-ee
  

For CentOS/Ubuntu installation:

systemctl reload apisix
  

Verify the Custom Plugin in Data Plane

curl 127.0.0.1:9092/v1/schema | jq |grep echo-test

Check the response to ensure it includes:

"echo-test": {

Enable Custom Plugin in the Control Plane

To ensure effective management, enable the Custom Plugin in the Control Plane to make it visible on the API7 Dashboard.

Replace JSON Schema

Manually replace the control plane's JSON schema data with the data plane's JSON schema.

info

The Control API is enabled in the default configuration file (config-default.yaml). Please double-check whether the configuration option for the Control API is enabled and if any modifications have been made in the configuration file (config.yaml). The default port for the Control API is 9092.

cd /usr/local/api7/dashboard/conf/
curl 127.0.0.1:9092/v1/schema > /usr/local/api7/dashboard/conf/schema.json

Edit Plugin Configuration of the Control Plane

info

Ensure the configuration file has the appropriate privileges: rw- r-- r-- (644) for editing.

Add the custom plugin to the plugins section:

vim /usr/local/api7/dashboard/conf/conf.yaml

...
  - datadog
  - echo
  - echo-test              <- add the custom plugin as a new line
...
  - http-logger
  - splunk-hec-logging
  

Restart API7 Control Plane

Restart API7 Dashboard to reload the JSON schema. For Docker installation:

docker restart api7-ee
  

For CentOS/Ubuntu installation:

systemctl restart api7-dashboard
  

Configure Plugin Management

Refer to the documentation on Enable Custom or Forbidden Plugin. In 7. Select the specific plugin., choose the customer plugin you added before.

Verify Custom Plugin

Refer to the documentation on Create Plugin Template to verify your custom plugin.