Rate Limiting Advanced

Rate limit how many HTTP requests can be made in a given time frame using multiple rate limits and window sizes, and applying sliding windows. This plugin is a more advanced version of the Rate Limiting plugin, which only allows one fixed rate limiting window.

If the underlying Gateway Service or Route has no authentication layer, the client IP address is used for identifying clients. Otherwise, the Consumer is used if an authentication plugin has been configured.

Advanced features of this plugin include:

• Sliding window support, which provides better performance than fixed rate limiting
• Multiple limits and window sizes
• Support for Redis Sentinel, Redis cluster, and Redis SSL
• Control over which requests contribute to incrementing the rate limiting counters via the config.disable_penalty parameter

Kong also provides multiple specialized rate limiting plugins, including rate limiting across LLMs and GraphQL queries. See Rate limiting in Kong Gateway to choose the plugin that is most useful in your use case.

The Rate Limiting Advanced plugin supports the following window types:

• Fixed window: Fixed windows consist of buckets that are statically assigned to a definitive time range. Each request is mapped to only one fixed window based on its timestamp and will affect only that window’s counters.
• Sliding window (default): A sliding window tracks the number of hits assigned to a specific key (such as an IP address, consumer, credential) within a given time window, taking into account previous hit rates to create a dynamically calculated rate. The default (and recommended) sliding window type ensures a resource is not consumed at a higher rate than what is configured.

Learn more about how the different window types work for rate limiting plugins.

An arbitrary number of limits or window sizes can be applied per plugin instance. This allows you to create multiple rate limiting windows (for example, rate limit per minute and per hour, and per any arbitrary window size). Because of limitations with Kong Gateway’s plugin configuration interface, each nth limit will apply to each nth window size. For example:

config:
  limit:
    - 10
    - 100
  window_size:
    - 60
    - 3600

This example applies two rate limiting policies, one of which will trip when 10 hits have been counted in 60 seconds, or the other when 100 hits have been counted in 3600 seconds.

The number of configured window sizes and limits parameters must be equal, otherwise you will get the following error:

You must provide the same number of windows and limits

The Rate Limiting Advanced plugin supports three rate limiting strategies: local, cluster, and redis.

This is controlled by the config.strategy parameter.

[1]: Only when config.sync_rate option is set to 0 (synchronous behavior).

Two common use cases for rate limiting are:

1. Every transaction counts: The highest level of accuracy is needed. An example is a transaction with financial consequences.
2. Backend protection: Accuracy is not as relevant. The requirement is only to protect backend services from overloading that’s caused either by specific users or by attacks.

Every transaction counts

In this scenario, because accuracy is important, the local policy is not an option. Consider the support effort you might need for Redis, and then choose either cluster or redis.

You could start with the cluster policy, and move to redis if performance reduces drastically.

If using a very high sync frequency, use redis. Very high sync frequencies with cluster mode are not scalable and not recommended. The sync frequency becomes higher when the sync_rate setting is a lower number - for example, a sync_rate of 0.1 is a much higher sync frequency (10 counter syncs per second) than a sync_rate of 1 (1 counter sync per second).

You can calculate what is considered a very high sync rate in your environment based on your topology, number of plugins, their sync rates, and tolerance for loose rate limits.

Together, the interaction between sync rate and window size affects how accurately the plugin can determine cluster-wide traffic. For example, the following table represents the worst-case scenario where a full sync interval’s worth of data hasn’t yet propagated across nodes:

If you choose to switch strategies, note that you can’t port the existing usage metrics from the Kong Gateway data store to Redis. This might not be a problem with short-lived metrics (for example, seconds or minutes) but if you use metrics with a longer time frame (for example, months), plan your switch carefully.

Backend protection

If accuracy is less important, choose the local policy. You might need to experiment a little before you get a setting that works for your scenario. As the cluster scales to more nodes, more user requests are handled. When the cluster scales down, the probability of false negatives increases. Make sure to adjust your rate limits when scaling.

For example, if a user can make 100 requests every second, and you have an equally balanced 5-node Kong Gateway cluster, you can set the local limit to 30 requests every second. If you see too many false negatives, increase the limit.

To minimize inaccuracies, consider using a consistent-hashing load balancer in front of Kong Gateway. The load balancer ensures that a user is always directed to the same Kong Gateway node, which reduces inaccuracies and prevents scaling problems.

Fallback from Redis

When the redis strategy is used and a Kong Gateway node is disconnected from Redis, the rate-limiting-advanced plugin will fall back to local. This can happen when the Redis server is down or the connection to Redis broken. Kong Gateway keeps the local counters for rate limiting and syncs with Redis once the connection is re-established. Kong Gateway will still rate limit, but the Kong Gateway nodes can’t sync the counters. As a result, users will be able to perform more requests than the limit, but there will still be a limit per node.

If limiting by IP address, it’s important to understand how Kong Gateway determines the IP address of an incoming request.

The IP address is extracted from the request headers sent to Kong Gateway by downstream clients. Typically, these headers are named X-Real-IP or X-Forwarded-For.

By default, Kong Gateway uses the header name X-Real-IP to identify the client’s IP address. If your environment requires a different header, you can specify this by setting the real_ip_header Nginx property. Depending on your network setup, you may also need to configure the trusted_ips Nginx property to include the load balancer IP address. This ensures that Kong Gateway correctly interprets the client’s IP address, even when the request passes through multiple network layers.

When this plugin is enabled, Kong Gateway sends some additional headers back to the client, indicating the state of the rate limiting policies in place:

You can optionally hide the limit and remaining headers with the config.hide_client_headers option.

If more than one limit is set, the plugin returns multiple time limit headers. For example:

X-RateLimit-Limit-Second: 5
X-RateLimit-Remaining-Second: 4
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9

If any of the limits are reached, the plugin returns an HTTP/1.1 429 status code to the client with the following JSON body:

{ "message": "API rate limit exceeded" }

The headers RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset are based on the Internet-Draft RateLimit Header Fields for HTTP and may change in the future to respect specification updates.

You can use the Consumer Groups entity to manage custom rate limiting configurations for subsets of Consumers.

You can see an example of this in the guide on enforcing rate limiting tiers with the Rate Limiting Advanced plugin.