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:
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-keybut to a non-existent route, the request is authenticated but APISIX returns an error warning users that the route is not found. - with
global-keyto 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
- Key Concepts
- Plugin Hub
- Admin API - Plugin Global Rules