This plugin allows you to limit the number of requests a developer can make
based on a custom response header returned by the upstream service. You can
arbitrarily set as many rate-limiting objects (or quotas) as you want and
instruct Kong to increase or decrease them by any number of units. Each custom
rate-limiting object can limit the inbound requests per seconds, minutes, hours,
days, months, or years.
If the underlying Service/Route has no authentication
layer, the Client IP address will be used; otherwise, the Consumer will be
used if an authentication plugin has been configured.
Configuration Reference
This plugin is partially compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway
declaratively.
Therefore, the Admin API is mostly read-only. The only tasks it can perform are all
related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
The plugin will run fine with the local
policy (which doesn’t use the database) or
the redis
policy (which uses an independent Redis, so it is compatible with DB-less).
The plugin will not work with the cluster
policy, which requires writes to the database.
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=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.block_on_first_violation=false" \
--data "config.policy=local" \
--data "config.fault_tolerant=true" \
--data "config.hide_client_headers=false"
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: <response-ratelimiting-example>
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
plugin: response-ratelimiting
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: <response-ratelimiting-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: response-ratelimiting
service: {SERVICE}
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
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 Response Rate Limiting plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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 Response Rate Limiting 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.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.block_on_first_violation=false" \
--data "config.policy=local" \
--data "config.fault_tolerant=true" \
--data "config.hide_client_headers=false"
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: <response-ratelimiting-example>
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
plugin: response-ratelimiting
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: <response-ratelimiting-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: response-ratelimiting
route: <route>
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
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 Response Rate Limiting plugin.
-
Enter the following parameters, updating the default
or sample values as needed:
- Config.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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 Response Rate Limiting 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.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.block_on_first_violation=false" \
--data "config.policy=local" \
--data "config.fault_tolerant=true" \
--data "config.hide_client_headers=false"
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: <response-ratelimiting-example>
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
plugin: response-ratelimiting
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: <response-ratelimiting-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: response-ratelimiting
consumer: {CONSUMER}
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
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 Response Rate Limiting 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.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.block_on_first_violation=false" \
--data "config.policy=local" \
--data "config.fault_tolerant=true" \
--data "config.hide_client_headers=false"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-response-ratelimiting>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
plugin: response-ratelimiting
For example, configure this plugin using the plugins:
entry in the declarative
configuration file:
plugins:
- name: response-ratelimiting
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
block_on_first_violation: false
policy: local
fault_tolerant: true
hide_client_headers: false
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 Response Rate Limiting 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.Limits.{limit Name}:
<SMS>
- Config.Block On First Violation: clear checkbox
- Config.Fault Tolerant: select checkbox
- Config.Hide Client Headers: clear checkbox
- 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 response-ratelimiting . |
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.limits.{limit_name}
required
Type: string
|
This is a list of custom objects that you can set, with arbitrary names set in the {limit_name } placeholder, like config.limits.sms.minute=20 if your object is called “SMS”.
|
config.limits.{limit_name}.second
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per second. At least one limit must exist.
|
config.limits.{limit_name}.minute
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per minute. At least one limit must exist.
|
config.limits.{limit_name}.hour
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per hour. At least one limit must exist.
|
config.limits.{limit_name}.day
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per day. At least one limit must exist.
|
config.limits.{limit_name}.month
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per month. At least one limit must exist.
|
config.limits.{limit_name}.year
semi-optional
Type: number
|
The amount of HTTP requests the developer can make per year. At least one limit must exist.
|
config.header_name
optional
Type: string
Default value: X-Kong-Limit
|
The name of the response header used to increment the counters.
|
config.block_on_first_violation
required
Type: boolean
Default value: false
|
A boolean value that determines if the requests should be blocked as soon as one limit is being exceeded. This will block requests that are supposed to consume other limits too.
|
config.limit_by
optional
Type: string
Default value: consumer
|
The entity that will be used when aggregating the limits: consumer , credential , ip . If the consumer or the credential cannot be determined, the system will always fallback to ip .
|
config.policy
optional
Type: string
Default value: cluster
|
The rate-limiting policies to use for retrieving and incrementing the
limits. Available values are:
local : Counters are stored locally in-memory on the node.
cluster : Counters are stored in the Kong datastore and shared across
the nodes.
redis : Counters are stored on a Redis server and shared
across the nodes.
In DB-less and hybrid modes, the cluster config policy is not supported.
For DB-less mode, use one of redis or local ; for hybrid mode, use
redis , or local for data planes only.
In Konnect Cloud, the default policy is redis .
For details on which policy should be used, refer to the
implementation considerations.
|
config.fault_tolerant
required
Type: boolean
Default value: true
|
A boolean value that determines if the requests should be proxied even if Kong has troubles connecting a third-party datastore. If true , requests will be proxied anyway, effectively disabling the rate-limiting function until the datastore is working again. If false , then the clients will see 500 errors.
|
config.hide_client_headers
required
Type: boolean
Default value: false
|
Optionally hide informative response headers.
|
config.redis_host
semi-optional
Type: string
|
When using the redis policy, this property specifies the address to the Redis server.
|
config.redis_port
optional
Type: integer
Default value: 6379
|
When using the redis policy, this property specifies the port of the Redis server.
|
config.redis_username
optional
Type: string
|
When using the redis policy, this property specifies the username to connect to the Redis server when ACL authentication is desired.
|
config.redis_password
optional
Type: string
|
When using the redis policy, this property specifies the password to connect to the Redis server.
|
config.redis_timeout
optional
Type: number
Default value: 2000
|
When using the redis policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server.
|
config.redis_database
optional
Type: number
Default value: 0
|
When using the redis policy, this property specifies Redis database to use.
|
Configuring Quotas
After adding the plugin, you can increment the configured limits by adding the following response header:
Header-Name: Limit=Value [,Limit=Value]
Because X-Kong-Limit
is the default header name (you can optionally change it),
the request looks like:
curl -v -H 'X-Kong-Limit: limitname1=2, limitname2=4'
The above example increments the limit limitname1
by 2 units, and limitname2
by 4 units.
You can optionally increment more than one limit with comma-separated entries.
The header is removed before returning the response to the original client.
When the plugin is enabled, Kong sends some additional headers back to the
client telling how many units are available and how many are allowed.
For example, if you created a limit/quota called “Videos” with a per-minute limit:
X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 9
If more than one limit value is being set, it returns a combination of more time limits:
X-RateLimit-Limit-Videos-Second: 5
X-RateLimit-Remaining-Videos-Second: 5
X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 10
If any of the limits configured is being reached, the plugin
returns an HTTP/1.1 429
(Too Many Requests) status code and an empty response body.
The plugin appends the usage headers for each limit before proxying it to the
upstream service, so that you can properly refuse to process the request if there
are no more limits remaining. The headers are in the form of
X-RateLimit-Remaining-{limit_name}
, for example:
X-RateLimit-Remaining-Videos: 3
X-RateLimit-Remaining-Images: 0
Changelog
Kong Gateway 2.8.x (plugin version 2.0.1)
- Added the
redis_username
configuration parameter.
- Fixed plugin versions in the documentation. Previously, the plugin versions
were labelled as
0.1-x
and 1.0-x
. They are now updated to align with the
plugin’s actual versions, 1.0.x
and 2.0.x
.