Redis Architecture in KubeBlocks

The Redis ClusterDefinition exposes three patterns. They differ by topology name and whether Redis Sentinel is deployed:

Standalone architecture

Use topology: standalone when you want a single Redis Component and do not provision Sentinel.

Cluster  →  Component (redis)  →  InstanceSet  →  Pod × N

• There is no redis-sentinel Component and no Sentinel quorum — the monitoring and failover flow in the Sentinel architecture section does not apply.
• Pod layout (Redis server + metrics sidecar, PVC per data pod) matches the Redis data pods description under Sentinel below.
• For HA with automatic failover on a single shard, use replication (or replication-twemproxy with Twemproxy), not standalone.

Sentinel architecture

Redis Sentinel uses a dedicated set of Sentinel processes to monitor the Redis primary, detect failures, and coordinate automatic failover. All data lives on a single primary; replicas serve as hot standbys and optional read targets.

Resource Hierarchy

KubeBlocks models a Redis Sentinel deployment as a hierarchy of Kubernetes custom resources:

Cluster  →  Component (redis)          →  InstanceSet  →  Pod × N
         →  Component (redis-sentinel)  →  InstanceSet  →  Pod × 3

At least 3 Sentinel pods are required to form a voting quorum. The ClusterDefinition provisions redis-sentinel before redis (sentinel must be ready before data pods register with it).

Containers Inside Each Pod

Redis Data Pods

Each Redis data pod runs two main containers (plus an init-dbctl init container that copies dbctl into /tools/ for use by the roleProbe):

Each data pod mounts its own PVC for the Redis data directory, preserving RDB/AOF files across restarts.

Redis Sentinel Pods

Each Sentinel pod mounts its own PVC (needSnapshot: true) for the Sentinel data directory, preserving Sentinel configuration across restarts.

High Availability via Redis Sentinel

Traffic Routing

• Write traffic: connect to {cluster}-redis-redis:6379 (always routes to the current primary)
• Sentinel queries (for client-side Sentinel discovery): connect to {cluster}-redis-sentinel-redis-sentinel:26379

Automatic Failover

1. Primary stops responding — Sentinels detect missing pings within down-after-milliseconds (default 20 s)
2. Quorum agreement (ODOWN) — the configured quorum of Sentinels agree the primary is objectively down
3. Sentinel leader election — Sentinels elect one of themselves as the failover coordinator
4. Replica selection — the coordinator picks the replica with the smallest replication lag
5. Promotion — the coordinator sends REPLICAOF NO ONE to the chosen replica
6. Reconfiguration — other replicas and Sentinels update their configuration to the new primary
7. Pod label updated — kubeblocks.io/role=primary applied to the new primary pod
8. Service Endpoints switch — the ClusterIP service automatically routes traffic to the new primary

Total failover time is typically 10–30 seconds.

Redis Cluster Architecture

Redis Cluster (also called sharding mode) distributes data across multiple independent shards using hash-slot-based partitioning. Each shard is an independent KubeBlocks Sharding component with its own primary and replicas. There are no Sentinel processes — nodes coordinate through a gossip protocol on the cluster bus.

Resource Hierarchy

Redis Cluster uses the KubeBlocks Sharding abstraction, which is different from the standard Component-based hierarchy:

Cluster  →  Sharding  →  Shard × N  →  InstanceSet  →  Pod × replicas

A minimum of 3 shards is required for Redis Cluster to achieve quorum. Each shard tolerates 1 pod failure when at least 1 replica is configured.

Containers Inside Each Pod

Every Redis Cluster pod runs two main containers (plus an init-dbctl init container that copies dbctl into /tools/ for use by the roleProbe):

Each pod mounts its own PVC for the Redis data directory.

Hash Slot Distribution

Redis Cluster divides the key space into 16384 hash slots. Each key is assigned to a slot via CRC16(key) mod 16384. Slots are distributed evenly across shards at cluster creation:

When shards are added or removed, KubeBlocks triggers a slot rebalancing operation to redistribute slots across the new shard count. After rebalancing, each shard may hold multiple non-contiguous slot ranges rather than a single interval.

High Availability via Gossip Protocol

Redis Cluster nodes use a peer-to-peer gossip protocol over port 16379 (cluster bus) for failure detection and topology propagation — no external coordinator is needed:

Traffic Routing

Redis Cluster does not use a standard ClusterIP service for write routing. Instead, a cluster-aware client fetches the slot map directly from the cluster:

1. The client connects to any cluster node on port 6379
2. It issues CLUSTER SLOTS (or CLUSTER SHARDS) to retrieve the full slot-to-node mapping
3. The client routes each command directly to the shard primary owning the key's slot
4. On a MOVED or ASK response, the client updates its routing table and retries

For external access, per-pod NodePort or LoadBalancer services (redis-advertised) can be enabled to expose each pod's advertised address.

Automatic Failover

1. Shard primary stops responding — peers detect missing gossip heartbeats
2. PFAIL declared — nodes that cannot reach the primary mark it as PFAIL
3. FAIL declared — a majority of other primaries agree → FAIL state propagated cluster-wide
4. Replica election — the shard replica requests votes from other primaries; majority vote promotes it
5. Slot ownership transferred — cluster topology updated with the new primary for the affected slots
6. Pod label updated — kubeblocks.io/role=primary applied by KubeBlocks
7. Clients follow MOVED — cluster-aware clients refresh their routing table automatically

System Accounts

KubeBlocks manages the following Redis account for all topology patterns on this page (standalone, Sentinel, and Redis Cluster). The password is auto-generated and stored in a Secret named {cluster}-{component}-account-default.