Skip to main content

Where a plugin runs

A plugin lives on the object you add it to, in that object's Plugins tab. The object decides which requests the plugin acts on. Six kinds of object carry plugins.

Added toActs on
A routeEvery request the route takes.
A serviceThe requests of every route on the service.
A plugin configThe requests of every route that names it.
A global ruleEvery request of the environment, whatever the route, and requests that no route takes.
A consumerThe requests of that consumer, once a plugin on the route has named it.
A consumer groupThe requests of every consumer in the group, once named.

Which copy wins​

The same plugin can sit on several of these at once. For one request, one copy runs.

  • The route beats its service and its plugin config. Where the route carries a plugin its service also carries, the route's copy is used on that route, whole, with its own settings. The service's other plugins still run. The same holds for a plugin config.
  • The consumer beats the route, and the group beats the route. Where a route carries limit-count and the consumer carries it too, the consumer's copy counts and the route's does not. A consumer without a copy of its own is counted by its group's copy, and only a consumer with neither by the route's. On a route whose own limit is 100, a member of a group with 1000 is counted by the group's, and a member with 5000 of its own by that.
  • A global rule's copy runs beside the route's. Neither replaces the other. A global limit-count and a route's limit-count both count each request; the route's answers show the route's numbers, and the request is still taken from the client's global count.
  • A plugin that rewrites the request is the exception. Where the route carries proxy-rewrite, only the route's copy rewrites the request, whatever the consumer or its group carries.

The route's Plugins tab shows the result for that route under Request path: the global rules first, then the route's own list, with the plugins the route takes from its service or plugin config in the Also applied card. In that card, a plugin the route also carries itself is marked overridden by this route, because the route's own copy runs instead.

In what order​

The gateway chooses the route first, by the route's matching rules, before any plugin runs. Then it works through the request in phases, stages of its work that follow each other, the rewrite phase before the access phase for example. Within one phase plugins run by their priority, higher first, and a plugin of an earlier phase runs before them all. Each reference page states the plugin's priority.

Two things follow from this that are easy to miss.

  • A plugin cannot change which route a request takes. real-ip takes the client's own address from a header the load balancer writes, so that later plugins see the client rather than the load balancer. A route's Client addresses field lists the addresses the route takes requests from. real-ip on a global rule gives every plugin the client's own address, but that field was already matched on the load balancer's address. See each client's own address sets this up.
  • A global rule's plugins run before the route's plugins of the same phase. key-auth on a global rule reads the key before a route's own key-auth does. With Hide credentials on, the global copy takes the key away, and a route that keeps key-auth of its own answers 401 even to a valid key.

Choosing where to put a plugin​

  • Only this route needs it: on the route.
  • Every route of one backend needs it, and they share the backend's nodes: on the service.
  • Several routes need the same plugins while each keeps its own target: on a plugin config.
  • Every request of the environment needs it: on a global rule. A plugin that refuses requests then refuses them everywhere, routes meant to stay open included.
  • One client needs it wherever it calls: on the consumer. Several clients alike: on a consumer group.
G8 dev