Redis with Apache APISIX
Share rate limits across Apache APISIX nodes with Redis.
Apache APISIX is an API gateway. Its limit-count plugin can keep
its counters in Redis, so that several APISIX 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 Apache APISIX 3.13 in standalone mode against Redis 8.0, with two APISIX 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 policy setting of limit-count selects where APISIX keeps the counters. local is the
default, which gives each node its own limit. The other documented values are redis,
redis-cluster, and redis-sentinel. This route allows 3 requests a minute for each client address
and keeps the counters in Redis. In standalone mode, which reads its routes from a file, set
config_provider: yaml in config.yaml:
deployment:
role: data_plane
role_data_plane:
config_provider: yaml
Then put the route in apisix.yaml:
routes:
- uri: /api/*
plugins:
limit-count:
count: 3
time_window: 60
key_type: var
key: remote_addr
rejected_code: 429
policy: redis
redis_host: <your-redis-host>
redis_port: 6379
redis_database: 0
upstream:
type: roundrobin
nodes:
"<your-upstream>": 1
#END
In a test with two APISIX 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-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Redis connection options
The plugin's Redis settings are redis_host, redis_port (default 6379), redis_username,
redis_password, redis_database (default 0), redis_timeout (default 1000 milliseconds),
and the TLS settings redis_ssl, redis_ssl_verify, and redis_server_name. The cluster policy
uses redis_cluster_nodes and redis_cluster_name. See the
limit-count documentation for the
full list. According to that page, Redis Sentinel support needs APISIX 3.18.0 or later, which the examples on this page don't cover.
What APISIX stores in Redis
APISIX keeps one string for each route and client, with a TTL equal to the time_window:
plugin-limit-count<route-key>:<route-version>:<client-ip>
Unlike Kong and Envoy, APISIX stores the remaining quota, not a count of requests. After five
requests against a limit of 3, the value was -2.
When Redis is unavailable
By default, APISIX rejects requests with a 500 error when it can't reach Redis. In the test, with
the Redis server stopped, each request returned 500 within about 0.1 seconds. Set
allow_degradation: true on the plugin to fail open instead. With that setting, the same
requests returned 200.
Other plugins
According to the APISIX documentation, limit-req and limit-conn also accept a Redis policy
(redis or redis-cluster), and the openid-connect plugin can store sessions in Redis with
session.storage: redis. The examples on this page don't cover these.