Skip to main content
Version: 3.20.0

Plugin Global Rules

In this document, you will learn the basic concept of plugin global rules in APISIX and why you may need them.

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

Overview​

In APISIX, a global rule object configures plugins for incoming requests independently of plugins bound to routes, services, consumers, consumer groups, or plugin configs. Rate-limiting and observability plugins are often enabled globally to apply consistent behavior across APIs.

Global plugins run before local plugins within the same phase. The complete order is global rewrite, local rewrite, global access, then local access. A global access handler therefore does not run before a local rewrite handler. Priorities order plugins within each phase and scope, and an early response prevents later handlers from running. See Plugins Execution Order for details.

The following diagram illustrates an example of enabling the key-auth plugin globally for all incoming requests and configuring the proxy-rewrite plugin on a route. Both plugins run in the rewrite phase, so the global key-auth instance runs before the route-level proxy-rewrite instance:

key-auth global rule diagram

This configuration ensures that only authenticated requests are allowed to interact with the upstream service. If authentication fails, APISIX rejects the request before running the route-level rewrite or proxying the request upstream. If a request is sent to APISIX:

  • 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 APISIX returns an error warning users that the route is not found.
  • with global-key to an existing route, the global authentication plugin validates the credential, the route plugin modifies the request header, and APISIX then forwards the request 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.

Additional Resources​