Cluster & High Availability

Valkey provides two HA solutions: Master-Replica + Sentinel for automatic failover, and Cluster for horizontal data sharding.

Master-Replica Replication

Replication is the foundation of Valkey HA. The master node handles writes, while replica nodes sync data and serve reads.

confCopy

# Replica configuration
replicaof 192.168.1.100 6379

# Master password (if requirepass is set)
masterauth your-master-password

# Whether replica is writable (default: no)
replica-read-only yes

# Serve reads when disconnected from master
replica-serve-stale-data yes

Replication proceeds in two phases:

Full Sync: On first connection, the master generates an RDB snapshot and sends it to the replica, buffering write commands during the process
Partial Resync: Based on replication offset, the master propagates new write commands to the replica in real-time (PSYNC)

Sentinel

Sentinel is a distributed system that monitors Valkey instances and performs automatic failover when the master goes down.

confCopy

# sentinel.conf

# Monitor master named mymaster with quorum of 2
sentinel monitor mymaster 192.168.1.100 6379 2

# Master password
sentinel auth-pass mymaster your-password

# Consider master down after 15s no response
sentinel down-after-milliseconds mymaster 15000

# Failover timeout
sentinel failover-timeout mymaster 60000

# Max replicas to sync during failover
sentinel parallel-syncs mymaster 1

Deployment Tip: Deploy at least 3 Sentinel nodes on different physical machines or availability zones. Set quorum to ceil(node_count/2) + 1 to avoid split-brain.

Cluster

Valkey Cluster is the native distributed solution, distributing data across multiple nodes via hash slots. There are 16384 slots total, with each master handling a subset.

Creating a Cluster

bashCopy

# Minimum 3 masters + 3 replicas (6 nodes)
valkey-cli --cluster create \
  192.168.1.10:6379 \
  192.168.1.11:6379 \
  192.168.1.12:6379 \
  192.168.1.13:6379 \
  192.168.1.14:6379 \
  192.168.1.15:6379 \
  --cluster-replicas 1

Key Configuration

confCopy

# Enable cluster mode
cluster-enabled yes

# Cluster config file (auto-managed, do not edit manually)
cluster-config-file nodes.conf

# Node timeout for failure detection
cluster-node-timeout 15000

# Allow serving when some slots are unavailable
cluster-require-full-coverage no

Cluster Operations

valkeyCopy

# View cluster info
CLUSTER INFO
CLUSTER NODES

# Add a new node
valkey-cli --cluster add-node 192.168.1.16:6379 192.168.1.10:6379

# Reshard slots
valkey-cli --cluster reshard 192.168.1.10:6379

# Check cluster health
valkey-cli --cluster check 192.168.1.10:6379

Solution Comparison

Choosing the right solution depends on your requirements:

Single Instance: Dev/test environments, or small datasets where brief downtime is acceptable
Master-Replica + Sentinel: Data fits in a single machine's memory, need automatic failover and read/write separation
Cluster: Data exceeds single machine memory, need horizontal scaling for throughput and storage

Cross-Slot Restriction: In Cluster mode, multi-key operations (e.g., MGET, MSET) require all keys in the same slot. Use Hash Tags to force related keys into the same slot: SET user:{1001}:name "John".

Configuration