Response Rate Limiting

Rate limiting strategies

The Response Rate Limiting plugin supports three rate limiting strategies: local, cluster, and redis. This is controlled by the config.policy parameter.

Strategy	Description	Pros	Cons
`local`	Counters are stored in-memory on the node.	Minimal performance impact.	Less accurate. Unless there’s a consistent-hashing load balancer in front of Kong, it diverges when scaling the number of nodes.
`cluster`	Counters are stored in the Kong Gateway data store and shared across nodes.	Accurate, no extra components to support.	Each request forces a read and a write on the data store. Therefore, relatively, the biggest performance impact. Not supported in hybrid mode or Konnect deployments.
`redis`	Counters are stored on a Redis server and shared across nodes.	Accurate, less performance impact than a `cluster` policy.	Needs a Redis installation. Bigger performance impact than a `local` policy.

Using cloud authentication with Redis v3.13+

If your plugin uses a Redis datastore, you can authenticate to it with a cloud Redis provider. This allows you to seamlessly rotate credentials without relying on static passwords.

The following providers are supported:

AWS ElastiCache
Azure Managed Redis
Google Cloud Memorystore (with or without Valkey)

You need:

A running Redis instance on an AWS ElastiCache instance for Valkey 7.2 or later or ElastiCache for Redis OSS version 7.0 or later
The ElastiCache user needs to set “Authentication mode” to “IAM”

The following policy assigned to the IAM user/IAM role that is used to connect to the ElastiCache:

{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": [
 "elasticache:Connect"
 ],
 "Resource": [
 "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE",
 "arn:aws:elasticache:ARN_OF_THE_ELASTICACHE_USER"
 ]
 }
 ]
}

Copied!

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
 policy: redis
 redis:
 host: $INSTANCE_ADDRESS
 username: $INSTANCE_USERNAME
 port: 6379
 cloud_authentication:
 auth_provider: aws
 aws_cache_name: $AWS_CACHE_NAME
 aws_is_serverless: false
 aws_region: $AWS_REGION
 aws_access_key_id: $AWS_ACCESS_KEY_ID
 aws_secret_access_key: $AWS_ACCESS_SECRET_KEY

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The ElastiCache instance address.
$INSTANCE_USERNAME: The ElastiCache username with IAM Auth mode configured.
$AWS_CACHE_NAME: Name of your AWS ElastiCache instance.
$AWS_REGION: Your AWS ElastiCache instance region.
$AWS_ACCESS_KEY_ID: (Optional) Your AWS access key ID.
$AWS_ACCESS_SECRET_KEY: (Optional) Your AWS secret access key.

You need:

A running Redis instance on an Azure Managed Redis instance with Entra authentication configured
Add the user/service principal/identity to the “Microsoft Entra Authentication Redis user” list for the Azure Managed Redis instance

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
 policy: redis
 redis:
 host: $INSTANCE_ADDRESS
 username: $INSTANCE_USERNAME
 port: 10000
 cloud_authentication:
 auth_provider: azure
 azure_client_id: $AZURE_CLIENT_ID
 azure_client_secret: $AZURE_CLIENT_SECRET
 azure_tenant_id: $AZURE_TENANT_ID

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The Azure Managed Redis instance address.
$INSTANCE_USERNAME: The object (principal) ID of the Principal/Identity with essential access.
$AZURE_CLIENT_ID: The client ID of the Principal/Identity.
$AZURE_CLIENT_SECRET: (Optional) The client secret of the Principal/Identity.
$AZURE_TENANT_ID: (Optional) The tenant ID of the Principal/Identity.

You need:

A running Redis instance on an Google Cloud Memorystore instance
Assign the principal to the corresponding role:
- Cloud Memorystore Redis DB Connection User(roles/redis.dbConnectionUser) for Memorystore for Redis Cluster
- Memorystore DB Connector User (roles/memorystore.dbConnectionUser) for Memorystore for Valkey

To configure cloud authentication with Redis, add the following parameters to your plugin configuration:

config:
 policy: redis
 redis:
 host: $INSTANCE_ADDRESS
 port: 6379
 cloud_authentication:
 auth_provider: gcp
 gcp_service_account_json: $GCP_SERVICE_ACCOUNT

Copied!

Replace the following with your actual values:

$INSTANCE_ADDRESS: The Memorystore instance address.
$GCP_SERVICE_ACCOUNT: (Optional) The GCP service account JSON.

Limit by IP address

If limiting by IP address, it’s important to understand how Kong Gateway determines the IP address of an incoming request.

The IP address is extracted from the request headers sent to Kong Gateway by downstream clients. Typically, these headers are named X-Real-IP or X-Forwarded-For.

By default, Kong Gateway uses the header name X-Real-IP to identify the client’s IP address. If your environment requires a different header, you can specify this by setting the real_ip_header Nginx property. Depending on your network setup, you may also need to configure the trusted_ips Nginx property to include the load balancer IP address. This ensures that Kong Gateway correctly interprets the client’s IP address, even when the request passes through multiple network layers.

Configuring quotas

After adding the plugin, you can increment the configured limits by adding the following response header:

Header-Name: Limit=Value [,Limit=Value]

Copied!

You can change the default header name using config.header_name.

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 Response Rate Limiting plugin is enabled, Kong Gateway sends additional headers back to the client, indicating how many units are still available and how many are allowed total.

For example, if you created a limit called Videos with a per-minute limit:

X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 9

Copied!

If more than one limit value is set, it returns a combination of all the 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

Copied!

If any of the configured limits configured is reached, the plugin returns an HTTP/1.1 429 (Too Many Requests) status code and an empty response body.

Upstream headers

The plugin appends usage headers for each limit before proxying the request 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

Copied!

URL: https://developer.konghq.com/plugins/response-ratelimiting/