RedisCluster CRD

Overview

The RedisCluster custom resource defines a Redis replication cluster with one primary and N-1 replicas. It supports standalone and sentinel modes. API Group: redis.io/v1
Kind: RedisCluster
Short Name: rc

Spec Fields

Core Configuration

instances

int32

required

Total number of Redis pods (1 primary + N-1 replicas)Constraints:

Minimum: 1
Default: 1

mode

ClusterMode

default:"standalone"

Redis operating modeEnum values:

standalone - Single primary with optional replicas
sentinel - Sentinel-managed automatic failover
cluster - Reserved for future use (currently rejected by webhook)

primaryUpdateStrategy

PrimaryUpdateStrategy

default:"unsupervised"

Controls how the primary is updated during rolling updatesEnum values:

unsupervised - Primary replacement runs automatically after replicas are updated
supervised - Waits for operator approval via redis.io/approve-primary-update annotation

imageName

string

default:"redis:7.2"

Redis container image (wire-compatible with Valkey 7.x/8.x)

Storage

storage

StorageSpec

required

PVC template for /data volumes

Show StorageSpec fields

size

resource.Quantity

default:"1Gi"

Requested storage size (e.g., 10Gi, 100Gi)

storageClassName

string

Name of the StorageClass to use for PVCs

Redis Configuration

redis

map[string]string

Redis.conf configuration parameters as key-value pairsExample:

redis:
  maxmemory: "2gb"
  maxmemory-policy: "allkeys-lru"
  tcp-keepalive: "300"

Note: Parameters requiring restart (bind, port, tls-port, unixsocket, databases) are applied on pod creation but not live-reloaded.

resources

corev1.ResourceRequirements

CPU/memory requests and limits for Redis containersExample:

resources:
  requests:
    cpu: "1"
    memory: "2Gi"
  limits:
    cpu: "2"
    memory: "4Gi"

Replication

minSyncReplicas

int32

default:"0"

Minimum number of synchronous replicas (corresponds to min-replicas-to-write)Constraints:

Minimum: 0

maxSyncReplicas

int32

default:"0"

Maximum number of synchronous replicas (corresponds to min-replicas-max-lag)Constraints:

Minimum: 0

Secrets

authSecret

LocalObjectReference

Reference to a Secret containing the Redis password in key password. If not set, the operator auto-generates one.

Show LocalObjectReference fields

name

string

required

Name of the Secret in the same namespace

aclConfigSecret

LocalObjectReference

Reference to a Secret containing ACL rules in key aclThe instance manager writes this to /data/users.acl and issues ACL LOAD on changes.

tlsSecret

LocalObjectReference

Reference to a Secret containing tls.crt and tls.key for TLS encryption

caSecret

LocalObjectReference

Reference to a Secret containing ca.crt for TLS client certificate verification

backupCredentialsSecret

LocalObjectReference

Reference to a Secret containing object storage credentials for backupsExpected keys:

AWS_ACCESS_KEY_ID or aws_access_key_id or accessKeyId or access_key_id
AWS_SECRET_ACCESS_KEY or aws_secret_access_key or secretAccessKey or secret_access_key
AWS_SESSION_TOKEN or aws_session_token or sessionToken or session_token (optional)

High Availability

enablePodDisruptionBudget

bool

default:"true"

Controls whether a PodDisruptionBudget is created to protect against simultaneous disruptions

primaryIsolation

PrimaryIsolationSpec

Configures runtime split-brain prevention for primary pods

Show PrimaryIsolationSpec fields

enabled

bool

default:"true"

Controls runtime primary-isolation checks in /healthz endpointWhen enabled, primary pods fail healthz if they cannot reach both the Kubernetes API server and at least one peer instance.

apiServerTimeout

metav1.Duration

default:"5s"

Timeout for Kubernetes API reachability checks

peerTimeout

metav1.Duration

default:"5s"

Timeout for peer instance-manager reachability checks

Scheduling

nodeSelector

map[string]string

Constrains pods to nodes with matching labelsExample:

nodeSelector:
  node.kubernetes.io/instance-type: "m5.xlarge"

affinity

corev1.Affinity

Pod affinity/anti-affinity scheduling rules. See Kubernetes Affinity docs.

tolerations

[]corev1.Toleration

Allow scheduling onto tainted nodes. See Kubernetes Tolerations docs.

topologySpreadConstraints

[]corev1.TopologySpreadConstraint

Control how pods are spread across topology domains. See Kubernetes Topology Spread Constraints docs.

Bootstrap

bootstrap

BootstrapSpec

Defines how to initialize the cluster from a backup

Show BootstrapSpec fields

backupName

string

required

Name of the RedisBackup resource to restore from

Maintenance

nodeMaintenanceWindow

NodeMaintenanceWindow

Controls planned node maintenance behavior

Show NodeMaintenanceWindow fields

inProgress

bool

required

Indicates planned node maintenance is currently in progress

reusePVC

bool

default:"true"

Controls whether PVCs are reused during maintenance

Disaster Recovery (Replica Mode)

replicaMode

ReplicaModeSpec

Configures external replication topology for disaster recovery clusters

Show ReplicaModeSpec fields

enabled

bool

default:"false"

Toggles external replication mode for all data podsWhen enabled, all pods replicate from an external Redis source instead of an internal primary.

source

ReplicaSourceSpec

Identifies the external Redis primary to replicate from

Show ReplicaSourceSpec fields

clusterName

string

Human-readable source cluster identifier (for labeling/events)

host

string

required

External Redis endpoint hostname or IP

port

int32

default:"6379"

External Redis portConstraints:

Minimum: 1
Maximum: 65535

authSecretName

string

Name of a Secret with key password for upstream authentication

promote

bool

default:"false"

Requests promotion of the local designated leader to standalone primaryWhen set to true, the instance manager promotes the current primary out of replica mode by issuing REPLICAOF NO ONE.

Status Fields

phase

ClusterPhase

Human-readable cluster phasePossible values:

Creating - Initial provisioning in progress
Healthy - All instances ready and replication healthy
Degraded - Some instances not ready or replication lag detected
Replicating - External replication active (replica mode)
FailingOver - Automatic failover in progress
Scaling - Scale-up or scale-down in progress
Updating - Rolling update in progress
WaitingForUser - Supervised primary update waiting for approval
Deleting - Finalizers executing
Hibernating - All pods scaled to zero (annotation-triggered)

currentPrimary

string

Pod name of the current primary instanceExample: my-redis-0

readyInstances

int32

Count of data pods passing readiness probes

sentinelReadyInstances

int32

Count of sentinel pods passing readiness probes (sentinel mode only)

instances

int32

Total number of managed pods

instancesStatus

map[string]InstanceStatus

Per-pod status map keyed by pod name

Show InstanceStatus fields

role

string

master or slave as reported by Redis INFO replication

connected

bool

Whether the instance manager can reach Redis

replicationOffset

int64

Current replication offset

replicaLagBytes

int64

Replication lag in bytes (replicas only)

connectedReplicas

int32

Number of connected replicas (primary only)

masterLinkStatus

string

up or down (replicas only)

lastSeenAt

metav1.Time

When this status was last reported

healthyPVC

int32

Count of healthy PersistentVolumeClaims

danglingPVC

[]string

List of PVC names not attached to any podUsed to detect orphaned storage after scale-down or pod deletion.

secretsResourceVersion

map[string]string

Maps secret names to their ResourceVersionUsed to detect secret rotation and trigger reconciliation.

conditions

[]metav1.Condition

Latest available observations of the cluster stateStandard condition types:

Ready - Overall cluster health
PrimaryAvailable - Primary instance is reachable
ReplicationHealthy - All replicas have healthy replication links
ReplicaMode - External replication active
PrimaryUpdateWaiting - Supervised update waiting for approval
LastBackupSucceeded - Most recent backup completed successfully
Hibernated - Cluster is hibernated
MaintenanceInProgress - Node maintenance window active
PVCResizeInProgress - PVC resize operation in progress

Annotations

Fencing

Key: redis.io/fencedInstances Value: JSON array of pod names to fence (stop redis-server) Example:

annotations:
  redis.io/fencedInstances: '["my-redis-0", "my-redis-1"]'

Fenced pods have their redis-server process stopped by the instance reconciler.

Hibernation

Key: redis.io/hibernation Value: on or true Example:

annotations:
  redis.io/hibernation: "on"

Scales all pods to zero while preserving PVCs.

Primary Update Approval

Key: redis.io/approve-primary-update Value: true Example:

annotations:
  redis.io/approve-primary-update: "true"

Approves a supervised primary update. The operator removes this annotation after promotion completes.

Labels

The operator applies these labels to all managed resources:

Label	Values	Description
`redis.io/cluster`	`<cluster-name>`	RedisCluster name
`redis.io/instance`	`<pod-name>`	Pod name
`redis.io/role`	`primary`, `replica`, `sentinel`	Current role
`redis.io/workload`	`data`, `sentinel`	Workload type

Constants

Sentinel Defaults

SentinelPort      = 26379
SentinelInstances = 3
SentinelQuorum    = 2

Example

apiVersion: redis.io/v1
kind: RedisCluster
metadata:
  name: my-redis
  namespace: default
spec:
  instances: 3
  mode: standalone
  imageName: redis:7.2
  storage:
    size: 10Gi
    storageClassName: fast-ssd
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "2"
      memory: "4Gi"
  redis:
    maxmemory: "2gb"
    maxmemory-policy: "allkeys-lru"
  minSyncReplicas: 1
  enablePodDisruptionBudget: true
  primaryIsolation:
    enabled: true
    apiServerTimeout: 5s
    peerTimeout: 5s

Custom Resources

Instance Manager

Overview

Spec Fields

Core Configuration

Storage

Redis Configuration

Replication

Secrets

High Availability

Scheduling

Bootstrap

Maintenance

Disaster Recovery (Replica Mode)

Status Fields

Annotations

Fencing

Hibernation

Primary Update Approval

Labels

Constants

Sentinel Defaults

Example

Build docs developers (and LLMs) love

Custom Resources

Instance Manager

​Overview

​Spec Fields

​Core Configuration

​Storage

​Redis Configuration

​Replication

​Secrets

​High Availability

​Scheduling

​Bootstrap

​Maintenance

​Disaster Recovery (Replica Mode)

​Status Fields

​Annotations

​Fencing

​Hibernation

​Primary Update Approval

​Labels

​Constants

​Sentinel Defaults

​Example

Build docs developers (and LLMs) love

Overview

Spec Fields

Core Configuration

Storage

Redis Configuration

Replication

Secrets

High Availability

Scheduling

Bootstrap

Maintenance

Disaster Recovery (Replica Mode)

Status Fields

Annotations

Fencing

Hibernation

Primary Update Approval

Labels

Constants

Sentinel Defaults

Example