Understanding Epochs in Redis Cluster: currentEpoch and configEpoch

Redis Cluster uses a concept called "epoch" (similar to the term in Raft) to assign incremental version numbers to events.

There are two kinds of epochs: currentEpoch and configEpoch .

currentEpoch is an unsigned 64‑bit integer that starts at 0 for all nodes when the cluster is created. When a node receives a packet with a higher currentEpoch, it updates its own value, and eventually all nodes converge to the same currentEpoch, indicating a consistent cluster state.

configEpoch is used for configuration versioning and conflict management. Each master node has a unique configEpoch. When the cluster configuration changes (e.g., failover, slot migration), configEpoch helps determine which node holds the latest configuration. A newly joined node starts with configEpoch 0; during a failover the promoted master receives a configEpoch equal to the current maximum plus one, and it can also be set manually with the set-config-config-epoch command.

All masters in the cluster hold distinct configEpoch values, and a master‑slave pair shares the same configEpoch.

Whenever configEpoch or currentEpoch changes, the new values are written to the nodes.conf file and persisted to disk with an fsync.

Example output of cluster nodes on a three‑master, three‑slave cluster shows ports 7000‑7004, 7001‑7005, and 7002‑7003, with configEpoch values 1, 2, and 3 respectively:

459 c1d9982b60cbab1f7b4a32862107f16edb0fa 127.0.0.1:7005@17005 slave bd8594069bdcfee1708e3fc758e2cef36e14e130 0 1745740700562 2 connected
3 df217b7de09dc9bb4569d571faed81c0ba2bdf0 127.0.0.1:7004@17004 slave ea4dc03dfa7db0d084563729866c3ef3bd65d030 0 1745740699599 1 connected
ea4dc03dfa7db0d084563729866c3ef3bd65d030 127.0.0.1:7000@17000 myself,master - 0 1745740698000 1 connected 0-5460
 a929d862550ca2fa3a24172685db876d57fd1b72 127.0.0.1:7003@17003 slave 3e7d39948f9b6a29d74f1c8dfa43e80d7c1edb46 0 1745740699493 3 connected
bd8594069bdcfee1708e3fc758e2cef36e14e130 127.0.0.1:7001@17001 master - 0 1745740698434 2 connected 5461-10922
3e7d39948f9b6a29d74f1c8dfa43e80d7c1edb46 127.0.0.1:7002@17002 master - 0 1745740700562 3 connected 10923-16383

The above information demonstrates a three‑master, three‑slave cluster where each master‑slave pair has its own configEpoch.

The nodes.conf file records the currentEpoch values, and the cluster info command can also display epoch information (as shown in the accompanying screenshots).

In summary, epochs in Redis Cluster provide a mechanism for versioning cluster state and configuration, ensuring consistency and aiding conflict resolution during topology changes.