Configure Redis - Tyk Documentation

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	Development, small deployments, or where Redis is managed externally as a single endpoint
Redis Cluster	High throughput or large datasets; data is automatically sharded across multiple nodes
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.

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.

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.

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	`sentinel_password`	`redis_sentinel_password`
Max active connections	`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:

"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:

"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:

"analytics_storage_config": {
  "type": "redis",
  "host": "redis-server",
  "port": 6379,
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_active": 500
}

Configure Redis Cluster

Redis Cluster 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 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.

When connecting to Amazon ElastiCache in cluster mode, you can use the configuration endpoint in addrs instead of listing individual nodes. The configuration endpoint handles routing automatically and supports both read and write operations.

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:

"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:

"redis_addrs": [
  "server1:6379",
  "server2:6380",
  "server3:6381"
],
"enable_cluster": true,
"redis_username": "",
"redis_password": "",
"redis_database": 0,
"redis_max_active": 4000

The enable_cluster field does not have the redis_ prefix.

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:

"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 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 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.

Do not set enable_cluster: Sentinel and Cluster are mutually exclusive modes.

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 pointing at that service address, and do not set master_name.

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:

"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:

"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:

"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:

"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.

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

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

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: general Redis problems including latency and memory
Redis Sentinel: inspecting primary and replica state, quorum, and failover
Redis Cluster: checking cluster state, node reachability, and slot distribution

​Supported Versions

​Configuration Reference

​Address Configuration

​Connection Pool

​Single Node Configuration

​Tyk Gateway

​Tyk Dashboard

​Tyk Pump

​Configure Redis Cluster

​Tyk Gateway

​Tyk Dashboard

​Tyk Pump

​Configure Redis Sentinel

​Tyk Gateway

​Tyk Dashboard

​Tyk Pump

​TLS Encryption

​Configuration Fields

​Example: Mutual TLS

​Troubleshooting

Supported Versions

Configuration Reference

Address Configuration

Connection Pool

Single Node Configuration

Tyk Gateway

Tyk Dashboard

Tyk Pump

Configure Redis Cluster

Tyk Gateway

Tyk Dashboard

Tyk Pump

Configure Redis Sentinel

Tyk Gateway

Tyk Dashboard

Tyk Pump

TLS Encryption

Configuration Fields

Example: Mutual TLS

Troubleshooting