Plugins

In this document, you will learn the basic concept of plugins in API7 Enterprise Edition 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.

Overview

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

API7 Enterprise Edition offers many existing plugins that can be customized and orchestrated 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, or consumers.

If existing API7 Enterprise Edition 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 Execution Lifecycle

The configuration of the plugin is then checked against the defined JSON Schema to make sure the plugins configuration schema is correct.

When a request goes through API7 Enterprise Edition, 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.

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

Plugins Execution Order

In general, plugins are executed in the following order:

1. Plugins in global rules

   1. plugins in rewrite phase
   2. plugins in access phase

2. Plugins bound to other objects

   1. plugins in rewrite phase
   2. plugins in access phase

Within each phase, you can optionally define a new priority value in the _meta.priority attribute of the plugin, which takes precedence over the default plugins priority during execution. Plugins with higher priority values are executed first. See plugin common configurations for an example.

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.

However, if the same plugin is configured locally on multiple objects, such as on routes, services, or consumers, only one copy of configuration is used as each non-global plugin is only executed once. This is because during execution, plugins configured in these objects are merged with respect to a specific order of precedence:

Consumer > Service Route > Service

such that if the same plugin has different configurations in different objects, the plugin configuration with the highest order of precedence during merging will be used.

Plugins Execution Filter

By default, all plugins are triggered by incoming requests that match the configured rules in routes. However, in some cases, you may want more granular control over plugins execution; that is, conditionally determine which plugins are triggered for requests.

API7 Enterprise Edition 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 API7 Enterprise Edition expressions.

Plugin Global Rules

In API7 Enterprise Edition, a global rule object is used to create plugins that are triggered on every incoming request and executed before other plugins locally bound to objects, such as routes, services, and consumers. Certain plugins, such as rate limiting and observability plugins, are frequently enabled globally in order to provide consistent and comprehensive protection for APIs.

The following diagram illustrates an example of enabling key authentication plugin globally for all incoming requests, where key-auth plugin is configured in both a global rule and a consumer. The proxy-rewrite plugin is configured on a route to modify the request's HTTP header, for demonstrating plugins execution order:

This configuration ensures that only the authenticated requests are allowed to interact with the upstream service. If a request is sent to API7 Enterprise Edition:

• without any key or with a wrong key, the request is rejected.
• with global-key but to a non-existent route, the request is authenticated but API7 Enterprise Edition returns an error warning users that the route is not found.
• with global-key to an existing route, the request is first authenticated, then the header of the request is modified by the plugin on the route, and finally the request is forwarded to the upstream service.

The example above used two different plugins in a global rule and a route. If the same plugin is configured in both objects, both instances of the plugin will be executed sequentially, rather than overwriting each other.

Plugin Metadata

In API7 Enterprise Edition, a plugin metadata object is used to configure the common metadata field(s) of all plugin instances sharing the same plugin name. It is useful when a plugin is enabled across multiple objects and requires a universal update to their metadata fields.

The following diagram illustrates the concept of plugin metadata using two instances of syslog plugins on two different routes, as well as a plugin metadata object setting a global log_format for the syslog plugin:

Without otherwise specified, the log_format on plugin metadata object should apply the same log format uniformly to both syslog plugins. However, since the syslog plugin on the /order route has a different log_format, requests visiting this route will generate logs in the log_format specified by the plugin in route.

In general, if a field of a plugin is defined in both the plugin metadata and another object, such as a route, the definition on the other object takes precedence over the global definition in plugin metadata to provide a more granular level of control.

Plugin metadata objects should only be used for plugins that have metadata fields. For more details on which plugins have metadata fields, please refer to the plugin reference guide (coming soon).