> ## Documentation Index
> Fetch the complete documentation index at: https://tyk.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Redis

> Learn how to configure Redis for use with Tyk Gateway, Tyk Dashboard and Tyk Pump, including single-node, Redis Cluster, Redis Sentinel, TLS, and connection pool tuning.

Tyk Gateway, Tyk Dashboard and Tyk Pump all connect to Redis. The configuration approach depends on how your Redis infrastructure is deployed:

| Deployment mode                                      | When to use                                                                                               |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [Single node](/docs/nightly/#single-node-configuration)   | Development, small deployments, or where Redis is managed externally as a single endpoint                 |
| [Redis Cluster](/docs/nightly/#configure-redis-cluster)   | High throughput or large datasets; data is automatically sharded across multiple nodes                    |
| [Redis Sentinel](/docs/nightly/#configure-redis-sentinel) | High availability with automatic failover; a primary and replicas, with Sentinel nodes managing promotion |

All three modes share the same set of configuration fields. The sections below explain those fields, then show how to apply them for each mode.

<Warning>
  All Tyk components that connect to the same Redis instance must use identical Redis configuration. In a standard deployment, this means Tyk Gateway, Tyk Dashboard and Tyk Pump must all be configured consistently. In a distributed deployment, the Control Plane and each Data Plane have separate Redis instances, so their configurations are independent, but within each plane, all components must still match.
</Warning>

## Supported Versions

* Tyk 5.3 and later supports Redis 6.2.x, 7.0.x, and 7.2.x.
* Tyk 5.2.x and earlier supports Redis 6.0.x and Redis 6.2.x only.

## Configuration Reference

Tyk Gateway and Tyk Pump configure Redis inside a named object (`storage` for Tyk Gateway, `analytics_storage_config` for Tyk Pump). Tyk Dashboard uses top-level fields prefixed with `redis_`. The underlying options are equivalent.

The table below covers all common configuration fields. TLS-specific fields are covered separately in [TLS Encryption](/docs/nightly/#tls-encryption).

| Purpose                                                                                                                            | Tyk Gateway / Tyk Pump field | Tyk Dashboard field       |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------- |
| Single host address                                                                                                                | `host`                       | `redis_host`              |
| Port                                                                                                                               | `port`                       | `redis_port`              |
| Multiple hosts (Cluster or Sentinel)                                                                                               | `addrs`                      | `redis_addrs`             |
| Username                                                                                                                           | `username`                   | `redis_username`          |
| Password                                                                                                                           | `password`                   | `redis_password`          |
| Database index                                                                                                                     | `database`                   | `redis_database`          |
| Enable Cluster mode                                                                                                                | `enable_cluster`             | `enable_cluster`          |
| Sentinel primary name                                                                                                              | `master_name`                | `redis_master_name`       |
| [Sentinel password](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/#sentinel-password-only-authentication) | `sentinel_password`          | `redis_sentinel_password` |
| [Max active connections](/docs/nightly/#connection-pool)                                                                                | `optimisation_max_active`    | `redis_max_active`        |
| Connection timeout (seconds)                                                                                                       | `timeout`                    | `redis_timeout`           |

### Address Configuration

* For a single-node connection, use `host` and `port`.
* For Redis Cluster, use `addrs` with the addresses of all cluster nodes (both primary and replica).
* For Redis Sentinel, use `addrs` with the addresses of your Sentinel nodes, not the Redis data nodes directly.
* When `addrs` is set, `host` and `port` are ignored.

### Connection Pool

Each Tyk component maintains a pool of connections to Redis. Two settings control this pool: the maximum number of active connections (`optimisation_max_active`) and the connection timeout (`timeout`), after which an attempt to connect to Redis is abandoned.

The defaults (`optimisation_max_active: 500`, `timeout: 5` seconds) are suitable for most deployments. If you are running Tyk under high load and see connection pool timeouts, raise `optimisation_max_active` (or `redis_max_active` for Tyk Dashboard) incrementally until the timeouts stop. Avoid setting it excessively high, as opening too many connections can place unnecessary load on Redis. Keep `timeout` low so that failures are detected quickly rather than queuing behind slow connections.

## Single Node Configuration

Use these settings when connecting to a standalone Redis instance. This is the simplest configuration and is appropriate for development or where your Redis provider exposes a single endpoint.

### Tyk Gateway

In `tyk.conf` (or via environment variables), Redis is configured inside the `storage` block:

```json theme={null}
"storage": {
  "type": "redis",
  "host": "redis-server",
  "port": 6379,
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 500
}
```

### Tyk Dashboard

In `tyk_analytics.conf` (or via environment variables), Redis settings are top-level fields:

```json theme={null}
"redis_host": "redis-server",
"redis_port": 6379,
"redis_username": "",
"redis_password": "",
"redis_database": 0,
"redis_max_active": 500
```

### Tyk Pump

In `pump.conf` (or via environment variables), Redis is configured inside the `analytics_storage_config` block:

```json theme={null}
"analytics_storage_config": {
  "type": "redis",
  "host": "redis-server",
  "port": 6379,
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 500
}
```

## Configure Redis Cluster

[Redis Cluster](https://redis.io/technology/redis-enterprise-cluster-architecture/) automatically shards data across multiple nodes, providing horizontal scalability. It is suited to high-throughput deployments or where the dataset is too large for a single node.

Redis Cluster is not the same as a primary/replica setup. In a primary/replica setup, all nodes hold the full dataset and replicas serve as failover targets. In Redis Cluster, the dataset is split across shards, and each shard has its own primary and optional replicas.

We recommend reviewing [this tutorial](https://redis.io/tutorials/operate/redis-at-scale/scalability/) to learn more about Redis Cluster.

The key differences from a single-node configuration are:

* Set `enable_cluster` to `true`.
* Replace `host`/`port` with `addrs`, listing **all** cluster node addresses. Tyk needs visibility of the full cluster to route correctly. Do not list only the primary nodes.

<Note>
  When connecting to Amazon ElastiCache in cluster mode, you can use the [configuration endpoint](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/Endpoints.html) in `addrs` instead of listing individual nodes. The configuration endpoint handles routing automatically and supports both read and write operations.
</Note>

### Tyk Gateway

In `tyk.conf` (or via environment variables), Redis is configured inside the `storage` block. Set `enable_cluster` to `true` and list all cluster nodes under `addrs`:

```json theme={null}
"storage": {
  "type": "redis",
  "enable_cluster": true,
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 4000
}
```

### Tyk Dashboard

In `tyk_analytics.conf` (or via environment variables), Redis settings are top-level fields. Set `enable_cluster` to `true` and list all cluster nodes under `redis_addrs`:

```json theme={null}
"redis_addrs": [
  "server1:6379",
  "server2:6380",
  "server3:6381"
],
"enable_cluster": true,
"redis_username": "",
"redis_password": "",
"redis_database": 0,
"redis_max_active": 4000
```

<Note>
  The `enable_cluster` field does not have the `redis_` prefix.
</Note>

### Tyk Pump

In `pump.conf` (or via environment variables), Redis is configured inside the `analytics_storage_config` block. Set `enable_cluster` to `true` and list all cluster nodes under `addrs`:

```json theme={null}
"analytics_storage_config": {
  "type": "redis",
  "enable_cluster": true,
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 4000
}
```

## Configure Redis Sentinel

[Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) provides high availability for a primary/replica Redis setup. Sentinel nodes monitor the primary, and if it becomes unavailable they coordinate promotion of a replica to primary. No change to Tyk's configuration is required when a failover occurs.

Sentinel is the right choice when you need automatic failover but do not need the horizontal sharding that Redis Cluster provides.

We recommend reviewing [this tutorial](https://redis.io/tutorials/operate/redis-at-scale/high-availability/) to learn more about Redis Sentinel.

The key differences from a single-node configuration are:

* List your Sentinel node addresses under `addrs` (not the Redis data nodes directly).
* Set `master_name` to the name of the monitored primary, as configured in your Sentinel setup.

<Note>
  Do not set `enable_cluster`: Sentinel and Cluster are mutually exclusive modes.
</Note>

<Warning>
  When using Bitnami charts to install Redis Sentinel in Kubernetes, a Redis *service* is exposed rather than the Sentinel nodes directly. In this case, use a standard [single-node configuration](/docs/nightly/tyk-configuration-reference/redis-cluster-sentinel#single-node-configuration) pointing at that service address, and do not set `master_name`.
</Warning>

### Tyk Gateway

In `tyk.conf` (or via environment variables), Redis is configured inside the `storage` block. Point `addrs` at your Sentinel nodes and set `master_name` to the name of the monitored primary:

```json theme={null}
"storage": {
  "type": "redis",
  "addrs": [
    "sentinel1:26379",
    "sentinel2:26379",
    "sentinel3:26379"
  ],
  "master_name": "mymaster",
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 4000,
  "sentinel_password": ""
}
```

* If your Sentinel nodes require a password, set `sentinel_password`.

### Tyk Dashboard

In `tyk_analytics.conf` (or via environment variables), Redis settings are top-level fields. Point `redis_addrs` at your Sentinel nodes and set `redis_master_name` to the name of the monitored primary:

```json theme={null}
"redis_addrs": [
  "sentinel1:26379",
  "sentinel2:26379",
  "sentinel3:26379"
],
"redis_master_name": "mymaster",
"redis_username": "",
"redis_password": "",
"redis_database": 0,
"redis_max_active": 4000,
"redis_sentinel_password": ""
```

* If your Sentinel nodes require a password, set `redis_sentinel_password`.

### Tyk Pump

In `pump.conf` (or via environment variables), Redis is configured inside the `analytics_storage_config` block. Point `addrs` at your Sentinel nodes and set `master_name` to the name of the monitored primary:

```json theme={null}
"analytics_storage_config": {
  "type": "redis",
  "addrs": [
    "sentinel1:26379",
    "sentinel2:26379",
    "sentinel3:26379"
  ],
  "master_name": "mymaster",
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 4000,
  "sentinel_password": ""
}
```

* If your Sentinel nodes require a password, set `sentinel_password`.

## TLS Encryption

Redis supports TLS encryption from version 6. TLS configuration uses the same fields regardless of whether you are using single-node, Cluster, or Sentinel mode.

### Configuration Fields

TLS fields are configured inside the `storage` block for Tyk Gateway, the `analytics_storage_config` block for Tyk Pump, and as top-level fields prefixed with `redis_` for Tyk Dashboard. Note that Tyk Pump uses different field names from Tyk Gateway for most TLS settings.

| Purpose                              | Tyk Gateway field          | Tyk Pump field             | Tyk Dashboard field              |
| ------------------------------------ | -------------------------- | -------------------------- | -------------------------------- |
| Enable TLS                           | `use_ssl`                  | `use_ssl`                  | `redis_use_ssl`                  |
| Skip server certificate verification | `ssl_insecure_skip_verify` | `ssl_insecure_skip_verify` | `redis_ssl_insecure_skip_verify` |
| Certificate Authority file           | `ca_file`                  | `ssl_ca_file`              | `redis_ca_file`                  |
| Client certificate file (mTLS)       | `cert_file`                | `ssl_cert_file`            | `redis_cert_file`                |
| Client private key file (mTLS)       | `key_file`                 | `ssl_key_file`             | `redis_key_file`                 |
| Minimum TLS version                  | `tls_min_version`          | `ssl_min_version`          | `redis_tls_min_version`          |
| Maximum TLS version                  | `tls_max_version`          | `ssl_max_version`          | `redis_tls_max_version`          |

* Valid values for min/max version: `"1.0"`, `"1.1"`, `"1.2"`, `"1.3"`. Defaults: minimum `"1.2"`, maximum `"1.3"`.
* Setting `ssl_insecure_skip_verify` to `true` is not recommended for production.

### Example: Mutual TLS

The following example configures Tyk Gateway to use mutual TLS (mTLS) when connecting to Redis:

```json theme={null}
"storage": {
  "use_ssl": true,
  "ca_file": "/path/to/ca.crt",
  "cert_file": "/path/to/client.crt",
  "key_file": "/path/to/client.key"
}
```

* TLS is enabled with `use_ssl`.
* The Redis server's certificate is verified against the provided CA with `ca_file`.
* Tyk Gateway's client certificate (`cert_file`) and private key (`key_file`) are used to satisfy Redis's client authentication requirement.

For Tyk Dashboard, the equivalent fields are prefixed with `redis_` (for example, `redis_use_ssl`, `redis_ca_file`). For Tyk Pump, these fields sit inside the `analytics_storage_config` block, but use different field names: for example, `ssl_ca_file` instead of `ca_file`. See the table above for the full field mapping.

For background on TLS and mTLS concepts, see [TLS and Certificate Management](/docs/nightly/api-management/certificates).

## Troubleshooting

Before adjusting Tyk configuration, verify that Redis itself is healthy. The commands below help diagnose problems across all deployment modes.

**Check Redis Is Reachable**

```bash theme={null}
redis-cli -h <host> -p <port> PING
```

A healthy Redis instance responds with `PONG`. If this fails, the connection problem is at the network or Redis level, not in Tyk configuration.

**Monitor Key Redis Metrics**

```bash theme={null}
redis-cli -h <host> -p <port> INFO
```

Watch the following metrics:

| Metric                      | Section   | What to look for                                                              |
| --------------------------- | --------- | ----------------------------------------------------------------------------- |
| `connected_clients`         | `clients` | Approaching the `maxclients` limit                                            |
| `blocked_clients`           | `clients` | Non-zero values indicate connection pool pressure                             |
| `rejected_connections`      | `stats`   | Any value above 0 means clients were refused. Set up alerting on this metric. |
| `instantaneous_ops_per_sec` | `stats`   | Sudden drops may indicate a problem with the Redis instance                   |
| `used_memory_rss`           | `memory`  | Growing unboundedly suggests a key eviction or retention issue                |

For further troubleshooting guidance, see the Redis documentation:

* [Troubleshooting Redis](https://redis.io/docs/latest/operate/oss_and_stack/management/troubleshooting/): general Redis problems including latency and memory
* [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/): inspecting primary and replica state, quorum, and failover
* [Redis Cluster](https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/): checking cluster state, node reachability, and slot distribution