Redis High Availability Architecture in KubeBlocks

This page describes how KubeBlocks deploys a Redis Sentinel cluster on Kubernetes — covering the resource hierarchy, pod internals for both data and Sentinel pods, Sentinel-based HA, traffic routing, and automatic failover.

Resource Hierarchy

KubeBlocks models a Redis cluster as a hierarchy of Kubernetes custom resources:

Cluster  →  Component  →  InstanceSet  →  Pod × N

Resource	Role
Cluster	User-facing declaration — specifies topology, replica count, storage size, and resources
Component	Generated automatically; one Component for Redis data pods and one for Sentinel pods; each references its own `ComponentDefinition`
InstanceSet	KubeBlocks custom workload (replaces `StatefulSet`); manages pods with stable identities and role awareness
Pod	Actual running Redis or Sentinel process; each pod gets a unique ordinal and (for data pods) its own PVC

A Redis Sentinel deployment consists of two KubeBlocks Components within the same Cluster: the Redis data component (primary + replicas) and the Redis Sentinel component (monitoring processes). At least 3 Sentinel pods are required to form a quorum.

Containers Inside Each Pod

Redis Data Pods

Container	Port	Purpose
`redis`	6379 (Redis protocol)	Redis data server; the primary accepts writes and replicates to secondaries via async replication
`kbagent`	5001	Role probe endpoint — KubeBlocks queries `GET /v1.0/getrole` every second to identify primary vs. replica
`metrics-exporter`	9187	Prometheus metrics exporter

Each data pod mounts its own PVC for the Redis data directory (/data), preserving RDB snapshots and AOF logs across pod restarts.

Redis Sentinel Pods

Container	Port	Purpose
`sentinel`	26379 (Sentinel protocol)	Redis Sentinel process that monitors the Redis primary, detects failures, and coordinates failover
`kbagent`	5001	Health probe endpoint

Sentinel pods use an emptyDir for their working directory — Sentinel configuration is rebuilt on restart from the current cluster state.

High Availability via Redis Sentinel

Redis Sentinel is a distributed monitoring and automatic failover system for Redis:

Sentinel Concept	Description
Monitoring	Each Sentinel continuously pings the Redis primary and all replicas to detect failures
Subjective down (SDOWN)	A Sentinel marks a node as subjectively down when it fails to respond within `down-after-milliseconds`
Objective down (ODOWN)	A primary is declared objectively down when a quorum of Sentinels agree it is unreachable
Leader election	Sentinels elect one of themselves as the failover coordinator using a Raft-based voting process
Failover	The elected Sentinel promotes the most up-to-date replica to primary and reconfigures other replicas to follow the new primary
Quorum	Typically `(N/2 + 1)` Sentinels must agree to trigger a failover; 3 Sentinels require 2 to agree

Traffic Routing

KubeBlocks creates services for both the Redis data component and the Sentinel component:

Service	Type	Port	Selector
`{cluster}-redis`	ClusterIP	6379	`kubeblocks.io/role=primary`
`{cluster}-redis-headless`	Headless	6379	all Redis data pods
`{cluster}-redis-sentinel`	ClusterIP	26379	all Sentinel pods
`{cluster}-redis-sentinel-headless`	Headless	26379	all Sentinel pods

The key mechanism is roleSelector: primary on the Redis ClusterIP service. KubeBlocks probes each data pod via kbagent every second and updates the pod label kubeblocks.io/role. The service Endpoints always point at the current primary — no VIP or external load balancer required.

Write traffic: connect to {cluster}-redis:6379
Replica access (read scaling): use the headless service DNS {pod-name}.{cluster}-redis-headless.{namespace}.svc.cluster.local:6379
Sentinel queries (for client-side Sentinel discovery): connect to {cluster}-redis-sentinel:26379

Automatic Failover

When the Redis primary pod fails, the following sequence restores write access automatically:

Primary stops responding — Sentinels detect the missing ping responses within down-after-milliseconds (default 5 s)
Quorum agreement (ODOWN) — the configured quorum of Sentinels agree the primary is objectively down
Sentinel leader election — Sentinels elect one of themselves as the failover coordinator
Replica selection — the coordinator chooses the replica with the smallest replication lag (most up-to-date)
Promotion — the coordinator sends SLAVEOF NO ONE to the chosen replica, making it the new primary
Reconfiguration — other replicas and Sentinels are informed of the new primary and update their configuration
KubeBlocks detects role change — kbagent returns primary for the new winner; the kubeblocks.io/role=primary label is applied
Service Endpoints switch — the ClusterIP service automatically routes traffic to the new primary

Total failover time is typically within 10–30 seconds, bounded by the down-after-milliseconds setting and the Sentinel quorum agreement time.

For a planned switchover, KubeBlocks calls the Sentinel SENTINEL FAILOVER command via kbagent, which performs a graceful promotion of a chosen replica.

System Accounts

KubeBlocks automatically manages the following Redis system account. The password is auto-generated and stored in a Secret named {cluster}-{component}-account-default.

Account	Role	Purpose
`default`	Admin	Default Redis authentication account; used for all client connections and inter-component communication (data pods, Sentinel, `kbagent`)