Skip to main content

​
Overview

This guide will walk you through creating a Redis cluster, connecting to it, and performing basic operations. You’ll have a working Redis cluster in under 5 minutes.
Before starting, ensure you have installed the Redis Operator and have kubectl access to your cluster.

​
Create a Redis Cluster

1

Create a RedisCluster Resource

Create a file named my-redis.yaml with a basic RedisCluster configuration:
my-redis.yaml
apiVersion: redis.io/v1
kind: RedisCluster
metadata:
  name: my-redis
  namespace: default
spec:
  instances: 3
  mode: standalone
  storage:
    size: 1Gi
This creates a 3-instance Redis cluster (1 primary + 2 replicas) in standalone mode with 1Gi of persistent storage per instance.
The operator automatically defaults spec.imageName to redis:7.2 and spec.mode to standalone if not specified.
Apply the configuration:
kubectl apply -f my-redis.yaml
Expected output:
rediscluster.redis.io/my-redis created
2

Wait for the Cluster to be Ready

Monitor the cluster status:
kubectl get rediscluster my-redis -n default --watch
The cluster progresses through phases:
NAME        INSTANCES   READY   PHASE       PRIMARY        AGE
my-redis    3           0       Creating                   5s
my-redis    3           1       Creating    my-redis-2     15s
my-redis    3           2       Replicating my-redis-2     25s
my-redis    3           3       Healthy     my-redis-2     35s
Wait for the Ready count to match Instances and Phase to be Healthy:
kubectl wait --for=condition=Ready rediscluster/my-redis -n default --timeout=10m
The cluster is ready when status.phase is Healthy and status.readyInstances equals spec.instances.
3

Verify Cluster Resources

Check the created resources:
# View all pods
kubectl get pods -n default -l redis.io/cluster=my-redis
Expected output:
NAME         READY   STATUS    RESTARTS   AGE
my-redis-0   1/1     Running   0          60s
my-redis-1   1/1     Running   0          60s
my-redis-2   1/1     Running   0          60s

# View services
kubectl get svc -n default -l redis.io/cluster=my-redis
Expected output:
NAME               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
my-redis-any       ClusterIP   10.96.100.10    <none>        6379/TCP   60s
my-redis-leader    ClusterIP   10.96.100.11    <none>        6379/TCP   60s
my-redis-replica   ClusterIP   10.96.100.12    <none>        6379/TCP   60s

# View persistent volumes
kubectl get pvc -n default -l redis.io/cluster=my-redis
Expected output:
NAME         STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
my-redis-0   Bound    pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890   1Gi        RWO            standard       60s
my-redis-1   Bound    pvc-b2c3d4e5-f6a7-8901-bcde-f12345678901   1Gi        RWO            standard       60s
my-redis-2   Bound    pvc-c3d4e5f6-a7b8-9012-cdef-123456789012   1Gi        RWO            standard       60s

​
Connect to Redis

1

Retrieve the Auto-Generated Password

The operator automatically creates an auth secret named <cluster-name>-auth:
PASSWORD=$(kubectl get secret my-redis-auth -n default -o jsonpath='{.data.password}' | base64 -d)
echo "Redis password: $PASSWORD"
If you don’t specify spec.authSecret, the operator generates a random password and stores it in a Secret named <cluster-name>-auth.
2

Port-Forward to the Leader Service

Forward port 6379 to the primary Redis instance:
kubectl port-forward svc/my-redis-leader 6379:6379 -n default
Keep this terminal open and open a new terminal for the next step.
3

Connect with redis-cli

Connect to Redis using the redis-cli:
redis-cli -a "$PASSWORD" -h 127.0.0.1 -p 6379 ping
Expected output:
PONG
Try some basic commands:
# Set a key
redis-cli -a "$PASSWORD" -h 127.0.0.1 -p 6379 SET mykey "Hello Redis"

# Get the key
redis-cli -a "$PASSWORD" -h 127.0.0.1 -p 6379 GET mykey

# Check replication info
redis-cli -a "$PASSWORD" -h 127.0.0.1 -p 6379 INFO replication

​
Service Endpoints

The operator creates three service endpoints per cluster: 
# my-redis-leader
# Routes to the current primary pod (status.currentPrimary)
# Use for: Write operations

apiVersion: v1
kind: Service
metadata:
  name: my-redis-leader
spec:
  selector:
    redis.io/cluster: my-redis
    redis.io/role: primary
  ports:
  - port: 6379
    targetPort: 6379

​
Connection Strings

Use these service DNS names from within the cluster:
  • Writes: my-redis-leader.default.svc.cluster.local:6379
  • Reads: my-redis-replica.default.svc.cluster.local:6379
  • Any instance: my-redis-any.default.svc.cluster.local:6379

​
Configuration Examples

​
Production Cluster with Resources

apiVersion: redis.io/v1
kind: RedisCluster
metadata:
  name: prod-redis
  namespace: production
spec:
  instances: 5
  mode: standalone
  imageName: redis:7.2
  
  storage:
    size: 50Gi
    storageClassName: fast-ssd
  
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  
  # Synchronous replication
  minSyncReplicas: 1
  maxSyncReplicas: 2
  
  # Custom Redis configuration
  redis:
    maxmemory: "3gb"
    maxmemory-policy: "allkeys-lru"
    save: "900 1 300 10 60 10000"
  
  # Enable PodDisruptionBudget
  enablePodDisruptionBudget: true
  
  # Spread across availability zones
  topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: topology.kubernetes.io/zone
    whenUnsatisfiable: DoNotSchedule
    labelSelector:
      matchLabels:
        redis.io/cluster: prod-redis

​
Verify Replication

Check the replication topology: 
# Get cluster status
kubectl get rediscluster my-redis -n default -o yaml
Look for status.currentPrimary and status.instancesStatus:
status excerpt
status:
  phase: Healthy
  currentPrimary: my-redis-2
  readyInstances: 3
  instances: 3
  instancesStatus:
    my-redis-0:
      role: slave
      connected: true
      replicationOffset: 12345
      replicaLagBytes: 0
      masterLinkStatus: up
    my-redis-1:
      role: slave
      connected: true
      replicationOffset: 12345
      replicaLagBytes: 0
      masterLinkStatus: up
    my-redis-2:
      role: master
      connected: true
      replicationOffset: 12345
      connectedReplicas: 2
The operator automatically configures my-redis-0 and my-redis-1 as replicas of my-redis-2 using the REPLICAOF command.

​
Test Failover

Simulate a primary failure to test automatic failover: 
# Delete the current primary pod
PRIMARY=$(kubectl get rediscluster my-redis -n default -o jsonpath='{.status.currentPrimary}')
kubectl delete pod $PRIMARY -n default

# Watch the cluster recover
kubectl get rediscluster my-redis -n default --watch
The cluster will:
  1. Detect the primary is unreachable
  2. Fence the old primary (add fencing annotation)
  3. Promote a replica to primary
  4. Update status.currentPrimary
  5. Reconfigure remaining replicas
  6. Return to Healthy phase
Failover typically completes in under 30 seconds. The operator uses a fencing-first approach to prevent split-brain scenarios.

​
Scale the Cluster

Scale up by adding more replicas: 
kubectl patch rediscluster my-redis -n default --type merge -p '{"spec":{"instances":5}}'
Watch the scale operation: 
kubectl get rediscluster my-redis -n default --watch
The cluster will:
  1. Enter Scaling phase
  2. Create new PVCs and Pods
  3. Configure new pods as replicas
  4. Return to Healthy phase when all instances are ready

​
Clean Up

Delete the Redis cluster: 
kubectl delete rediscluster my-redis -n default
Deleting a RedisCluster resource deletes the Pods, Services, and ConfigMaps. By default, PVCs are retained to prevent accidental data loss. Delete PVCs manually if you want to remove all data.
To delete PVCs: 
kubectl delete pvc -n default -l redis.io/cluster=my-redis

​
Next Steps

API Reference

Explore all RedisCluster configuration options

Backup & Restore

Learn how to backup and restore Redis data

Monitoring

Set up Prometheus metrics and Grafana dashboards

Runbooks

Operational guides for common scenarios

Build docs developers (and LLMs) love

Get started for freeTalk to us