Skip to content
|
search
Plugin Hub
header icon

Response Rate Limiting

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

The following examples provide some typical configurations for enabling the response-ratelimiting plugin on a service.

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 servicehub icon Service Hub, select a service version, then set up the plugin:

  1. In the Plugins section, click Add Plugin.
  2. Find and select the Response Rate Limiting plugin.

  3. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  4. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. From the Services section, click View for the service row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the Response Rate Limiting plugin.
  5. If the option is available, select Scoped.
  6. Add the service name and ID to the Service field if it is not already pre-filled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  8. Click Create.

The following examples provide some typical configurations for enabling the response-ratelimiting plugin on a route.

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 servicehub icon Service Hub, select a service version, then set up the plugin:

  1. Select a route.
  2. In the Plugins section, click Add Plugin.
  3. Find and select the Response Rate Limiting plugin.

  4. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  5. Click Create.

You can configure this plugin through the Kong Manager UI.

  1. In Kong Manager, select the workspace.
  2. Open Routes from the menu, then click View for the route row.
  3. From the plugin section, click Add Plugin.
  4. Find and select the Response Rate Limiting plugin.
  5. If the option is available, select Scoped.
  6. Add the route ID if it is not already prefilled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  8. Click Create.

The following examples provide some typical configurations for enabling the response-ratelimiting plugin on a consumer.

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.

  1. In Kong Manager, select the workspace.
  2. From the Consumers section, click View for the consumer row.
  3. Select the Plugins tab, then click Add Plugin.
  4. Find and select the Response Rate Limiting plugin.
  5. If the option is available, select Scoped.
  6. Add the consumer ID if it is not already prefilled.

  7. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  8. 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.

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.

  1. In Kong Manager, select the workspace.
  2. Open Plugins from the menu, then click New Plugin.
  3. Find and select the Response Rate Limiting plugin.
  4. If the option is available, set the plugin scope to Global.

  5. Configure the plugin’s parameters.

    You can test out the plugin with the following sample configuration:

    • Config.Limits.{limit Name}: <SMS>
  6. 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.

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