Configure Redis and monitor health

Itential Platform uses Redis for inter-application messaging and shared authentication token storage and expiration.

In a standalone topology, a local Redis instance handles authentication token storage. In an highly available (HA) topology, Redis Sentinel monitors your Redis primary and replica nodes, detects failures automatically, and promotes a replica to primary when needed. Sentinel also acts as a configuration provider; clients query it for the current primary node rather than using a hardcoded address, making failover transparent to your application. Sentinel ensures that a single Redis node failure does not take down the entire platform.

The default Redis properties are sufficient for most Itential Platform installations. You only need to modify the defaults if you are configuring an HA topology or need to enable password authentication.

Core Redis properties

The core Redis properties connect by default to a Redis process running on the same server as Itential Platform. Configure a password if your Redis server requires authentication.

Property	Description
`redis_host`	The hostname or IP address of the Redis server. IPv4 and IPv6 addresses are supported.
`redis_port`	The port number for the Redis server. The default port is `6379`.
`redis_password`	The password for the Redis server. Use a reference to your secret manager rather than a plaintext value.
`redis_max_retries_per_request`	The maximum number of connection retries on a lost Redis link. The default is `20`.
`redis_max_heartbeat_write_retries`	The maximum number of write retries when Redis loses the ability to write data. The default is `20`.

Standalone Redis configuration

1 # The username to use when connecting to Redis.
2 redis_username = itential
3 
4 # The password to use when connecting to Redis.
5 redis_password = <your-password>
6 
7 # The maximum number of times to retry a request to Redis when the connection is lost.
8 redis_max_retries_per_request = 20
9 
10 # The maximum number of times to retry writing a heartbeat message to Redis from a service.
11 redis_max_heartbeat_write_retries = 20
12 
13 # The hostname of the Redis server. Not used when connecting to Redis Sentinels.
14 # redis_host = <your-redis-host>
15 
16 # The port to use when connecting to this Redis instance.
17 redis_port = 6379

Redis HA configuration

1 # The username to use when connecting to Redis.
2 redis_username = itential
3 
4 # The password to use when connecting to Redis.
5 redis_password = <your-redis-password>
6 
7 # The maximum number of times to retry a request to Redis when the connection is lost.
8 redis_max_retries_per_request = 20
9 
10 # The maximum number of times to retry writing a heartbeat message to Redis from a service.
11 redis_max_heartbeat_write_retries = 20
12 
13 # The port to use when connecting to this Redis instance.
14 redis_port = 6379
15 
16 # The username to use when authenticating with a Redis Sentinel cluster
17 redis_sentinel_username = sentineluser
18 
19 # The password to use when authenticating with a Redis Sentinel cluster
20 redis_sentinel_password = <your-sentinel-password>
21 
22 # The list of Redis Sentinel servers (hostnames and ports) to use for high availability.
23 redis_sentinels = [{"host": "<sentinel-address-01>", "port": 26379}, {"host": "<sentinel-address-02>", "port": 26379}, {"host": "<sentinel-address-03>", "port": 26379}]
24 
25 # The Redis primary name. This only has meaning when Redis is running with replication enabled.
26 # The sentinels will monitor this node and consider it down only when the sentinels agree.
27 # Note: The primary name should not include special characters other than: .-_ and no whitespaces.
28 redis_name = itentialmaster

Health monitoring

The Redis driver used by Itential Platform is based on the ioredis library, with additional parameters for platform-specific behavior.

Property	Type	Default	Description
`redis_max_retries_per_request`	Number	`20`	The maximum number of connection retries on a lost Redis link. Itential Platform shuts down when this limit is reached.
`redis_max_heartbeat_write_retries`	Number	`20`	The maximum number of write retries when Redis loses the ability to write data. Itential Platform shuts down when this limit is reached.

Connection retry behavior

When the driver detects a Redis connection problem, it immediately begins reconnection attempts using a predefined retryStrategy. The redis_max_retries_per_request property counts these reconnection attempts. When the count reaches the configured value, Itential Platform shuts down. If the connection is restored before that point, the retry counter resets.

Heartbeat write behavior

The driver also monitors Redis write availability. A heartbeat fires every 2000 ms (heartbeatInterval). When the heartbeat detects a write failure, it triggers a predefined retryHeartbeatWriteStrategy. The redis_max_heartbeat_write_retries property counts the subsequent write attempts during this strategy. When the count reaches the configured value, Itential Platform shuts down. If the heartbeat successfully writes data again before that point, the write retry counter resets.