Skip to main content
API7.ai Logo

Plugins

In this document, you will learn the basic concept of plugins in APISIX and why you need plugins. You will be introduced to a few relevant concepts, including plugins enablement, plugins configuration files precedence, plugins execution filter and order, as well as plugins development.

Explore additional resources at the end of the document for more information on related topics.

Overview​

APISIX plugins extend APISIX's functionalities to meet organization or user-specific requirements in traffic management, observability, security, request/response transformation, serverless computing, and more.

APISIX offers many existing plugins that can be customized and combined to suit your needs. These plugins can be globally enabled to be triggered on every incoming request, or locally bound to other objects, such as routes, services, consumers, consumer groups, or plugin configs. See plugin hub for an inventory of plugins and their usage.

If existing APISIX plugins do not meet your needs, you can also write your own plugins in Lua or other languages such as Java, Python, Go, and Wasm.

Plugins Installation​

By default, most APISIX plugins are installed:

apisix/cli/config.lua
local _M = {
  ...
  plugins = {
    "real-ip",
    "ai",
    "client-control",
    "proxy-control",
    "request-id",
    "zipkin",
    "ext-plugin-pre-req",
    "fault-injection",
    "mocking",
    "serverless-pre-function",
    ...
  },
  ...
}

If you would like to make adjustments to plugins installation, add the customized plugins configuration to config.yaml. For example:

plugins:
  - real-ip
  - ai
  - client-control
  - proxy-control
  - request-id
  - zipkin     
  - ext-plugin-pre-req
  - fault-injection
  # - mocking                 # do not install
  - serverless-pre-function
  ...                         # other plugins

See config.yaml.example(https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for a complete configuration reference.

Reload APISIX for changes to take effect.

Plugins Execution Lifecycle​

An installed plugin is first initialized. The configuration of the plugin is then checked against the defined JSON Schema to make sure the plugin configuration schema is correct.

When a request goes through APISIX, the plugin's corresponding methods are executed in one or more of the following phases: rewrite, access, before_proxy, header_filter, body_filter, and log. These phases are largely influenced by the OpenResty directives.


Routes Diagram

To learn more about phases for your custom plugins development, see the plugin development how-to guide.

Plugins Execution Order​

For a matched HTTP route, global and local plugins are interleaved by phase:

  1. global-rule plugins in the rewrite phase;
  2. locally bound plugins in the rewrite phase;
  3. global-rule plugins in the access phase; and
  4. locally bound plugins in the access phase.

A global plugin therefore runs before a local plugin in the same phase, but a local rewrite handler runs before every global access handler. Do not assume that every global plugin completes before all route or service plugins.

Within each global or local phase group, you can define a priority in _meta.priority, which takes precedence over the plugin's default priority. Plugins with higher priorities run first in that group. A priority does not move a plugin across phase or global/local boundaries. See plugin common configurations for an example.

If a plugin terminates the request in a phase, later handlers that would otherwise run are skipped. This includes lower-priority plugins in the same group and groups scheduled later in the request lifecycle.

Plugins Merging Precedence​

When the same plugin is configured both globally in a global rule and locally in an object (e.g. a route), both plugin instances are executed sequentially.

If the same plugin is configured locally on multiple objects, APISIX merges those configurations and executes one local plugin instance. The merge follows this precedence:

Consumer > Consumer Group > Route > Plugin Config > Service

If the objects contain different configurations for the same plugin, APISIX uses the configuration with the highest precedence.

Plugins Execution Filter​

By default, all plugins are triggered by incoming requests that match the configured route. You can use an execution filter when a plugin should run only for requests that meet additional conditions.

APISIX allows for dynamic control over plugin execution by applying the _meta.filter configuration to the plugins. The configuration supports the evaluation of a wide range of built-in variables and APISIX expressions.

See plugin common configurations for an example.

Plugins Development​

APISIX supports plugin extension in multiple languages, including Lua, Java, Python, Go, and Wasm. Plugins run in three major ways:

  • Lua plugins run natively in APISIX.
  • Java, Python, and Go plugins run in their corresponding APISIX plugin runners, communicating over remote procedure calls (RPCs).
  • Wasm plugins run in the APISIX Wasm plugin runtime.

To learn more about developing plugins, see create plugin in Lua.

Additional Resources​