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 (or deprecated API entity) has no authentication layer, the Client IP address will be used; otherwise, the Consumer will be used if an authentication plugin has been configured.

Note: The functionality of this plugin as bundled with versions of Kong prior to 0.13.1 and Kong Enterprise prior to 0.32 differs from what is documented herein. Refer to the CHANGELOG for details.

Configuration Reference

You can configure this plugin using the Kong Admin API or through declarative configuration, which involves directly editing the Kong configuration file.

This plugin is compatible with requests with the following protocols:

http
https

This plugin is partially compatible with DB-less mode.

In DB-less mode, Kong does not have an Admin API. If using this mode, configure the plugin using declarative configuration.

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.

Enabling the plugin on a Service

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin on a Service by making the following request:

$ curl -X POST http://<admin-hostname>:8001/services/<service>/plugins \
    --data "name=response-ratelimiting"  \
    --data "config.limits.{limit_name}=<SMS>" \
    --data "config.limits.{limit_name}.minute=10"

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
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>

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

<service> is the id or name of the Service that this plugin configuration will target.

Note: The legacy API entity has been deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Enabling the plugin on a Route

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin on a Route with:

$ curl -X POST http://<admin-hostname>:8001/routes/<route>/plugins \
    --data "name=response-ratelimiting"  \
    --data "config.limits.{limit_name}=<SMS>" \
    --data "config.limits.{limit_name}.minute=10"

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
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

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

<route> is the id or name of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin on a Consumer with:

$ curl -X POST http://<admin-hostname>:8001/consumers/<consumer>/plugins \
    --data "name=response-ratelimiting"  \
    --data "config.limits.{limit_name}=<SMS>" \
    --data "config.limits.{limit_name}.minute=10"

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
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

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

<consumer> is the id or username of the Consumer that this plugin configuration will target.

Enabling 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.

Kong Admin API

Kubernetes

Declarative (YAML)

For example, configure this plugin globally with:

$ curl -X POST http://<admin-hostname>:8001/plugins/ \
    --data "name=response-ratelimiting"  \
    --data "config.limits.{limit_name}=<SMS>" \
    --data "config.limits.{limit_name}.minute=10"

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
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

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Form Parameter	Description
`name` Type: string	The name of the plugin to use, 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` Type: boolean Default value: `true`	Whether this plugin will be applied.
`api_id` Type: string	The ID of the API the plugin targets. Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.
`config.limits.{limit_name}` required	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	The amount of HTTP requests the developer can make per second. At least one limit must exist.
`config.limits.{limit_name}.minute` semi-optional	The amount of HTTP requests the developer can make per minute. At least one limit must exist.
`config.limits.{limit_name}.hour` semi-optional	The amount of HTTP requests the developer can make per hour. At least one limit must exist.
`config.limits.{limit_name}.day` semi-optional	The amount of HTTP requests the developer can make per day. At least one limit must exist.
`config.limits.{limit_name}.month` semi-optional	The amount of HTTP requests the developer can make per month. At least one limit must exist.
`config.limits.{limit_name}.year` semi-optional	The amount of HTTP requests the developer can make per year. At least one limit must exist.
`config.header_name` optional Default value: X-Kong-Limit	The name of the response header used to increment the counters.
`config.block_on_first_violation` optional 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 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 Default value: cluster	The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local` (counters will be stored locally in-memory on the node), `cluster` (counters are stored in the datastore and shared across the nodes) and `redis` (counters are stored on a Redis server and will be shared across the nodes).
`config.fault_tolerant` optional 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` optional Default value: false	Optionally hide informative response headers.
`config.redis_host` semi-optional	When using the `redis` policy, this property specifies the address to the Redis server.
`config.redis_port` optional Default value: 6379	When using the `redis` policy, this property specifies the port of the Redis server.
`config.redis_password` optional	When using the `redis` policy, this property specifies the password to connect to the Redis server.
`config.redis_timeout` optional 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 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

About this Plugin
Made by
Categories	Traffic Control
DB-less compatible?	Partially (Kong Gateway only)
Bundled with...
Kong Enterprise 2.2.x 2.1.x 1.5.x 1.3-x 0.36-x 0.35-x 0.34-x 0.33-x 0.32-x 0.31-x Kong Community 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 0.14.x 0.13.x 0.12.x 0.11.x 0.10.x 0.9.x 0.8.x 0.7.x 0.6.x 0.5.x