apecloud/kubeblocks-addon-redis

Deploy Redis on KubeBlocks

Overview

Deploy Redis on Kubernetes using KubeBlocks. Three topologies are available: standalone for development, replication with Sentinel for HA, and Redis Cluster for horizontal sharding.

Official docs: https://kubeblocks.io/docs/preview/user_docs/kubeblocks-for-redis/cluster-management/create-and-connect-a-redis-cluster Full doc index: https://kubeblocks.io/llms-full.txt

Prerequisites

• A running Kubernetes cluster with KubeBlocks installed (see install-kubeblocks)
• The Redis addon must be enabled:

# Check if redis addon is installed
helm list -n kb-system | grep redis

# Install if missing
helm install kb-addon-redis kubeblocks/redis --namespace kb-system --version 1.0.0

Available Topologies

| Topology | clusterDef | topology | Components | Use Case | |---|---|---|---|---| | Standalone | redis | standalone | redis (1 replica) | Dev/test, no HA needed | | Replication | redis | replication | redis (2+) + redis-sentinel (3) | Production HA | | Sharding | N/A | N/A | Uses spec.shardings with componentDef redis-cluster-7 | Horizontal scaling |

Important: The sharding topology uses spec.shardings instead of spec.componentSpecs. This is a fundamentally different spec structure.

Supported Versions

| Version | serviceVersion | |---|---| | Redis 7.0 | 7.0.6 | | Redis 7.2 | 7.2.4 |

Workflow

- [ ] Step 1: Ensure addon is installed
- [ ] Step 2: Create namespace
- [ ] Step 3: Create cluster (choose topology)
- [ ] Step 4: Wait for cluster to be ready
- [ ] Step 5: Connect to Redis

Step 1: Ensure Addon Is Installed

helm list -n kb-system | grep redis

If not found:

helm install kb-addon-redis kubeblocks/redis --namespace kb-system --version 1.0.0

Step 2: Create Namespace

kubectl create namespace demo --dry-run=client -o yaml | kubectl apply -f -

Step 3: Create Cluster

Standalone

Simplest setup, single Redis instance. Good for development:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-standalone
  namespace: demo
spec:
  clusterDef: redis
  topology: standalone
  terminationPolicy: Delete
  componentSpecs:
    - name: redis
      serviceVersion: "7.2.4"
      replicas: 1
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Replication with Sentinel

Production-ready HA setup. Sentinel monitors the primary and performs automatic failover:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-replication
  namespace: demo
spec:
  clusterDef: redis
  topology: replication
  terminationPolicy: Delete
  componentSpecs:
    - name: redis
      serviceVersion: "7.2.4"
      replicas: 2
      resources:
        limits: {cpu: "0.5", memory: "0.5Gi"}
        requests: {cpu: "0.5", memory: "0.5Gi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}
    - name: redis-sentinel
      serviceVersion: "7.2.4"
      replicas: 3
      resources:
        limits: {cpu: "0.2", memory: "256Mi"}
        requests: {cpu: "0.2", memory: "256Mi"}
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes: [ReadWriteOnce]
            resources: {requests: {storage: 20Gi}}

Key points:

• The redis component has 2+ replicas (1 primary + replicas, managed by Sentinel)
• The redis-sentinel component needs 3 replicas for quorum

Redis Cluster (Sharding)

For horizontal scaling with data sharding. This topology uses spec.shardings instead of spec.componentSpecs:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: redis-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  shardings:
    - name: shard
      shards: 3
      template:
        name: redis-shard
        componentDef: redis-cluster-7
        serviceVersion: "7.2.4"
        replicas: 2
        resources:
          limits: {cpu: "0.5", memory: "0.5Gi"}
          requests: {cpu: "0.5", memory: "0.5Gi"}
        volumeClaimTemplates:
          - name: data
            spec:
              accessModes: [ReadWriteOnce]
              resources: {requests: {storage: 20Gi}}

Key points:

• Uses spec.shardings — NOT spec.componentSpecs
• shards: 3 creates 3 shards (minimum recommended)
• Each shard has replicas: 2 (1 primary + 1 replica per shard)
• Uses componentDef: redis-cluster-7 (not clusterDef)
• Does NOT set clusterDef or topology at the cluster level

Step 4: Wait for Cluster Ready

kubectl -n demo get cluster <cluster-name> -w

Wait until STATUS shows Running.

Check pods:

kubectl -n demo get pods -l app.kubernetes.io/instance=<cluster-name>

Step 5: Connect to Redis

Get Credentials

# Secret name format: <cluster>-redis-account-default
kubectl -n demo get secret redis-standalone-redis-account-default -o jsonpath='{.data.password}' | base64 -d

Connect via kubectl exec

# Standalone / Replication
kubectl -n demo exec -it redis-standalone-redis-0 -- redis-cli

# Redis Cluster (use -c flag for cluster mode)
kubectl -n demo exec -it redis-cluster-shard-ckvks-0 -- redis-cli -c

Connect via Port-Forward

kubectl -n demo port-forward svc/redis-standalone-redis 6379:6379
# Then from another terminal:
redis-cli -h 127.0.0.1 -p 6379

Troubleshooting

Cluster stuck in Creating:

kubectl -n demo describe cluster <cluster-name>
kubectl -n demo get events --sort-by='.lastTimestamp'

Sentinel failover issues:

kubectl -n demo exec -it redis-replication-redis-sentinel-0 -- redis-cli -p 26379 SENTINEL masters

Redis Cluster slots not assigned:

kubectl -n demo exec -it <any-shard-pod> -- redis-cli -c CLUSTER INFO

Day-2 Operations

| Operation | Skill | External Docs | |---|---|---| | Stop / Start / Restart | cluster-lifecycle | Docs | | Scale CPU / Memory | vertical-scaling | Docs | | Add / Remove replicas | horizontal-scaling | Docs | | Expand storage | volume-expansion | Docs | | Change parameters | reconfigure-parameters | Docs | | Expose externally | expose-service | Docs | | Backup | backup | Docs | | Restore | restore | Docs |

Safety Patterns

Follow safety-patterns.md for dry-run before apply, status confirmation after watch, and pre-deletion checklist.

Next Steps

• For full YAML examples of all topologies, see reference.md