Plugin Global Rules

Understand the concept of global rules in Apache APISIX, which allow plugins to be executed on every incoming request for consistent API behavior.

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 (opens in Plugin Hub docs) plugin globally for all incoming requests. Once a request is authenticated, the route uses the proxy-rewrite (opens in Plugin Hub docs) plugin to set an additional request header, which demonstrates the plugins execution order:

key-auth global rule diagram

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-key but to a non-existent route, the request is authenticated but APISIX returns an error stating 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 are executed sequentially, rather than overwriting each other.

Tasks that use this concept

Use Debug Mode

Related concepts