The Rate Limiting Advanced plugin for Kong Gateway is a re-engineered
version of the incredibly popular Kong Community
Rate Limiting plugin,
with greatly enhanced configuration options and performance.
Configuration Reference
Enable the plugin on a service
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
For example, configure this plugin on a service by
making the following request:
curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
--data "name=rate-limiting-advanced" \
--data "config.limit=5" \
--data "config.window_size=30" \
--data "config.identifier=consumer" \
--data "config.dictionary_name=kong_rate_limiting_counters" \
--data "config.sync_rate=-1" \
--data "config.namespace=random_auto_generated_string" \
--data "config.strategy=cluster" \
--data "config.hide_client_headers=false" \
--data "config.window_type=sliding"
SERVICE
is the id
or name
of the service that this plugin
configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: <rate-limiting-advanced-example>
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
plugin: rate-limiting-advanced
Next, apply the KongPlugin resource to a
Service by annotating the
Service as follows:
apiVersion: v1
kind: Service
metadata:
name: {SERVICE}
labels:
app: {SERVICE}
annotations:
konghq.com/plugins: <rate-limiting-advanced-example>
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: {SERVICE}
selector:
app: {SERVICE}
{SERVICE}
is the id
or name
of the service that this plugin
configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
For example, configure this plugin on a service by
adding this section to your declarative configuration file:
plugins:
- name: rate-limiting-advanced
service: {SERVICE}
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
SERVICE
is the id
or name
of the service that this plugin
configuration will target.
Configure this plugin on a service:
- In Konnect Cloud, select the service on the ServiceHub page.
- Scroll down to Versions and select the version.
- Scroll down to Plugins and click New Plugin.
- Find and select the Rate Limiting Advanced plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Configure this plugin on a service:
- In Kong Manager, select the workspace.
- From the Dashboard, scroll down to Services and click View for the
service row.
- Scroll down to plugins and click Add Plugin.
-
Find and select the Rate Limiting Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already prefilled.
-
Enter the following parameters, updating the default or sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Enable the plugin on a route
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
For example, configure this plugin on a route with:
$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
--data "name=rate-limiting-advanced" \
--data "config.limit=5" \
--data "config.window_size=30" \
--data "config.identifier=consumer" \
--data "config.dictionary_name=kong_rate_limiting_counters" \
--data "config.sync_rate=-1" \
--data "config.namespace=random_auto_generated_string" \
--data "config.strategy=cluster" \
--data "config.hide_client_headers=false" \
--data "config.window_type=sliding"
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: <rate-limiting-advanced-example>
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
plugin: rate-limiting-advanced
Then, apply it to an ingress (Route or Routes)
by annotating the ingress as follows:
apiVersion: networking/v1beta1
kind: Ingress
metadata:
name: {ROUTE}
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: <rate-limiting-advanced-example>
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
serviceName: echo
servicePort: 80
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
For example, configure this plugin on a route by
adding this section to your declarative configuration file:
plugins:
- name: rate-limiting-advanced
route: <route>
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
Configure this plugin on a route:
- In Konnect Cloud, select the service from the ServiceHub page.
- Scroll down to Versions and select the version.
- Select the route.
- Scroll down to Plugins and click Add Plugin.
- Find and select the Rate Limiting Advanced plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Configure this plugin on a route:
- In Kong Manager, select the workspace.
- From the Dashboard, select Routes in the left navigation.
- Click View for the route row.
- Scroll down to plugins and click Add Plugin.
-
Find and select the Rate Limiting Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the Route ID if it is not already prefilled.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Enabling the plugin on a consumer
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
For example, configure this plugin on a consumer with:
$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
--data "name=rate-limiting-advanced" \
--data "config.limit=5" \
--data "config.window_size=30" \
--data "config.identifier=consumer" \
--data "config.dictionary_name=kong_rate_limiting_counters" \
--data "config.sync_rate=-1" \
--data "config.namespace=random_auto_generated_string" \
--data "config.strategy=cluster" \
--data "config.hide_client_headers=false" \
--data "config.window_type=sliding"
CONSUMER
is the id
or username
of the consumer that this plugin
configuration will target.
You can combine consumer.id
, service.id
, or route.id
in the same request, to further narrow the scope of the plugin.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: <rate-limiting-advanced-example>
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
plugin: rate-limiting-advanced
Then, apply it to a consumer by
annotating the KongConsumer resource as follows:
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
name: {CONSUMER}
annotations:
konghq.com/plugins: <rate-limiting-advanced-example>
kubernetes.io/ingress.class: kong
CONSUMER
is the id
or username
of the consumer that this plugin
configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any Service, Consumer, or Route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
For example, configure this plugin on a consumer by
adding this section to your declarative configuration file:
plugins:
- name: rate-limiting-advanced
consumer: {CONSUMER}
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
CONSUMER
is the id
or username
of the consumer that this plugin
configuration will target.
Configure this plugin on a consumer:
- In Kong Manager, select the workspace.
- From the Dashboard, scroll down to Consumers and click View for the consumer row.
- Select the Plugins tab.
- Click Add Plugin.
-
Find and select the Rate Limiting Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, select Global.
-
Enter the following parameters, updating the default or sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Enable the plugin globally
A plugin which is not associated to any service, route, or consumer is
considered global, and will be run on every request. Read the
Plugin Reference and the Plugin Precedence
sections for more information.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
For example, configure this plugin globally with:
$ curl -X POST http://{HOST}:8001/plugins/ \
--data "name=rate-limiting-advanced" \
--data "config.limit=5" \
--data "config.window_size=30" \
--data "config.identifier=consumer" \
--data "config.dictionary_name=kong_rate_limiting_counters" \
--data "config.sync_rate=-1" \
--data "config.namespace=random_auto_generated_string" \
--data "config.strategy=cluster" \
--data "config.hide_client_headers=false" \
--data "config.window_type=sliding"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-rate-limiting-advanced>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
plugin: rate-limiting-advanced
For example, configure this plugin using the plugins:
entry in the declarative
configuration file:
plugins:
- name: rate-limiting-advanced
config:
limit:
- 5
window_size:
- 30
identifier: consumer
dictionary_name: kong_rate_limiting_counters
sync_rate: -1
namespace: random_auto_generated_string
strategy: cluster
hide_client_headers: false
window_type: sliding
Configure this plugin globally:
- In Kong Manager, select the workspace.
- From the Dashboard, select Plugins in the left navigation.
- Click New Plugin.
-
Find and select the Rate Limiting Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See
Kong Gateway tiers.
- If the option is available, set the plugin scope to Global.
-
Enter the following parameters, updating the
default/sample values as needed:
- Config.Limit:
5
- Config.Window Size:
30
- Config.Identifier:
consumer
- Config.Dictionary Name:
kong_rate_limiting_counters
- Config.Sync Rate:
-1
- Config.Namespace:
random_auto_generated_string
- Config.Strategy:
cluster
- Config.Window Type:
sliding
- Click Create.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter |
Description |
name
required
Type: string |
The name of the plugin, in this case rate-limiting-advanced . |
service.id
Type: string |
The ID of the Service the plugin targets. |
route.id
Type: string |
The ID of the Route the plugin targets. |
consumer.id
Type: string |
The ID of the Consumer the plugin targets. |
enabled
required
Type: boolean
Default value: true |
Whether this plugin will be applied. |
config.limit
required
Type: array of number elements
|
One or more requests-per-window limits to apply. There must be a matching
number of window limits and sizes specified.
|
config.window_size
required
Type: array of number elements
|
One or more window sizes to apply a limit to (defined in seconds). There
must be a matching number of window limits and sizes specified.
|
config.identifier
required
Type: string
Default value: consumer
|
How to define the rate limit key. Can be ip , credential , consumer , service , or header .
|
config.header_name
semi-optional
Type: string
|
Header name to use as the rate limit key when the header identifier is defined.
|
config.dictionary_name
required
Type: string
Default value: kong_rate_limiting_counters
|
The shared dictionary where counters will be stored until the next sync cycle.
|
config.sync_rate
required
Type: number
|
How often to sync counter data to the central data store. A value of 0
results in synchronous behavior; a value of -1 ignores sync behavior
entirely and only stores counters in node memory. A value greater than
0 will sync the counters in the specified number of seconds.
|
config.namespace
required
Type: string
Default value: random_auto_generated_string
|
The rate limiting library namespace to use for this plugin instance. Counter
data and sync configuration is shared in a namespace.
|
config.strategy
required
Type: string
Default value: cluster
|
The sync strategy to use; cluster and redis are supported. Hybrid mode does
not support the cluster strategy.
|
config.hide_client_headers
optional
Type: boolean
Default value: false
|
Optionally hide informative response headers. Available options: true or false .
|
config.redis.host
semi-optional
Type: string
|
Host to use for Redis connection when the redis strategy is defined.
|
config.redis.port
semi-optional
Type: integer
Default value: 6379
|
Specifies the Redis server port when using the redis strategy. Must be a
value between 0 and 65535. Default: 6379.
|
config.redis.ssl
optional
Type: boolean
Default value: false
|
If set to true, then uses SSL to connect to Redis.
Note: This parameter is only available for Kong Gateway versions
2.2.x and later.
|
config.redis.ssl_verify
optional
Type: boolean
Default value: false
|
If set to true, then verifies the validity of the server SSL certificate. Note that you need to configure the
lua_ssl_trusted_certificate
to specify the CA (or server) certificate used by your redis server. You may also need to configure
lua_ssl_verify_depth accordingly.
Note: This parameter is only available for Kong Gateway versions
2.2.x and later.
|
config.redis.server_name
optional
Type: string
|
Specifies the server name for the new TLS extension Server Name Indication (SNI) when connecting over SSL.
Note: This parameter is only available for Kong Gateway versions
2.2.x and later.
|
config.redis.timeout
semi-optional
Type: number
Default value: 2000
|
Connection timeout (in milliseconds) to use for Redis connection when the redis strategy is defined.
|
config.redis.password
semi-optional
Type: string
|
Password to use for Redis connection when the redis strategy is defined. If undefined, no AUTH commands are sent to Redis.
|
config.redis.database
semi-optional
Type: integer
Default value: 0
|
Database to use for Redis connection when the redis strategy is defined.
|
config.redis.sentinel_master
semi-optional
Type: string
|
Sentinel master to use for Redis connections when the redis strategy is defined.
Defining this value implies using Redis Sentinel.
|
config.redis.sentinel_password
semi-optional
Type: string
|
Sentinel password to authenticate with a Redis Sentinel instance.
Note: This parameter is only available for Kong Gateway versions
1.3.0.2 and later.
|
config.redis.sentinel_role
semi-optional
Type: string
|
Sentinel role to use for Redis connections when the redis strategy is defined.
Defining this value implies using Redis Sentinel. Available options: master , slave , any .
|
config.redis.sentinel_addresses
semi-optional
Type: array of string elements
|
Sentinel addresses to use for Redis connections when the redis strategy is defined.
Defining this value implies using Redis Sentinel. Each string element must
be a hostname. The minimum length of the array is 1 element.
|
config.redis.cluster_addresses
semi-optional
Type: array of string elements
|
Cluster addresses to use for Redis connections when the redis strategy is defined.
Defining this value implies using Redis cluster. Each string element must
be a hostname. The minimum length of the array is 1 element.
|
config.window_type
required
Type: string
Default value: sliding
|
Sets the time window type to either sliding (default) or fixed .
|
Notes:
-
The plugin does not support the cluster
strategy in
hybrid mode.
The redis
strategy must be used instead.
-
Redis configuration values are ignored if the cluster
strategy is used.
-
PostgreSQL 9.5+ is required when using the cluster
strategy with postgres
as the backing Kong cluster data store.
-
The dictionary_name
directive was added to prevent the usage of the kong
shared dictionary,
which could lead to no memory
errors.
When this plugin is enabled, Kong sends some additional headers back to the client
indicating the allowed limits, how many requests are available, and how long it will take
until the quota will be restored.
For example:
RateLimit-Limit: 6
RateLimit-Remaining: 4
RateLimit-Reset: 47
The plugin also sends headers indicating the limits in the time frame and the number
of remaining minutes:
X-RateLimit-Limit-Minute: 10
X-RateLimit-Remaining-Minute: 9
You can optionally hide the limit and remaining headers with the hide_client_headers
option.
If more than one limit is being set, the plugin returns a combination of more time limits:
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 configured has been 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 Retry-After
header will be present on 429
errors to indicate how long the service is
expected to be unavailable to the client. When using window_type=sliding
and RateLimit-Reset
, Retry-After
may increase due to the rate calculation for the sliding window.
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.
Multiple Limits and Window Sizes
An arbitrary number of limits/window sizes can be applied per plugin instance. This allows you to create
multiple rate limiting windows (e.g., rate limit per minute and per hour, and per any arbitrary window size).
Because of limitations with Kong’s plugin configuration interface, each nth limit will apply to each nth window size.
For example:
$ curl -X POST http://kong:8001/services/{service}/plugins \
--data name=rate-limiting-advanced \
--data config.limit=10 \
--data config.limit=100 \
--data config.window_size=60 \
--data config.window_size=3600 \
--data config.sync_rate=10
This example applies 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. For more information, see the
Enterprise Rate Limiting Library.
The number of configured window sizes and limits parameters must be equal (as shown above);
otherwise, an error occurs:
You must provide the same number of windows and limits
Fallback to IP
When the selected strategy cannot be retrieved, the rate-limiting-advanced
plugin will fall back
to limit using IP as the identifier. This can happen for several reasons, such as the
selected header was not sent by the client or the configured service was not found.