Plugin

Description

This represents the configuration of the plugins that are executed during the HTTP request/response lifecycle. A Plugin configuration can be bound directly to a Route, a Service, a Consumer or a Plugin Config.

You can also refer to Admin API for how to use this resource.

Plugin - 图1note

While configuring the same plugin, only one copy of the configuration is valid. The order of precedence is always Consumer > Consumer Group > Route > Plugin Config > Service.

While configuring APISIX, you can declare the Plugins that are supported by the local APISIX node. This acts as a whitelisting mechanism as Plugins that are not in this whitelist will be automatically ignored. So, this feature can be used to temporarily turn off/turn on specific plugins.

Adding a Plugin

For adding new plugins based on existing plugins, copy the data in the plugins node from the default configuration file conf/config-default.yaml to your configuration file (conf/config.yaml).

In a request, a Plugin is only executed once. This is true even if it is bound to multiple different objects like Routes and Services. The order in which Plugins are run is determined by its configured priorities:

  1. local _M = {
  2.     version = 0.1,
  3.     priority = 0, -- the priority of this plugin will be 0
  4.     name = plugin_name,
  5.     schema = schema,
  6.     metadata_schema = metadata_schema,
  7. }

A Plugin configuration is submitted as part of the Route or Service and is placed under plugins. It internally uses the Plugin name as the hash key to holding the configuration items for the different Plugins.

  1. {
  2.     ...
  3.     "plugins": {
  4.         "limit-count": {
  5.             "count": 2,
  6.             "time_window": 60,
  7.             "rejected_code": 503,
  8.             "key": "remote_addr"
  9.         },
  10.         "prometheus": {}
  11.     }
  12. }

Not all Plugins have specific configuration items (for example, prometheus). In such cases, an empty object identifier can be used.

A warning level log as shown below indicates that the request was rejected by the Plugin.

  1. ip-restriction exits with http status code 403

Plugin common configuration

Some common configurations can be applied to plugins through the _meta configuration items, the specific configuration items are as follows:

NameTypeDescription
disablebooleanWhen set to true, the plugin is disabled.
error_responsestring/objectCustom error response.
priorityintegerCustom plugin priority.
filterarrayDepending on the requested parameters, it is decided at runtime whether the plugin should be executed. Something like this: {{var, operator, val}, {var, operator, val}, …}}. For example: {“arg_version”, “==”, “v2”}, indicating that the current request parameter version is v2. The variables here are consistent with NGINX internal variables. For details on supported operators, please see lua-resty-expr.

Disable the plugin

Through the disable configuration, you can add a new plugin with disabled status and the request will not go through the plugin.

  1. {
  2.     "proxy-rewrite": {
  3.         "_meta": {
  4.             "disable": true
  5.         }
  6.     }
  7. }

Custom error response

Through the error_response configuration, you can configure the error response of any plugin to a fixed value to avoid troubles caused by the built-in error response information of the plugin.

The configuration below means to customize the error response of the jwt-auth plugin to Missing credential in request.

  1. {
  2.     "jwt-auth": {
  3.         "_meta": {
  4.             "error_response": {
  5.                 "message": "Missing credential in request"
  6.             }
  7.         }
  8.     }
  9. }

Custom plugin priority

All plugins have default priorities, but through the priority configuration item you can customize the plugin priority and change the plugin execution order.

  1.  {
  2.     "serverless-post-function": {
  3.         "_meta": {
  4.             "priority": 10000
  5.         },
  6.         "phase": "rewrite",
  7.         "functions" : ["return function(conf, ctx)
  8.                     ngx.say(\"serverless-post-function\");
  9.                     end"]
  10.     },
  11.     "serverless-pre-function": {
  12.         "_meta": {
  13.             "priority": -2000
  14.         },
  15.         "phase": "rewrite",
  16.         "functions": ["return function(conf, ctx)
  17.                     ngx.say(\"serverless-pre-function\");
  18.                     end"]
  19.     }
  20. }

The default priority of serverless-pre-function is 10000, and the default priority of serverless-post-function is -2000. By default, the serverless-pre-function plugin will be executed first, and serverless-post-function plugin will be executed next.

The above configuration means setting the priority of the serverless-pre-function plugin to -2000 and the priority of the serverless-post-function plugin to 10000. The serverless-post-function plugin will be executed first, and serverless-pre-function plugin will be executed next.

Plugin - 图2note
  • Custom plugin priority only affects the current object(route, service …) of the plugin instance binding, not all instances of that plugin. For example, if the above plugin configuration belongs to Route A, the order of execution of the plugins serverless-post-function and serverless-post-function on Route B will not be affected and the default priority will be used.
  • Custom plugin priority does not apply to the rewrite phase of some plugins configured on the consumer. The rewrite phase of plugins configured on the route will be executed first, and then the rewrite phase of plugins (exclude auth plugins) from the consumer will be executed.

Dynamically control whether the plugin is executed

By default, all plugins specified in the route will be executed. But we can add a filter to the plugin through the filter configuration item, and control whether the plugin is executed through the execution result of the filter.

The configuration below means that the proxy-rewrite plugin will only be executed if the version value in the request query parameters is v2.

  1. {
  2.     "proxy-rewrite": {
  3.         "_meta": {
  4.             "filter": [
  5.                 ["arg_version", "==", "v2"]
  6.             ]
  7.         },
  8.         "uri": "/anything"
  9.     }
  10. }

Create a complete route with the below configuration:

  1. {
  2.     "uri": "/get",
  3.     "plugins": {
  4.         "proxy-rewrite": {
  5.             "_meta": {
  6.                 "filter": [
  7.                     ["arg_version", "==", "v2"]
  8.                 ]
  9.             },
  10.             "uri": "/anything"
  11.         }
  12.     },
  13.     "upstream": {
  14.         "type": "roundrobin",
  15.         "nodes": {
  16.             "httpbin.org:80": 1
  17.         }
  18.     }
  19. }

When the request does not have any parameters, the proxy-rewrite plugin will not be executed, the request will be proxy to the upstream /get:

  1. curl -v /dev/null http://127.0.0.1:9080/get -H"host:httpbin.org"
  1. < HTTP/1.1 200 OK
  2. ......
  3. < Server: APISIX/2.15.0
  4. <
  5. {
  6.   "args": {},
  7.   "headers": {
  8.     "Accept": "*/*",
  9.     "Host": "httpbin.org",
  10.     "User-Agent": "curl/7.79.1",
  11.     "X-Amzn-Trace-Id": "Root=1-62eb6eec-46c97e8a5d95141e621e07fe",
  12.     "X-Forwarded-Host": "httpbin.org"
  13.   },
  14.   "origin": "127.0.0.1, 117.152.66.200",
  15.   "url": "http://httpbin.org/get"
  16. }

When the parameter version=v2 is carried in the request, the proxy-rewrite plugin is executed, and the request will be proxy to the upstream /anything:

  1. curl -v /dev/null http://127.0.0.1:9080/get?version=v2 -H"host:httpbin.org"
  1. < HTTP/1.1 200 OK
  2. ......
  3. < Server: APISIX/2.15.0
  4. <
  5. {
  6.   "args": {
  7.     "version": "v2"
  8.   },
  9.   "data": "",
  10.   "files": {},
  11.   "form": {},
  12.   "headers": {
  13.     "Accept": "*/*",
  14.     "Host": "httpbin.org",
  15.     "User-Agent": "curl/7.79.1",
  16.     "X-Amzn-Trace-Id": "Root=1-62eb6f02-24a613b57b6587a076ef18b4",
  17.     "X-Forwarded-Host": "httpbin.org"
  18.   },
  19.   "json": null,
  20.   "method": "GET",
  21.   "origin": "127.0.0.1, 117.152.66.200",
  22.   "url": "http://httpbin.org/anything?version=v2"
  23. }

Hot reload

APISIX Plugins are hot-loaded. This means that there is no need to restart the service if you add, delete, modify plugins, or even if you update the plugin code. To hot-reload, you can send an HTTP request through the Admin API:

  1. curl http://127.0.0.1:9180/apisix/admin/plugins/reload -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT
Plugin - 图3note

If a configured Plugin is disabled, then its execution will be skipped.

Hot reload in stand-alone mode

For hot-reloading in stand-alone mode, see the plugin related section in stand alone mode.