Apache APISIX global rules, plugin configs and plugin precedence

Global rules set gateway-wide policy, plugin configs group reusable plugins, and precedence decides which settings win. This page explains how to structure them so the gateway stays manageable as routes multiply.

On this page

Global rules and plugin precedence in Apache APISIX: when your gateway needs them

Global rules, plugin configs and plugin precedence are how Apache APISIX keeps plugin configuration manageable once a gateway grows beyond a handful of routes. The common failure looks like this: the same rate limit, authentication and logging plugins are copied into many routes, and a change made in one place never reaches the others. A global rule holds a plugin configuration that applies gateway-wide, a plugin config is a reusable plugin set that routes can reference, and a consumer carries the identity of each API caller. You create and update these objects through the Admin API, which manages global rules, plugin configs, consumers and routes as separate resources. Keeping each policy in one object is what lets you answer which setting applies to a request.

Precedence decides which configuration wins when the same plugin is defined at more than one level. According to the APISIX consumer documentation, the order is Consumer, then Route, then Plugin Config, then Service, so a consumer-level setting is evaluated ahead of a route-level one, and a service-level setting has the lowest priority. Before you rely on that order, confirm in the documentation how global rules fit alongside these four levels and how plugin fields merge when they differ between levels, because the order alone does not tell you the resulting values. Consumer identity also depends on authentication: plugins such as key-auth, jwt-auth, hmac-auth and basic-auth identify the consumer, so consumer-level plugins only take effect for requests that pass that authentication step.

Two recent releases change how you should audit existing configuration. APISIX 3.15.0 disallows creating duplicate plugins in global rules, so a configuration that stacks the same plugin twice will need correcting before you upgrade or re-apply it. APISIX 3.14.0 stopped the Admin API from populating default values when writing resources, which means a resource read back may no longer show the defaults you assumed were stored. Export your global rules, plugin configs and routes, compare them with what the gateway actually holds, and check each duplicate. Confirm the exact behavior for your target version in the APISIX changelog before scheduling the change.

Which configuration object fits which policy

APISIX spreads policy across four objects: global rules, plugin configs, consumers, and the services and routes that handle traffic. Each one answers a different question about where a policy should live, and mixing them up is the most common cause of plugin sprawl.

Global rules for gateway-wide policy

A global rule applies a plugin to every request the gateway handles, regardless of route. It suits policy that must hold everywhere, such as a common logging or security header plugin. The Admin API lists global rules as a managed resource, so they can be reviewed and versioned like other configuration. Before adding one, check which routes it will touch, because a global rule runs for all of them and is easy to forget during troubleshooting.

Plugin configs for reusable plugin sets

A plugin config is a named, reusable set of plugins that several routes can reference. Use it when a group of routes needs the same rate limit, authentication, or transformation without copying the settings into each route. Changing the plugin config then updates every route that uses it. Confirm which routes reference each config before editing it, since a change affects all of them at once.

Consumers for identifying API callers

A consumer represents an API caller, identified by a username. Authentication plugins such as key-auth, jwt-auth, basic-auth, hmac-auth, ldap-auth and wolf-rbac identify the consumer on each request, which lets policies target a specific client. Consumer-bound settings take precedence over route settings, so a consumer-level rate limit can differ from the limit on the route it calls. Decide early how consumer names map to your client applications and owners.

Services and routes as attachment points

Routes match incoming requests and send them to an upstream, while services group shared settings such as upstreams and plugins for several routes. Policy attaches here when it describes one API or one endpoint. Attaching a plugin directly to a route is the clearest option for a single endpoint, but repeating it across many routes is a signal that a plugin config or global rule is the better home. Review route-level plugins whenever a shared policy changes.

Checking the object before you add a plugin

Before adding a plugin, ask four questions: does it apply everywhere, to a group of routes, to one caller, or to one endpoint? The answer selects the object. Record that decision in your configuration-as-code repository so reviewers can see why a plugin sits where it does. This check is what prevents the same policy from appearing in global rules, plugin configs and routes at once, which the 3.15.0 duplicate-plugin check now rejects in global rules.

How APISIX resolves which plugin settings apply

When a request carries credentials that an authentication plugin maps to a consumer, APISIX identifies the caller by username and applies that consumer's settings first. The consumer documentation lists basic-auth, hmac-auth, jwt-auth, key-auth, ldap-auth and wolf-rbac as plugins that identify the consumer, and the order for this case is Consumer, then Route, then Plugin Config, then Service.

  • Consumer settings come first: a plugin configured on the consumer takes precedence over the same plugin on the route, plugin config or service.
  • The authentication plugin must run on the route: key-auth, jwt-auth or hmac-auth has to be enabled on the matched route for the consumer to be identified at all.
  • Per-caller limits follow the consumer: a rate limit set on one consumer applies to that caller only (illustrative: two API keys on the same route can carry different limits).
  • Unidentified requests lose consumer settings: a request without valid credentials does not match a consumer, so consumer-scoped settings never apply to it.

Before relying on this, send requests with two different consumer credentials to the same route and confirm each receives its own configured behavior, then send one request with no credentials and confirm it is rejected or handled by the route-level policy you expect.

Why APISIX 3.15 blocks duplicate plugins in global rules

APISIX 3.15.0 disallows creating duplicate plugins in global rules, so a global rule that declares the same plugin more than once will now be rejected by the Admin API. Teams that generate global rules from templates, merge several overlay files, or copy policy blocks between environments are the most likely to hit this. The practical step is to treat the 3.15.0 change as a validation gate: before you upgrade, export every global rule your gateway holds, then search each plugins object for repeated keys and consolidate the duplicates into one definition per plugin.

The second change matters for the same review. APISIX 3.14.0 stopped the Admin API from populating default values when it writes resources. Before that release, a write could silently fill in plugin defaults, so a stored resource might look more complete than the file that produced it. After 3.14.0, what your pipeline sends is what gets stored, which means any default you relied on must now be written explicitly. Compare the exported state with your repository for at least one resource of each type, and confirm that the configuration-as-code tool you use does not depend on server-side defaults.

For configuration-as-code pipelines, add a diff step that compares the desired state with the live state after each write, and make the pipeline fail on duplicate plugin keys rather than letting the Admin API reject them mid-run. Check the APISIX changelog for every release between your current version and your target, not only the entries for 3.14.0 and 3.15.0, because other behavior changes may affect the same resources. Confirm with your platform team which owner signs off on global rule changes, and record the upgrade test results alongside the release.

How to structure global rules and plugin configs step by step

This sequence moves plugin configuration from copies scattered across routes into a small set of gateway-wide rules, named plugin configs and targeted consumer bindings, with a check at each stage that confirms the gateway behaves as intended.

  1. Inventory plugins repeated across routes

    The gateway owner exports the current route, service and consumer definitions through the Admin API or a configuration file and lists every plugin that appears more than once, along with its settings. Common candidates include authentication headers, rate limits, request ID injection and logging. Each repeated plugin is recorded with the routes that carry it and whether the settings are identical. The step is done when the team has a table showing each repeated plugin, its copy count and any settings that differ between copies, because differing copies usually signal a configuration drift problem to resolve before consolidation.

  2. Classify plugins by scope

    The platform team and the owners of each API team decide which plugins are gateway-wide policy, such as security headers or request ID generation, and which belong to a team or a single API, such as a partner-specific rate limit. The decision is written against each plugin in the inventory, with a named owner for every per-team entry. Gateway-wide candidates should be policies that every route must carry regardless of owner. The step is complete when every plugin in the inventory has one scope label and one owner, which becomes the basis for the global rule and plugin config design in the next steps.

  3. Move gateway-wide policy into global rules

    The platform team creates global rules for the plugins classified as gateway-wide, one global rule per plugin, since APISIX 3.15.0 disallows duplicate plugins in global rules. The Admin API is used to write these resources, and each resource is version-controlled with the rest of the gateway configuration. Before removing any copies from individual routes, the team confirms that the global rule's settings match the values that were previously repeated. The step is done when a test route with no plugins of its own returns the expected headers or log behavior, showing that the global rule is applied.

  4. Group shared team plugins into named plugin configs

    For plugin sets that several routes share but that are not gateway-wide, the API owner creates a named plugin config and attaches it to each route that needs the set. This keeps one definition per set so a change is made in one place and applied to every linked route. Plugin configs should be named after the policy they carry, such as a partner rate limit set, rather than the route they were first used on. The step is done when each named plugin config is referenced by the routes that need it, and a query of those routes shows the same plugin config identifier, with no leftover inline copies of its plugins.

  5. Attach consumers only where caller identity matters

    The security owner identifies the APIs that must know which client is calling, such as those using key-auth or jwt-auth, and creates consumers only for those callers. A consumer is identified by username and carries the authentication plugin's credentials, so unnecessary consumers add credential sprawl without benefit. Consumer-specific settings, such as a per-client limit, are placed on the consumer only when the policy truly differs by caller. The step is complete when each consumer maps to a documented business owner and each API that uses consumer-level policy has a written reason for it.

  6. Confirm the precedence order on a test route

    APISIX applies plugins in the order Consumer, then Route, then Plugin Config, then Service, so a setting defined on a consumer takes priority over the same plugin defined elsewhere. The platform team creates an illustrative test route with the same plugin defined at the service, plugin config and route levels, then sends representative requests with and without a consumer credential. The team compares the observed response headers, status codes or rate-limit behavior with the expected precedence. The step is done when the results match the documented order and the team records them as the reference for future changes.

  7. Review the effective configuration before release

    Before a change is promoted, the reviewer reads the stored definitions for the test route and confirms which global rules, plugin configs, service and consumer settings apply to it. The check covers duplicate plugins, leftover inline copies and any setting that changed without an owner's approval. The team also confirms the Admin API stores what was sent, since APISIX 3.14.0 stopped the Admin API from populating default values when writing resources, so reviewers should not assume defaults appear in the stored output. The step is complete when the review record shows no unexplained overlaps and the test requests pass in staging.

Choosing between global rules, plugin configs and per-route plugins

This table compares five places to attach APISIX plugins by what each one scopes, who usually owns it, how it is changed and when it fits. Read it as a decision aid: start with the widest scope that matches the policy, and narrow only when a specific API, team or caller needs a different setting.

OptionWhat it scopesWho typically owns itHow it is changedWhen it fits
Global rulesEvery request the gateway handles, unless a more specific object overrides itPlatform or gateway teamAdmin API update of the global rule object, reviewed as a platform changeGateway-wide policy such as baseline logging, common security headers or a shared observability plugin
Plugin configsAny set of routes or services that reference the same config by IDPlatform team, with input from API ownersUpdate the shared object once and every referencing route picks it upA reusable bundle, such as one authentication and rate-limit profile, applied to many routes
Route-level pluginsA single route, identified by its URI and methodsAPI or service team that owns the endpointChange the route definition, often through the team's own deployment pipelineBehavior unique to one endpoint, such as a specific transformation or a stricter limit on a sensitive operation
Service-level pluginsAll routes that point to one service objectOwner of the backend serviceUpdate the service object, which affects every route bound to itOne backend exposing many routes that all need the same plugin set, without repeating it per route
Consumer-level pluginsRequests from one authenticated consumer identityTeam that issues and manages API credentialsCreate or update the consumer and its credentials through the Admin APIPer-caller settings such as a quota or identity-specific handling tied to a key, JWT or other credential

Where plugin configuration goes wrong in production

Plugin configuration in APISIX is spread across global rules, plugin configs, consumers, routes and services, and the Admin API can change any of them at runtime. The risks below come from how those layers combine, so each one is worth checking before the configuration reaches production.

Global rule reaches every route

A global rule applies its plugins to all routes, including ones that were never meant to carry that policy. A rate limit, header rewrite or authentication check added at gateway level can break health endpoints, internal APIs or partner routes that sit behind the same gateway. Before enabling a global rule, list the routes it will touch and confirm that each one expects the policy. Since 3.15.0, APISIX rejects duplicate plugins in global rules, so review the rule's plugin list as a whole, not only the new entry.

Consumer plugin overrides route policy

Precedence runs Consumer, then Route, then Plugin Config, then Service, so a plugin configured on a consumer can take precedence over the policy the route owner set. A consumer-level rate limit or header rule may quietly replace the limit that the API team reviewed. Map each consumer's plugins against the routes it calls, and record which team owns the consumer object. Treat consumer changes as policy changes, even though they look like credential updates.

Duplicated plugins drift apart

Teams often copy a working plugin block into several routes or services instead of referencing one plugin config. Over time the copies diverge: one gets a new timeout, another keeps an old allowlist, and nobody can say which one is current. Use reusable plugin configs for shared policy, and check which resources reference each config before changing it. Compare exported resources across environments to catch drift that the gateway itself will not report.

Admin API changes without review

The Admin API can create or update routes, global rules, plugin configs, consumers and secrets directly, so a single authenticated call can change live traffic with no pull request and no approval record. The Admin API is also the path most likely to be scripted by automation that no one reviews. Route all changes through version-controlled configuration, restrict Admin API access to the deployment pipeline, and log every write to a system your audit team can read.

Upgrades change how resources are written

APISIX 3.14.0 stopped the Admin API from filling in default values when writing resources. Configuration that relied on those defaults can behave differently after an upgrade, even though the file looks unchanged. Before upgrading, export every global rule, plugin config, route and consumer, compare the stored form with what your templates produce, and test the difference in a staging gateway. Read the changelog entries for each version between your current and target release.

Securing the Admin API and reviewing plugin changes

Access to the Admin API is the control that decides who can change gateway policy. Global rules, plugin configs, consumers and consumer credentials are all created and edited through the Admin API, so a user or automation account that can write to it can add a plugin to every route, loosen an authentication rule or issue a new key to a consumer. Treat the Admin API as the most privileged interface in the gateway. Confirm which network segments can reach the Admin API port in your deployment (in traditional mode that is port 9180 per the deployment modes documentation), restrict it to administration hosts or a management network, and issue separate admin keys to people and pipelines so that each change can be traced to an identity. Consumer credentials such as keys and secrets are also stored in the configuration, so the same review applies to who can read them, not only to who can write them.

Keep every change reviewable by storing the desired state in version control. Keep global rules, plugin configs and the route definitions that reference them as files in a repository, and apply changes through a pipeline rather than by hand against the Admin API. A pull request then shows the exact plugin list that will run before and after the change, and the precedence rules explained in the previous section make it possible to check which plugin wins on a given route. Run each change first in a non-production gateway that uses the same APISIX version and plugin set, and send a test request that exercises the affected routes and consumers. Ask your team to confirm the version used in staging matches production, since plugin behavior can change between releases. Where a duplicate plugin would be created, the check added in 3.15.0 is the safety net, but a review step still catches intent errors that the gateway cannot detect.

Hardening the gateway itself, including the Admin API, etcd, TLS, encryption of stored secrets and header trust, is a separate body of work with its own scope, and this page does not cover it. Ask whether that work is planned before go-live, because it determines how the Admin API is exposed and how secrets are protected at rest. The APISIX repository and project documentation are the starting point for confirming which of these controls your release supports.

Questions teams ask before changing plugin configuration

How much effort does it take to restructure plugins on an existing APISIX gateway?

The effort depends mostly on how many routes and services already carry copied plugin blocks, how many distinct plugin combinations are in use, and how much of the current configuration lives in the Admin API versus files in version control. A gateway with a small set of routes and a few repeated policies is usually a short exercise, while one with hundreds of routes that each define their own rate limits, authentication and headers needs an inventory first. Ask any partner to start with a read-only export of current routes, services, consumers, global rules and plugin configs, then size the consolidation from that export rather than from a general estimate.

What does the work need from our internal team?

Three roles matter most. Someone who owns the gateway configuration must confirm which policies are intentional and which are historical leftovers. A security or compliance owner must approve changes to authentication, consumer identity and any policy that touches audit evidence. An engineer who understands how upstream services expect headers and paths must check that moving a plugin from a route to a shared plugin config does not change behavior for services that depend on it. Plan time for these people up front, because most delays come from waiting for decisions, not from editing configuration.

Can we restructure global rules and plugin configs in-house?

Yes, if your team already runs APISIX through the Admin API or declarative configuration and has a test environment that mirrors production routes. The mechanics are not difficult: global rules apply gateway-wide, plugin configs are reusable sets referenced by routes, and precedence is consumer, then route, then plugin config, then service. The harder part is proving that each change keeps the intended behavior for every route, which needs replayable test traffic and a rollback path. Teams without that testing capacity often bring in an outside engineer for the first consolidation and keep the resulting structure in their own repository.

How do APISIX upgrades affect existing global rules?

Upgrades can change how global rules and plugin configs behave, so each upgrade needs a review before it reaches production. The APISIX 3.15.0 release disallows creating duplicate plugins in global rules, so a configuration that loaded on an earlier version may be rejected or need cleanup when you move forward. The APISIX 3.14.0 release stopped the Admin API from populating default values when writing resources, which can change the stored state that your tooling compares against. Read the changelog for each version between your current and target release, export configuration before and after the move, and diff the two. The upgrade guides are the place to confirm version-specific behavior.

What does a fixed-scope engagement cover for plugin structure work?

A fixed-scope engagement is agreed in writing before work starts and lists the deliverables and timeline. For this topic it typically covers an inventory of current plugin use, a target design for global rules, plugin configs and consumer-level policy, the configuration changes themselves, test cases that prove the behavior of key routes, and documentation that explains who may change each layer. Items usually left out are changes to upstream services, new authentication providers and application code, so list those separately if you need them. A quote follows from the written scope, and DeployOpen does not publish a price list.

What makes the cost of this work go up or down?

Cost moves with the number of routes and services, the variety of plugins in use, how many environments must be kept in step, and how strict the review rules are. Each additional plugin type adds configuration to test, and each environment adds a deployment and verification pass. Review requirements matter too: if every change to authentication or rate limiting needs security sign-off, the schedule depends on approval cycles that no partner controls. Ask for a quote that separates one-time restructuring from recurring work such as upgrades, reviews of new plugin use and ongoing support, since the recurring part depends on how often your policies change.

What should we verify after consolidating plugins?

Check that each route returns the same status codes, headers and authentication results as before the change, and that a request from each consumer type is accepted or rejected as intended. Confirm that precedence works as you designed it: a consumer-level plugin should override the route value, and a service-level setting should not silently replace a route-level one. Keep a set of replayable requests for critical routes, store the exported configuration in version control, and record who approved each change. Your auditors will ask for this evidence, and it is easier to produce when it is created during the work.

What to confirm in your own APISIX environment

Plugin precedence, global rules and configuration delivery all depend on the exact APISIX version and deployment mode you run. The cards below are questions to answer in your own environment before you design the plugin structure, so each one can be settled against your real configuration rather than assumed.

Precedence behavior in your version

Confirm how your APISIX version resolves a plugin that is set on the consumer, route, plugin config and service at once. The documented order is Consumer, then Route, then Plugin Config, then Service, but the effective behavior for each plugin should be checked by testing a request against your running version. Record the result for each plugin you rely on, and repeat the check after every upgrade.

Duplicates in existing global rules

Ask whether your current global rules already define the same plugin more than once, since versions from 3.15.0 reject duplicate plugins in global rules. Export every global rule through the Admin API and list the plugin names per rule before any upgrade. A rule that once loaded may fail to write after the upgrade, so the list should guide cleanup planning.

Configuration delivery by deployment mode

Confirm which of the three deployment modes you run, because it determines how global rules and plugin configs reach the data plane. In traditional and decoupled modes, changes flow through the shared etcd cluster, while standalone mode reads a file or API. Check how quickly each gateway node picks up a change, and whether a stale node could apply an older policy during a rollout.

Admin API defaults on writes

Confirm how your version handles default values when resources are written through the Admin API, since 3.14.0 stopped the Admin API from populating defaults. Compare stored resources against what your automation or GitOps tooling sends. A plugin that depended on an implicit default may behave differently after an upgrade, so review the output of a read after each write.

Identity provider consumer mapping

Ask how your identity provider's claims or client identifiers map to an APISIX consumer, since the consumer is what triggers consumer-level plugins. Confirm whether one consumer per user, per application or per tenant is intended, and which authentication plugin supplies the identity. A mapping that puts many callers under one consumer will share its rate limits and policies across them.

Ownership of shared policy

Confirm who may change global rules and plugin configs, and whether those changes go through review. Global rules apply to every route, so a single edit can alter traffic for the whole gateway. Agree on an owner for each global rule, a change record, and a rollback step that restores the previous rule set in the same way it was applied.

How the work fits into an APISIX implementation

Plugin structure is rarely a separate task. In an APISIX implementation, decisions about global rules, plugin configs and precedence are made at the same time as route design, authentication choices and the migration plan, because each of those decisions determines where a plugin should attach. A global rule that applies a rate limit to every route, a plugin config reused across a product line, and a consumer-level key-auth setting all interact. Deciding them one at a time tends to produce duplicated settings that are hard to trace later. The practical starting point is an inventory of the plugins each existing route already relies on, grouped by whether they are gateway-wide, shared by several services, or specific to one API.

DeployOpen works from a written scope. The scope states which routes, consumers and plugin policies are in the implementation, which configuration will be managed as code and which Admin API resources will be created, and who approves the naming and grouping conventions. Restructuring existing plugin configuration can be a defined deliverable inside a migration or a new build, or it can be a separate review of a gateway already running in production. Either way, the scope should say what is changed, what is left alone, and how the team will confirm that requests still receive the same plugins after the change. Ask for the list of Admin API resources in scope before work starts, since the Admin API covers routes, services, consumers, global rules and plugin configs as separate objects.

Your team should confirm a few things before any quote is final: the APISIX version you run or plan to run, since the duplicate-plugin check in global rules arrived in 3.15.0 and affects how existing configuration behaves on upgrade; whether gateway configuration is managed in a Git repository or edited through the Admin API; and which person owns changes to shared policy. Results such as fewer incidents or simpler audits depend on your services and controls, so DeployOpen scopes the structural work and states its deliverables, not outcomes you should expect from it.

How DeployOpen scopes and delivers APISIX plugin configuration work

DeployOpen plans the plugin layout for your APISIX gateway before any route is written, so global rules, plugin configs and consumer policies each have a clear owner and a clear place. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

  • We inventory existing policies and decide which belong in global rules, plugin configs, consumers, routes or services.
  • The written scope names each plugin, its precedence position and the routes or consumers it applies to.
  • We agree in writing which plugin configs are reusable templates and which policies stay route-specific.

How we build

  • We author global rules and plugin configs through the Admin API or configuration as code, reviewed in version control.
  • We test precedence with representative requests to confirm which plugin settings take effect for each caller.
  • We check for duplicate plugins in global rules, including behavior on APISIX 3.15 and later versions.

How we hand over

  • You receive a documented map of plugin layers, owners, and the order in which settings are evaluated.
  • Runbooks explain how to add a route, a consumer or a plugin config without creating conflicting policy.
  • Knowledge transfer sessions cover change review, rollback steps and where configuration is stored.

How we support

  • Ongoing support, upgrades and testing are available as a retainer after handover.
  • Retainers can cover reviews of new global rules and plugin configs before they reach production.
  • Upgrade reviews check precedence and plugin behavior against the release notes for your target version.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.