Redis Sentinel

Redis Sentinel is the built-in high availability solution for Redis. It watches your Redis instances and automatically promotes a replica to primary when the primary becomes unavailable.

What Sentinel does

Sentinel handles three responsibilities:

• Monitoring. Each Sentinel process continuously checks whether your Redis primary and replicas are responding.
• Notification. When something goes wrong, Sentinel can alert system administrators or other programs via the pub/sub API.
• Automatic failover. When the primary is unreachable for longer than a configured threshold, Sentinel coordinates with other Sentinel instances, elects a new primary from the available replicas, and reconfigures the remaining replicas to follow the new primary.

Clients that support Sentinel discovery ask Sentinel for the current primary address rather than hardcoding it. When failover happens, the client learns the new address automatically.

Sentinel vs. Cluster

Redis Sentinel and Redis Cluster solve different problems.

Sentinel provides high availability for a single dataset. You have one primary that accepts writes, one or more replicas for read scaling, and Sentinel managing failover. All the data lives on a single node.

Cluster spreads your dataset across multiple shards and provides both horizontal scaling and HA within each shard. Use Cluster when your dataset is too large for one node or when write throughput exceeds what a single primary can handle.

For most applications, Sentinel is the simpler choice. Use Cluster only when you need data sharding.

Minimum setup: why three Sentinels

You need at least three Sentinel instances for a production-grade setup. Sentinel uses a quorum to decide when failover should happen: a minimum number of Sentinels must agree that the primary is down before any action is taken.

With only two Sentinels, a network partition between them leaves both unable to reach quorum, preventing any failover. Three Sentinels means two can agree even if one is isolated, which avoids split-brain scenarios where two nodes both believe they are primary.

Run each Sentinel on a separate machine or availability zone.

Basic configuration

Create a sentinel.conf file for each Sentinel instance. A minimal configuration looks like this:

# sentinel.conf

# Tell Sentinel to monitor a primary named "mymaster" at the given address.
# The final number (2) is the quorum: how many Sentinels must agree
# before declaring the primary down.
sentinel monitor mymaster 127.0.0.1 6379 2

# How long (ms) the primary must be unreachable before Sentinel considers
# it subjectively down (SDOWN).
sentinel down-after-milliseconds mymaster 5000

# How long (ms) Sentinel will wait for a failover to complete before
# declaring it failed and allowing another Sentinel to try.
sentinel failover-timeout mymaster 60000

# How many replicas can sync with the new primary at the same time
# during failover. Set to 1 to keep at least one replica available
# for reads during the sync.
sentinel parallel-syncs mymaster 1

Each Sentinel in your cluster should point to the same primary. They discover each other and the replicas automatically by communicating via the primary.

Starting Sentinel

You can start Sentinel two ways:

# Using the redis-sentinel binary
redis-sentinel /path/to/sentinel.conf

# Using redis-server with the --sentinel flag
redis-server /path/to/sentinel.conf --sentinel

Sentinel listens on port 26379 by default. You can change it with port 26380 in the config file.

Querying Sentinel

Connect to a Sentinel instance with redis-cli:

redis-cli -p 26379

Useful commands once connected:

# List all monitored primaries
SENTINEL masters

# List replicas for a specific primary
SENTINEL replicas mymaster

# Get the current primary address (what your app should use)
SENTINEL get-master-addr-by-name mymaster

SENTINEL get-master-addr-by-name returns the IP and port of the current primary. This is the same lookup your application client performs when Sentinel support is enabled.

Sample output:

1) "127.0.0.1"
2) "6379"

Connecting from an application

Clients that support Sentinel connect to one or more Sentinel addresses at startup and ask for the current primary. They also subscribe to Sentinel notifications so they learn about failovers as they happen.

Python (redis-py)

from redis.sentinel import Sentinel

sentinel = Sentinel(
    [("sentinel1.example.com", 26379),
     ("sentinel2.example.com", 26379),
     ("sentinel3.example.com", 26379)],
    socket_timeout=0.5
)

# Get a client that always points to the current primary
primary = sentinel.master_for("mymaster", socket_timeout=0.5)

# Get a client for read-only replica queries
replica = sentinel.slave_for("mymaster", socket_timeout=0.5)

primary.set("key", "value")
print(primary.get("key"))

Node.js (ioredis)

const Redis = require("ioredis");

const client = new Redis({
  sentinels: [
    { host: "sentinel1.example.com", port: 26379 },
    { host: "sentinel2.example.com", port: 26379 },
    { host: "sentinel3.example.com", port: 26379 },
  ],
  name: "mymaster",
});

await client.set("key", "value");
console.log(await client.get("key"));

Both clients will reconnect to the new primary automatically after a failover.

Failover process

When the primary stops responding, Sentinel follows this sequence:

1. A Sentinel marks the primary as subjectively down (SDOWN) after down-after-milliseconds passes.
2. That Sentinel asks the others whether they also see the primary as down.
3. Once enough Sentinels agree (quorum reached), the primary is marked objectively down (ODOWN).
4. The Sentinels elect a leader among themselves to carry out the failover.
5. The leader chooses the most up-to-date replica as the new primary and sends it REPLICAOF NO ONE.
6. The other replicas are reconfigured to follow the new primary.
7. Sentinel updates its own config and notifies clients.

Total failover time is typically down-after-milliseconds plus a few seconds for coordination and sync. With a down-after-milliseconds of 5000, expect 10 to 30 seconds of write downtime in normal conditions.

Authentication

Protecting Redis instances

Add requirepass to your Redis instance config:

requirepass your-redis-password

Then tell Sentinel the password so it can connect:

sentinel auth-pass mymaster your-redis-password

Protecting Sentinel itself

To require authentication for Sentinel connections, add to sentinel.conf:

requirepass your-sentinel-password

Clients connecting to Sentinel will then need to authenticate. Make sure all Sentinel instances share the same password if you enable this.

Common issues

SDOWN vs. ODOWN. SDOWN (subjectively down) means one Sentinel thinks the primary is unreachable. ODOWN (objectively down) means enough Sentinels agree to trigger failover. If you see SDOWN but not ODOWN, either your quorum number is too high or other Sentinels cannot reach the primary from their location.

Quorum not reached. If fewer Sentinels than the quorum value are running, failover is blocked. This is by design: it prevents false positives. Check that all Sentinel processes are running and can communicate with each other.

Clients without Sentinel support. Some older Redis clients only accept a static host and port. These clients will not reconnect to the new primary after failover. Replace them with a client that supports Sentinel, or put a proxy (such as Twemproxy or Envoy) in front of Redis.

Clock skew. Sentinel uses timeouts for failure detection. If system clocks on your Sentinel hosts are significantly out of sync, you may see erratic SDOWN/ODOWN transitions. Keep clocks synced with NTP.

Quick reference

Key sentinel.conf directives

Sentinel CLI commands