Configure Redis Cluster and Sentinel

Configure Redis Cluster

Our Gateway, Dashboard and Pump all support integration with Redis Cluster. Redis Cluster allows data to be automatically sharded across multiple Redis Nodes. To setup Redis Cluster correctly, we recommend you read the Redis Cluster Tutorial. You must use the same settings across the Gateway, Dashboard and Pump.

Redis Cluster operates differently from a Redis setup where one instance serves as the primary and others as replicas.

Supported Versions

Tyk 5.3 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.

Redis Cluster and Tyk Gateway

To configure the Tyk Gateway to work with your Redis Cluster, set enable_cluster to true and list your servers under addrs in your tyk.conf file.

addrs is new in v2.9.3, and replaces hosts which is now deprecated.

If you are using TLS for Redis connections, set use_ssl to true.

"storage": {
  "type": "redis",
  "enable_cluster": true,
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_idle": 2000,
  "optimisation_max_active": 4000,
  "use_ssl": false
},

Redis Cluster and Tyk Dashboard

redis_addrs is new in v1.9.3 for the Dashboard, and replaces hosts which is now deprecated.

"redis_addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
"redis_use_ssl": true,
"enable_cluster": true

To configure the Tyk Dashboard to work with your Redis Cluster, add the Redis address information to your tyk_analytics.conf file:

Redis Cluster and Tyk Pump

To configure the Tyk Pump to work with your Redis Cluster, set enable_cluster to true and list your servers under addrs in your pump.conf file.

addrs is new in v2.9.3, and replaces hosts which is now deprecated.

"analytics_storage_config": {
  "type": "redis",
  "enable_cluster": true,
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_idle": 100,
  "use_ssl": false
},

Redis Cluster with Docker

For Redis clustered mode to work with Tyk using Docker and Amazon ElastiCache, follow these two steps:

Make sure cluster mode is enabled

Set the environment variable TYK_GW_STORAGE_ENABLECLUSTER to true.

Add all cluster endpoints to the config

Add all the Redis Cluster endpoints into Tyk, not just the primary. If Tyk can’t see the whole cluster, then it will not work. For ElastiCache Redis, you can bypass having to list all your nodes, and instead just use the configuration endpoint, this allows read and write operations and the endpoint will determine the correct node to target. If this does not work, you can still list out the hosts using an environment variable. To do so, set the environment variable:

TYK_GW_STORAGE_ADDRS="redis_primary1:port,redis_replica1:port,redis_primary2:port,redis_replica2:port,redis_primary3:port,redis_replica3:port"

It is important that Tyk can connect to all primary and replica instances. It is recommended to ensure that the connection pool is big enough. To do so, set the following environment variables:

TYK_GW_STORAGE_MAXIDLE=6000
TYK_GW_STORAGE_MAXACTIVE=10000

These are suggested settings, please verify them by load testing.

Redis Cluster with TLS

If you are using TLS for Redis connections, set use_ssl to true for Gateway and Pump, and redis_use_ssl to true for the dashboard. Redis supports SSL/TLS encryption from version 6 as an optional feature, enhancing the security of data in transit. Similarly, Amazon ElastiCache offers encryption in transit and at rest. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk’s configuration files:

storage.use_ssl: Set this to true to enable TLS encryption for the connection.
storage.ssl_insecure_skip_verify: A flag that, when set to true, instructs the application not to verify the Redis server’s TLS certificate. This is not recommended for production due to the risk of man-in-the-middle attacks.

From Tyk 5.3, additional options are available for more granular control:

storage.ca_file: Path to the Certificate Authority (CA) file for verifying the Redis server’s certificate.
storage.cert_file and storage.key_file: Paths to your application’s certificate and private key files, necessary for mTLS where both parties verify each other’s identity.
storage.max_version and storage.min_version: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3).

Setting up an Insecure TLS Connection

Enable TLS: By setting "use_ssl": true, you encrypt the connection.
Skip Certificate Verification: Setting "ssl_insecure_skip_verify": true bypasses the server’s certificate verification, suitable only for non-production environments.

Setting up a Secure TLS Connection

Ensure use_ssl is set to true.
Set ssl_insecure_skip_verify to false to enforce certificate verification against the CA specified in ca_file.
Specify the path to the CA file in ca_file for server certificate verification.
Adjust min_version and max_version to secure TLS versions, ideally 1.2 and 1.3.

Setting up a Mutual TLS (mTLS) Connection

Follow the steps for a secure TLS connection.
Provide paths for cert_file and key_file for your application’s TLS certificate and private key, enabling Redis server to verify your application’s identity.

Example Gateway Configuration

"storage": {
  "type": "redis",
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "use_ssl": true,
  "ssl_insecure_skip_verify": false,
  "ca_file": "/path/to/ca.crt",
  "cert_file": "/path/to/client.crt",
  "key_file": "/path/to/client.key",
  "max_version": "1.3",
  "min_version": "1.2",
  "enable_cluster": true,
  "optimisation_max_idle": 2000,
  "optimisation_max_active": 4000
}

Troubleshooting Redis Cluster

If you find that Tyk components fail to initialise when using Redis clustering, for example the application does not start and the last log file entry shows a message such as Using clustered mode, try setting the environment variable REDIGOCLUSTER_SHARDCOUNT to 128 on all hosts which connect to the Redis Cluster i.e. Gateway, Dashboard, Pump, MDCB. E.g. REDIGOCLUSTER_SHARDCOUNT=128 If setting to 128 does not resolve the issue, try 256 instead.

Configure Redis Sentinel

From v2.9.3 Redis Sentinel is supported. Similar to Redis Cluster, our Gateway, Dashboard and Pump all support integration with Redis Sentinel. To configure Tyk to work with Redis Sentinel, list your servers under addrs and set the master name in your Gateway, Dashboard, Pump and MDCB config. Unlike Redis Cluster, enable_cluster should not be set. Indicative config snippets as follows:

Supported Versions

Tyk 5.3 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.

Redis Sentinel and Gateway

"storage": {
  "type": "redis",
  "addrs": [
    "server1:26379",
    "server2:26379",
    "server3:26379"
  ],
  "master_name": "mymaster",
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_idle": 2000,
  "optimisation_max_active": 4000,
  "use_ssl": false
},

Redis Sentinel and Dashboard

"redis_addrs": [
  "server1:26379",
  "server2:26379",
  "server3:26379"
],
"redis_master_name": "mymaster"

Redis Sentinel and Pump

"analytics_storage_config": {
  "type": "redis",
  "addrs": [
    "server1:26379",
    "server2:26379",
    "server3:26379"
  ],
  "master_name": "mymaster",
  "username": "",
  "password": "",
  "database": 0,
  "optimisation_max_idle": 100,
  "use_ssl": false
},

When using Bitnami charts to install Redis Sentinel in k8s, a Redis service is exposed, which means that standard Redis config is required instead of the above setup, i.e. a single server in addrs and master_name is not required.

Support for Redis Sentinel AUTH

To support the use of Redis Sentinel AUTH (introduced in Redis 5.0.1) we have added the following global config settings in Tyk v3.0.2:

In the Tyk Gateway config file - sentinel_password
In the Tyk Dashboard config file - redis_sentinel_password
In the Tyk Pump config file - sentinel_password
In the Tyk Identity Broker config file - SentinelPassword
In the Tyk Synk config file - sentinel_password

These settings allow you to support Sentinel password-only authentication in Redis version 5.0.1 and above. See the Redis and Sentinel authentication section of the Redis Sentinel docs for more details.

Configuring Both Sentinel and Master Redis Passwords

When your Redis Sentinel deployment uses authentication for both the Sentinel nodes and the master Redis instance, you must configure both passwords in your Tyk configuration:

Sentinel password (sentinel_password or redis_sentinel_password): Used to authenticate with the Redis Sentinel nodes
Master Redis password (password or redis_password): Used to authenticate with the master Redis instance after Sentinel provides its address

If you only configure the sentinel_password but your master Redis instance also requires authentication, Tyk will successfully connect to Sentinel but fail to authenticate with the master Redis instance. Make sure to configure both passwords when both are required.

Gateway Configuration Example (with both passwords)

"storage": {
  "type": "redis",
  "addrs": [
    "sentinel1:26379",
    "sentinel2:26379",
    "sentinel3:26379"
  ],
  "master_name": "mymaster",
  "sentinel_password": "your-sentinel-password",
  "username": "",
  "password": "your-master-redis-password",
  "database": 0,
  "optimisation_max_idle": 2000,
  "optimisation_max_active": 4000,
  "use_ssl": false
}

Field	Environment Variable	Description
`sentinel_password`	`TYK_GW_STORAGE_SENTINELPASSWORD`	Password for authenticating with Redis Sentinel nodes
`password`	`TYK_GW_STORAGE_PASSWORD`	Password for authenticating with the master Redis instance

Dashboard Configuration Example (with both passwords)

"redis_addrs": [
  "sentinel1:26379",
  "sentinel2:26379",
  "sentinel3:26379"
],
"redis_master_name": "mymaster",
"redis_sentinel_password": "your-sentinel-password",
"redis_password": "your-master-redis-password"

Field	Environment Variable	Description
`redis_sentinel_password`	`TYK_DB_REDISSENTINELPASSWORD`	Password for authenticating with Redis Sentinel nodes
`redis_password`	`TYK_DB_REDISPASSWORD`	Password for authenticating with the master Redis instance

Pump Configuration Example (with both passwords)

"analytics_storage_config": {
  "type": "redis",
  "addrs": [
    "sentinel1:26379",
    "sentinel2:26379",
    "sentinel3:26379"
  ],
  "master_name": "mymaster",
  "sentinel_password": "your-sentinel-password",
  "username": "",
  "password": "your-master-redis-password",
  "database": 0,
  "optimisation_max_idle": 100,
  "use_ssl": false
}

Field	Environment Variable	Description
`sentinel_password`	`TYK_PMP_ANALYTICSSTORAGECONFIG_SENTINELPASSWORD`	Password for authenticating with Redis Sentinel nodes
`password`	`TYK_PMP_ANALYTICSSTORAGECONFIG_PASSWORD`	Password for authenticating with the master Redis instance

Configure Redis TLS Encryption

Redis supports SSL/TLS encryption from version 6 as an optional feature, enhancing the security of data in transit. To configure TLS or mTLS connections between an application and Redis, consider the following settings in Tyk’s configuration files:

storage.use_ssl: Set this to true to enable TLS encryption for the connection.
storage.ssl_insecure_skip_verify: A flag that, when set to true, instructs the application not to verify the Redis server’s TLS certificate. This is not recommended for production due to the risk of man-in-the-middle attacks.

From Tyk 5.3, additional options are available for more granular control:

storage.ca_file: Path to the Certificate Authority (CA) file for verifying the Redis server’s certificate.
storage.cert_file and storage.key_file: Paths to your application’s certificate and private key files, necessary for mTLS where both parties verify each other’s identity.
storage.max_version and storage.min_version: Define the acceptable range of TLS versions, enhancing security by restricting connections to secure TLS protocols (1.2 or 1.3).

Setting up an Insecure TLS Connection

Enable TLS: By setting "use_ssl": true, you encrypt the connection.
Skip Certificate Verification: Setting "ssl_insecure_skip_verify": true bypasses the server’s certificate verification, suitable only for non-production environments.

Setting up a Secure TLS Connection

Ensure use_ssl is set to true.
Set ssl_insecure_skip_verify to false to enforce certificate verification against the CA specified in ca_file.
Specify the path to the CA file in ca_file for server certificate verification.
Adjust min_version and max_version to secure TLS versions, ideally 1.2 and 1.3.

Setting up a Mutual TLS (mTLS) Connection

Follow the steps for a secure TLS connection.
Provide paths for cert_file and key_file for your application’s TLS certificate and private key, enabling Redis server to verify your application’s identity.

Example Gateway Configuration

"storage": {
  "type": "redis",
  "addrs": [
    "server1:6379",
    "server2:6380",
    "server3:6381"
  ],
  "use_ssl": true,
  "ssl_insecure_skip_verify": false,
  "ca_file": "/path/to/ca.crt",
  "cert_file": "/path/to/client.crt",
  "key_file": "/path/to/client.key",
  "max_version": "1.3",
  "min_version": "1.2",
  "optimisation_max_idle": 2000,
  "optimisation_max_active": 4000
}

Overview

Getting Started

Deploy Tyk

Managing APIs

Security in Tyk

Reference

Developer Support

Configure Redis Cluster and Sentinel