Introducing Kong Dynamic Plugin Ordering

Viktor Gamov and Rick Spurgeon co-authored this blog post.

Kong Gateway provides dynamic plugin ordering allowing administrators to control plugin execution order. Dynamic plugin ordering was added in Kong Enterprise 3.0 and the full technical reference is available in the official documentation. (Check out the overview of what’s new in Kong Gateway 3.0 announced at Kong Summit 2022.)

Kong Gateway: API sentinel

Kong Gateway is a lightweight, fast, and flexible API gateway. An API gateway is a reverse proxy that sits between your APIs and their consumers. Think of Kong Gateway as a guard at the door for your APIs. Requests are made to Kong Gateway, which provides the ability to protect, route, audit, and transform requests before they arrive at your API's waiting connection. These features are enabled via the Kong Gateway Plugin system, which allows for highly specialized configurations suited to your system's specific needs.

Kong Gateway ships with bundled plugins and provides a software development kit for building custom ones. The Kong Plugin Hub is the best source for plugin information.

Plugins are defined with a static execution priority, represented by a numeric priority integer. When multiple plugins are set to be executed for a given request, the order is determined by ranking the plugins from highest (largest number) to lowest (smallest number) priority.

The static priority system is a good default mechanism covering common plugin ordering use cases, however, does not work when users have a requirement to customize execution order. For example, the Rate Limiting plugin has a static priority of 910 , and the Key Authentication plugin has a static priority of 1250. This is fine for situations where users wish to authorize requests before rate limiting them, but not possible if the reverse is desired.

Kong Enterprise 3.0 introduces dynamic plugin ordering, which allows users to explicitly define the execution of plugins. The following guide looks at how Kong Gateway behaves by default and then modifies the behavior to change the plugin execution order.

Kong Gateway Setup

When experimenting with new features with Kong Gateway, it's often helpful to have a test instance that is easy to create and destroy. The following instructions assume you have curl and Docker installed.

Start a new Kong Gateway with the quickstart script:

When Kong Gateway is ready, you will see:

The script sets up service and a route for you (via the -m flag above), and you can test that the request proxy (port 8000) works with the following:

Static Plugin Ordering

Next, use the Admin API (port 8001) to install the Key Authentication plugin globally (will be executed for all requests):

Create a new Consumer (example-user):

Assign example-user a new key (secret-key):

Enable the Rate Limiting plugin globally, configuring a maximum of 3 requests per minute:

Now, if you make the same request to the proxy, the gateway will prevent the request forwarding because you enabled the Key Authentication:

Results in:

When Kong Gateway's Rate Limiting plugin is executed, it will inject informational headers into the response. In the response headers above, you will notice there is no rate limiting specific information.

Now, execute an authorized request and you will notice headers containing rate limiting information:

You will notice headers containing rate-limiting information:

Dynamic Plugin Ordering

This works fine, but what if you want to limit request rates before authenticating the caller? You may want to do this to protect your backend authentication service if you use one, or block offending clients as soon as possible. With Kong Gateway 3.0 dynamic ordering, this is a straightforward configuration.

First, disable the current Rate Limiting plugin:

Reinstall the Rate Limiting plugin, this time specifying its execution order before the installed key-auth plugin:

Finally, make an unauthorized request and verify that there is rate-limiting information in the response headers. This is different than the default behavior and validates the dynamic execution order:

If you execute the previous request more than 3 times in 1 minute, you will see the response transition from unauthorized to API rate limit exceeded.