# Redis with Kong Gateway

```json metadata
{
  "schema_version": 2,
  "title": "Redis with Kong Gateway",
  "description": "Share rate limits across Kong Gateway nodes with Redis.",
  "categories": ["docs","integrate","oss","rs","rc"],
  "group": "platform",
  "tableOfContents": {"sections":[{"id":"requirements","title":"Requirements"},{"children":[{"id":"redis-connection-options","title":"Redis connection options"}],"id":"limit-requests-with-a-redis-policy","title":"Limit requests with a Redis policy"},{"id":"what-kong-stores-in-redis","title":"What Kong stores in Redis"},{"id":"when-redis-is-unavailable","title":"When Redis is unavailable"},{"id":"kong-gateway-enterprise","title":"Kong Gateway Enterprise"},{"id":"more-information","title":"More information"}]}

,
  "codeExamples": []
}
```


[Kong Gateway](https://konghq.com/) 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](https://redis.io/docs/latest/develop/use-cases/rate-limiter) 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](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),
use [Docker](https://hub.docker.com/_/redis), or connect to
[Redis Cloud](https://redis.io/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:

```yaml
_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](https://developer.konghq.com/plugins/rate-limiting/reference/):

| Setting | Default | Notes |
|---------|---------|-------|
| `host`, `port` | none, `6379` | The Redis server. |
| `username`, `password` | none | For [ACL](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl) authentication (Redis 6.0 or later). If you don't set a password, Kong sends no `AUTH` command. |
| `database` | `0` | The [logical database](https://redis.io/docs/latest/commands/select). |
| `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-cache` plugin stores
  its cache in memory only.
- The `session` plugin 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.

## More information

- [Rate Limiting plugin](https://developer.konghq.com/plugins/rate-limiting/)
- [Kong Gateway documentation](https://developer.konghq.com/gateway/)

