The Rate Limiting Advanced plugin for Kong Enterprise is a re-engineered version of the incredibly popular Kong Rate Limiting plugin, with greatly enhanced configuration options and performance.
Terminology
plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.Service: the Kong entity representing an external upstream API or microservice.Route: the Kong entity representing a way to map downstream requests to upstream services.Consumer: the Kong entity representing a developer or machine using the API. When using Kong, a Consumer only communicates with Kong which proxies every call to the said upstream API.Credential: a unique string associated with a Consumer, also referred to as an API key.upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.
Configuration
Enabling the plugin on a Service
With a database
Configure this plugin on a Service by making the following request:
$ curl -X POST http://kong:8001/services/{service}/plugins \
--data "name=rate-limiting-advanced"
Without a database
Configure this plugin on a Service by adding this section do your declarative configuration file:
plugins:
- name: rate-limiting-advanced
service: {service}
config:
In both cases, {service} is the id or name of the Service that this plugin configuration will target.
Enabling the plugin on a Route
With a database
Configure this plugin on a Route with:
$ curl -X POST http://kong:8001/routes/{route}/plugins \
--data "name=rate-limiting-advanced"
Without a database
Configure this plugin on a Route by adding this section do your declarative configuration file:
plugins:
- name: rate-limiting-advanced
route: {route}
config:
In both cases, {route} is the id or name of the Route that this plugin configuration will target.
Enabling the plugin on a Consumer
With a database
You can use the http://localhost:8001/plugins endpoint to enable this plugin
on specific Consumers:
$ curl -X POST http://kong:8001/consumers/{consumer}/plugins \
--data "name=rate-limiting-advanced" \
Without a database
Configure this plugin on a Consumer by adding this section do your declarative configuration file:
plugins:
- name: rate-limiting-advanced
consumer: {consumer}
config:
In both cases, {consumer} is the id or username of the Consumer that this plugin configuration will target.
You can combine consumer_id and
service_id
in the same request, to furthermore narrow the scope of the plugin.
Enabling the plugin on an API
If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:
$ curl -X POST http://kong:8001/apis/{api}/plugins \
--data "name=rate-limiting-advanced"
api: either id or name of the API that this plugin configuration will target.
Global plugins
- Using a database, all plugins can be configured using the
http://kong:8001/plugins/endpoint. - Without a database, all plugins can be configured via the
plugins:entry on the declarative configuration file.
A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
| form parameter | description |
|---|---|
name | The name of the plugin to use, in this case rate-limiting-advanced |
service.id | The id of the Service which this plugin will target. |
route.id | The id of the Route which this plugin will target. |
enableddefault value: true | Whether this plugin will be applied. |
api_id | The id of the API which this plugin will target. Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32. |
config.limit
|
One of more request per window to apply |
config.window_size
|
One more more window sizes to apply (defined in seconds) |
config.identifier
default value: consumer |
How to define the rate limit key. Can be |
config.header_name
semi-optional |
Header name to use as the rate limit key when the |
config.dictionary_name
default value: kong_rate_limiting_counters |
The shared dictionary where counters will be stored until the next sync cycle |
config.sync_rate
|
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 that many number of seconds. |
config.namespace
optional default value: random string |
The rate limiting library namespace to use for this plugin instance. Counter data and sync configuration is shared in a namespace. |
config.strategy
default value: cluster |
The sync strategy to use; |
config.redis.host
semi-optional |
Host to use for Redis connection when the |
config.redis.port
semi-optional |
Port to use for Redis connection when the |
config.redis.timeout
semi-optional default value: 2000 |
Connection timeout (in milliseconds) to use for Redis connection when the |
config.redis.password
semi-optional |
Password to use for Redis connection when the |
config.redis.database
semi-optional default value: 0 |
Database to use for Redis connection when the |
config.redis.sentinel_master
semi-optional |
Sentinel master to use for Redis connection when the |
config.redis.sentinel_role
semi-optional |
Sentinel role to use for Redis connection when the |
config.redis.sentinel_addresses
semi-optional |
Sentinel addresses to use for Redis connection when the |
config.redis.cluster_addresses
semi-optional |
Cluster addresses to use for Redis connection when the |
config.window_type
default value: sliding |
This sets the time window to either |
Note: Redis configuration values are ignored if the cluster strategy is used.
Note: PostgreSQL 9.5+ is required when using the cluster strategy with postgres as the backing Kong cluster data store. This requirement varies from the PostgreSQL 9.4+ requirement as described in the Kong Community Edition documentation.
Note: The dictionary_name directive was added to prevent the usage of the kong shared dictionary, which could lead to no memory errors
Notes
An arbitrary number of limits/window sizes can be applied per plugin instance. This allows users to create multiple rate limiting windows (e.g., rate limit per minute and per hour, and/or per any arbitrary window size); because of limitation with Kong’s plugin configuration interface, each nth limit will apply to each nth window size. For example:
$ curl -i -X POST http://kong:8001/services/{service}/plugins \
--data name=rate-limiting-advanced \
--data config.limit=10,100 \
--data config.window_size=60,3600 \
--data config.sync_rate=10
This will apply rate limiting policies, one of which will trip when 10 hits have been counted in 60 seconds, or when 100 hits have been counted in 3600 seconds. For more information, please see Enterprise Rate Limiting Library.