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.
Example plugin configuration
Enable on a service
Enable on a route
Enable on a consumer
Enable globally
The following examples provide some typical configurations for enabling
the response-ratelimiting
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.policy=local"
Replace SERVICE_NAME|SERVICE_ID
with 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
policy: local
plugin: response-ratelimiting
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: response-ratelimiting-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with 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
.
Add this section to your declarative configuration file:
plugins:
- name: response-ratelimiting
service: SERVICE_NAME|SERVICE_ID
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
policy: local
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- In the Plugins section, click Add Plugin.
- Find and select the Response Rate Limiting plugin.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the Response Rate Limiting plugin.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- Click Create.
The following examples provide some typical configurations for enabling
the response-ratelimiting
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.policy=local"
Replace ROUTE_NAME|ROUTE_ID
with 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
policy: local
plugin: response-ratelimiting
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: response-ratelimiting-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with 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
.
Add this section to your declarative configuration file:
plugins:
- name: response-ratelimiting
route: ROUTE_NAME
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
policy: local
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- Select a route.
- In the Plugins section, click Add Plugin.
- Find and select the Response Rate Limiting plugin.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the Response Rate Limiting plugin.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- Click Create.
The following examples provide some typical configurations for enabling
the response-ratelimiting
plugin on a
consumer.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/consumers/CONSUMER_NAME|CONSUMER_ID/plugins \
--data "name=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.policy=local"
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
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
policy: local
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_NAME|CONSUMER_ID
annotations:
konghq.com/plugins: response-ratelimiting-example
kubernetes.io/ingress.class: kong
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
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
.
Add this section to your declarative configuration file:
plugins:
- name: response-ratelimiting
consumer: CONSUMER_NAME|CONSUMER_ID
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
policy: local
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Consumers section, click View for the consumer row.
- Select the Plugins tab, then click Add Plugin.
- Find and select the Response Rate Limiting plugin.
- If the option is available, select Scoped.
- Add the consumer ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- Click Create.
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.
The following examples provide some typical configurations for enabling
the response-ratelimiting
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=response-ratelimiting" \
--data "config.limits.{limit_name}=<SMS>" \
--data "config.limits.{limit_name}.minute=10" \
--data "config.policy=local"
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
policy: local
plugin: response-ratelimiting
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: response-ratelimiting
config:
limits:
{limit_name}: <SMS>
limits:
{limit_name}:
minute: 10
policy: local
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the Response Rate Limiting plugin.
- If the option is available, set the plugin scope to Global.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Limits.{limit Name}:
<SMS>
- 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.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
consumer.name or consumer.id
Type: string |
The name or ID of the consumer the plugin targets.
Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.
Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins . |
enabled
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 number of HTTP requests the developer can make per month. A month is defined as a 30-day interval of time, not a calendar month. At least one limit must exist.
|
config.limits.{limit_name}.year
semi-optional
Type: number
|
The number of HTTP requests the developer can make per year. A year is defined as a 365-day interval of time, not a calendar 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: local
|
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, 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.
This requires Redis v6.0.0+. The username cannot be set to default .
This field is referenceable, which means it can be securely stored as a
secret
in a vault. References must follow a specific format.
|
config.redis_password
optional
Type: string
|
When using the redis policy, this property specifies the password to connect to the Redis server.
This field is referenceable, which means it can be securely stored as a
secret
in a vault. References must follow a specific format.
|
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.
|
config.redis_ssl
required
Type: boolean
Default value: false
|
When using the redis policy, this property specifies if SSL is used to connect to the Redis server.
|
config.redis_ssl_verify
required
Type: boolean
Default value: false
|
When using the redis policy with redis_ssl set to true , this property specifies if the server SSL certificate is validated. 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.
|
config.redis_server_name
optional
Type: string
|
When using the redis policy with redis_ssl set to true , this property specifies the server name for the TLS extension Server Name Indication (SNI)
|
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 3.1.x
- Added the
redis_ssl
, redis_ssl_verify
, and redis_server_name
configuration parameters.
Kong Gateway 2.8.x
- Added the
redis_username
configuration parameter.