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 key-auth plugin globally for all incoming requests. Once a request is authenticated, the route uses the proxy-rewrite plugin to set an additional request header, which demonstrates the 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 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 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.
Additional Resources
- Key Concepts
- Plugin Hub
- Admin API - Plugin Global Rules