Response Rate Limiting plugin

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.

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.

Headers sent to the 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.

Upstream Headers

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.

About this Plugin
Plugin Version	2.0.x
Made by	Kong Inc.
Categories	Traffic Control
DB-less compatible?	Partially
Konnect Cloud compatible?	Yes
Compatible protocols	`http` `https`
Version Compatibility
Kong Gateway 2.8.x 2.7.x 2.6.x 2.5.x 2.4.x 2.3.x 2.2.x 2.1.x 1.5.x 1.3-x 0.36-x Kong Gateway (OSS) 2.8.x 2.7.x 2.6.x 2.5.x 2.4.x 2.3.x 2.2.x 2.1.x 2.0.x 1.5.x 1.4.x 1.3.x 1.2.x 1.1.x 1.0.x