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 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, consumers, consumer groups, or plugin configs. 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 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 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 Resource(s)

• Key Concepts
  • Plugins
  • Consumers
• Plugin Hub
• Admin API - Plugin Configs