Redis with Kong Gateway
Share rate limits across Kong Gateway nodes with Redis.
Kong Gateway is an API gateway. Its rate-limiting plugin can keep its
counters in Redis, so that several Kong nodes enforce one shared limit. See the rate limiter use case for when to choose
this pattern.
Requirements
The examples on this page were run with the open source Kong Gateway 3.9 image (kong:3.9) in
DB-less mode against Redis 8.0, with two Kong nodes sharing one Redis server.
You also need a running Redis server. You can run one locally with Redis Open Source, use Docker, or connect to Redis Cloud.
Limit requests with a Redis policy
The rate-limiting plugin's policy setting selects where Kong keeps the counters:
| Policy | Where the counters live |
|---|---|
local (default) |
In the memory of each Kong node, so each node enforces its own limit. |
cluster |
In Kong's database. |
redis |
In Redis, shared by every node that uses the same Redis server. |
This declarative configuration allows 3 requests a minute on a route and keeps the counters in Redis:
_format_version: "3.0"
services:
- name: demo
url: http://<your-upstream>
routes:
- name: demo-route
paths:
- /api
plugins:
- name: rate-limiting
config:
minute: 3
policy: redis
redis:
host: <your-redis-host>
port: 6379
database: 0
In a test with two Kong nodes behind the same Redis server, five requests that alternated
between the nodes returned 200, 200, 200, 429, and 429. Each response carried
X-RateLimit-Remaining-Minute and RateLimit-Remaining headers, and the 429 responses
added Retry-After: 60.
Redis connection options
The redis settings of the plugin, from the
Kong plugin reference:
| Setting | Default | Notes |
|---|---|---|
host, port |
none, 6379 |
The Redis server. |
username, password |
none | For ACL authentication (Redis 6.0 or later). If you don't set a password, Kong sends no AUTH command. |
database |
0 |
The logical database. |
ssl, ssl_verify, server_name |
false, true |
Transport Layer Security (TLS) settings. |
timeout |
2000 |
The connection timeout in milliseconds. |
What Kong stores in Redis
Kong keeps one counter for each client and time window, as a string:
ratelimit:<route-id>:<service-id>:<client-ip>:<window-start-ms>:minute
The counter has a time to live (TTL) of 60 seconds for a minute limit. After the five
requests above it held 5: Kong counts the requests that it rejects as well as the ones that it
allows.
When Redis is unavailable
In the test, with the Redis server stopped, Kong let every request through (200), and each
one took about 2 seconds, which is the default timeout. The gateway fails open, but its
latency rises by the connection timeout, so lower timeout if that matters to you.
Kong Gateway Enterprise
According to the Kong documentation, some Redis features are available only in Kong Gateway Enterprise:
- Rate Limiting Advanced adds Redis Sentinel and Redis Cluster support.
- Proxy Cache Advanced caches responses in Redis. The open source
proxy-cacheplugin stores its cache in memory only. - The
sessionplugin stores sessions in the cookie or in Kong's database. It has no Redis storage option.
The examples on this page don't cover these Enterprise plugins.