Redis-Cluster on Kubernetes: Hands-on Guide ①

Manifest (YAML) overview

Redis-Cluster overview

Redis-Cluster spreads data across three Redis Pods (masters), and each master Pod has a backup (replica) Pod. If a Redis master Pod goes down, the backup (replica) Redis is promoted to master.
Let’s build Redis-Cluster with six Pods (3 masters, 3 replicas).
🔗 See here for an overall Redis-Cluster overview.

1. Redis-Cluster manifests (YAML)

When you deploy Redis-Cluster on Kubernetes, split the work into Config, Service, and creation (StatefulSet) roles and manage them as three YAML files.

┌─────────────────────────────────────────────────────┐ │ 1. redis-cluster-config.yaml (ConfigMap) │ │ : redis.conf, users.acl │ └──────────────────┬──────────────────────────────────┘ │ [Step 1: provide Config values] ▼ ┌─────────────────────────────────────────────────────┐ │ 2. redis-cluster-service.yaml (Headless Service) │ │ : redis-cluster-service, clusterIP: None, port │ └──────────────────┬──────────────────────────────────┘ │ [Step 2: prepare the Service] ▼ ┌─────────────────────────────────────────────────────┐ │ 3. redis-cluster-statefulset.yaml (StatefulSet) │ │ : Config, Service -> redis-cluster-0~5 (6Pods) │ │ Persistent Volume Claim (PVC) │ └─────────────────────────────────────────────────────┘ [Step 3: create Redis Pods]

2. File contents by deploy order

🟢 [Step 1] Redis config: redis-cluster-config.yaml

kind: ConfigMap
name (metadata:name): redis-cluster-config
⚠️ Names are strictly limited to lowercase (a-z), digits (0-9), and hyphen (`-`) (uppercase is not allowed)
This is the ConfigMap settings file. The directives here are used to create redis.conf.
The redis.conf that ships with the tarball is not used.
If each Redis instance (Pod) needs a different value, you can set it dynamically with a command script in the StatefulSet. Example) cluster-announce-hostname redis-cluster-0,1,2...

🧑‍💻 Key values

bind * -::* # IPs are assigned and change dynamically, so accept all IPs.
KISA (Korea Internet & Security Agency) [Cloud Vulnerability Assessment Guide] insists on setting an IP on bind for security. That is correct on VMs/bare metal, but you cannot do that in Kubernetes.
(You will need to explain this clearly to auditors on public-sector/finance projects.)
protected-mode no # Because bind is '*', setting 'yes' blocks external connections.
It may look like a security violation, but Kubernetes has its own security, so this setting is fine.
daemonize no # Do not set this to 'yes'.
requirepass password # 💥Always set a password. If the server or PC is on the internet, set a password even in a development environment. Redis is not hacked by 🕵️people (hackers) but by 💻 programs that scan 24 hours a day. Without a password, even a few minutes of a dev instance can be compromised immediately.
See here for details. 🔗 Redis Hacking
If you configure users.acl, you do not need to set 'requirepass'.
masterauth password # Always set this.
cluster-node-timeout 3000 # Node-down detection time (3000ms (3sec)): set to 3 seconds.
cluster-announce-hostname, cluster-announce-human-nodename These two items are injected dynamically at Pod creation time: the initContainer command in statefulset.yaml looks up the Pod name. So do not set them here.
echo "cluster-announce-hostname ${POD_FQDN}" >> /data/redis.conf
echo "cluster-announce-human-nodename ${POD_NAME}" >> /data/redis.conf
users.acl: lines 90–91. Password ('#0cbc...' 64 chars) must be set separately.
See here for details. 🔗 ACL

💾 View redis-cluster-config.yaml ▼

📄 redis-cluster-config.yaml

   1	apiVersion: v1
   2	kind: ConfigMap
   3	metadata:
   4	  name: redis-cluster-config
   5	data:
   6	  redis.conf: |
   7	    # Redis-8.8.1 configuration for Redis Cluster
   8	    # [NETWORK]
   9	    bind * -::*
  10	    protected-mode no
  11	    port 18504
  12	    tcp-keepalive 60
  13	    # [GENERAL]
  14	    daemonize no
  15	    pidfile /data/redis.pid
  16	    # notice / verbose / degub
  17	    loglevel notice
  18	    logfile /data/redis.log
  19	    always-show-logo yes
  20	    # locale-collate "ko_KR.UTF-8" -> Error: Failed to configure LOCALE for invalid locale name.
  21	    # [MEMORY MANAGEMENT]
  22	    maxmemory 1gb
  23	    # [SNAPSHOTTING]
  24	    dbfilename dump.rdb
  25	    rdb-del-sync-files yes
  26	    # [working directory]
  27	    dir /data
  28	    # [SECURITY]
  29	    requirepass password
  30	    masterauth password
  31	    enable-protected-configs no
  32	    enable-debug-command no
  33	    # 📍 File must be created
  34	    aclfile /data/users.acl
  35	    # [REPLICATION]
  36	    # replica-priority is not used in Redis-Cluster.
  37	    replica-priority 100                
  38	    repl-backlog-size 128mb
  39	    repl-diskless-sync yes
  40	    repl-diskless-sync-delay 3
  41	    repl-diskless-sync-max-replicas 0
  42	    repl-diskless-load on-empty-db
  43	    # [CLIENTS]
  44	    maxclients 10000
  45	    client-output-buffer-limit normal 0 0 0
  46	    client-output-buffer-limit replica 1gb 1gb 120
  47	    client-output-buffer-limit pubsub 128mb 64mb 60
  48	    # [APPEND ONLY MODE]
  49	    save ""
  50	    appendonly yes
  51	    appendfilename "aof"
  52	    appenddirname "aof"	
  53	    appendfsync everysec
  54	    no-appendfsync-on-rewrite yes
  55	    auto-aof-rewrite-percentage 200
  56	    auto-aof-rewrite-min-size 1gb
  57	    aof-use-rdb-preamble yes
  58	    aof-timestamp-enabled yes
  59	    # [SLOW LOG]
  60	    slowlog-log-slower-than 10000
  61	    slowlog-max-len 1024
  62	    # [LATENCY MONITOR]
  63	    # 10ms, 0 disable
  64	    latency-monitor-threshold 10		
  65	    # [REDIS CLUSTER]
  66	    cluster-enabled yes
  67	    cluster-config-file nodes.conf
  68	    # Node-down detection time: 3000ms (3sec)
  69	    cluster-node-timeout 3000
  70	    # Minimum number of replicas a master must have
  71	    cluster-migration-barrier 1
  72	    # yes: if any master with no replica goes down, the cluster
  73	    #      goes down and no client operations work.
  74	    # no:  even if a master with no replica goes down, the cluster stays up.
  75	    #      Slots of the down node error, but slots on other nodes still
  76	    #      accept insert/update/delete/get normally.
  77	    cluster-require-full-coverage no
  78	    # yes: allow reads even when the cluster is Down: default no
  79	    cluster-allow-reads-when-down yes
  80	    # yes: allow Pub/Sub shard even when the cluster is Down: default yes
  81	    cluster-allow-pubsubshard-when-down yes
  82	    # 📍 The two items below are injected dynamically at Pod start
  83	    #    by initContainer/Command with each Pod's DNS and name
  84	    # 🚩 Use Headless Service DNS names instead of IPs
  85	    cluster-announce-hostname ""
  86	    # 🚩 Node ID is a 40-char random hash like `e4a7f10...`
  87	    #    -> use the Kubernetes Pod name (redis-cluster-0)
  88	    cluster-announce-human-nodename ""
  89	
  90	  users.acl: |
  91	    user default on sanitize-payload #0cbc... ~* &* +@all

The values shown here are redis.conf settings applied at 90%+ of the 100+ sites redisGate has installed and operated. (Adjust maxmemory to match your data size)

💻 On bare metal/VMs, change the following values.

bind 114.x.y.z 127.0.0.1 -::1 -> pin an IP
protected-mode yes
port -> default 💥port 6379 is a major hacking target. Always use a different port.
daemonize yes
dir /app/redis -> also put pidfile, logfile, etc. under this dir
aclfile /app/redis/users.acl -> per-user permissions: recommended
#maxmemory <bytes> -> comment out (default)
① On a Redis-dedicated server, set 50%–90% of system memory
② If you have plenty of RAM: e.g. 16GB system memory and Redis using 1–2GB, (in practice) you may not need to set it
③ 💥 If Redis uses all system memory, the OS (Linux) kills the Redis process.
#cluster-announce-hostname "" -> comment out (default)
#cluster-announce-human-nodename "" -> comment out (default)

🟢 [Step 2] Service config: redis-cluster-service.yaml

kind: Service
name (metadata:name): redis-cluster-service
⚠️ Names are strictly limited to lowercase (a-z), digits (0-9), and hyphen (`-`) (uppercase is not allowed)
This is the Service settings file. Even if Pod IPs change, it prepares a network address board so you can reach each Redis by a stable domain name (FQDN: Fully Qualified Domain Name).

🧑‍💻 Key values

clusterIP: None # 📍Set to 'None' (to identify each Pod DNS independently)
port: 18504 # Redis port
port: 28504 # Redis Cluster bus port

💾 View redis-cluster-service.yaml ▼

📄 redis-cluster-service.yaml

  1	apiVersion: v1
  2	kind: Service
  3	metadata:
  4	  name: redis-cluster-service
  5	  labels:
  6	    app: redis-cluster
  7	spec:
  8	  clusterIP: None   # Keep Headless Service (identify each Pod DNS independently)
  9	  ports:
 10	  - port: 18504
 11	    name: redis-port    # Client response and data port
 12	  - port: 28504
 13	    name: cluster-bus-port # ⭐ Dedicated Redis Cluster Gossip port
 14	  selector:
 15	    app: redis-cluster

🟢 [Step 3] Redis Pod creation manifest: redis-cluster-statefulset.yaml

Manifest file that creates Redis Pods (replicas, initContainers, memory, pvc (disk volume)).

kind: StatefulSet
name (metadata:name): redis-cluster
⚠️ Names are limited to lowercase (a-z), digits (0-9), and hyphen (`-`) (uppercase is not allowed)
Pod names are built from this name plus a number: redis-cluster-0,1,2.
The Pod name and serviceName are used to build an FQDN (Fully Qualified Domain Name) as follows.
redis-cluster-0.redis-cluster-service.default.svc.cluster.local
Each Redis can talk to other Redis instances or to the App by its unique FQDN.
When the IP changes, the new IP is bound to the FQDN.

🧑‍💻 Key values

configMap: name: redis-cluster-config (linked to Step 1 Redis config)
serviceName: redis-cluster-service (linked to Step 2 Service)
replicas: 6 # Create 6 Redis Pods. Splitting roles into Master (3) and Replica (3) is decided when Redis-Cluster is created.
image: redis:8.8.2 # Use version 8.8.2, released 17 Aug 2026 (Mon)
imagePullPolicy: IfNotPresent # Use the local image
command script: copy ConfigMap files from Step 1 and apply dynamic settings
volumeMounts: mountPath: /data: stores all files Redis uses/manages (redis.conf, users.acl, aof files, and so on).

💾 View redis-cluster-statefulset.yaml ▼

📄 redis-cluster-statefulset.yaml

   1	apiVersion: apps/v1
   2	kind: StatefulSet
   3	metadata:
   4	  name: redis-cluster
   5	spec:
   6	  serviceName: "redis-cluster-service"
   7	  replicas: 6
   8	  selector:
   9	    matchLabels:
  10	      app: redis-cluster
  11	  template:
  12	    metadata:
  13	      labels:
  14	        app: redis-cluster
  15	    spec:
  16	      initContainers:
  17	      - name: init-redis-config
  18	        image: redis:8.8.1
  19	        imagePullPolicy: IfNotPresent  # Use the local image
  20	        command:
  21	        - /bin/sh
  22	        - -c
  23	        - |
  24	          # 1. Copy read-only redis.conf from ConfigMap to writable /data
  25	          cp /readonly-config/redis.conf /data/redis.conf
  26	          chmod 600 /data/redis.conf
  27	
  28	          # 2. Copy users.acl and set permissions
  29	          cp /readonly-config/users.acl /data/users.acl
  30	          chmod 600 /data/users.acl
  31	          
  32	          # 3. Inject Redis Cluster dynamic FQDN and Human-Nodename
  33	          POD_NAME=$(hostname)
  34	          SERVICE_NAME="redis-cluster-service"
  35	          NAMESPACE="default"
  36	          POD_FQDN="${POD_NAME}.${SERVICE_NAME}.${NAMESPACE}.svc.cluster.local"
  38	          echo "cluster-announce-hostname ${POD_FQDN}" >> /data/redis.conf
  39	          echo "cluster-announce-human-nodename ${POD_NAME}" >> /data/redis.conf
  40	
  53	        volumeMounts:
  54	        - name: config-volume
  55	          mountPath: /readonly-config
  56	        - name: redis-data
  57	          mountPath: /data
  58	        # 📍 Pod memory and CPU resource settings
  59	        resources:
  60	          requests:
  61	            memory: "1Gi"      # Guaranteed minimum memory (node scheduling)
  62	            cpu: "500m"        # Guaranteed minimum CPU (0.5 core)
  63	          limits:
  64	            memory: "1.2Gi"    # Max memory (OOM if exceeded)
  65	            cpu: "1000m"       # Max CPU (1 core)
  66	      containers:
  67	      - name: redis
  68	        image: redis:8.8.1
  69	        imagePullPolicy: IfNotPresent  # Use the local image
  70	        # 🚩 Copy /data/.bashrc to /root/ then start Redis
  71	        command:
  72	        - /bin/sh
  73	        - -c
  74	        - |
  75	          cat << 'EOF' >> /root/.bashrc
  76	          alias cls='clear'
  77	          alias ll='ls -l --color=auto'
  78	          alias ls='ls --color=auto'
  79	          EOF
  80	          exec redis-server /data/redis.conf
  81	        #command: ["redis-server", "/data/redis.conf"]
  82	        ports:
  83	        - containerPort: 18504
  84	          name: redis-port
  85	        # 🚩 Added Redis Cluster Bus (Gossip) port
  86	        - containerPort: 28504 
  87	          name: cluster-port
  88	        volumeMounts:
  89	        - name: redis-data
  90	          mountPath: /data
  91	        # Mount the Host OS timezone into the container
  92	        - name: tz-config
  93	          mountPath: /etc/localtime
  94	          readOnly: true
  95	      volumes:
  96	      - name: config-volume
  97	        configMap:
  98	          name: redis-cluster-config
  99	      # Refer to the Host OS /etc/localtime file
 100	      - name: tz-config
 101	        hostPath:
 102	          path: /etc/localtime
 103	  volumeClaimTemplates:
 104	  - metadata:
 105	      name: redis-data
 106	    spec:
 107	      accessModes: [ "ReadWriteOnce" ]
 108	      resources:
 109	        requests:
 110	          storage: 10Gi

🧑‍💻 initContainers: command: script notes

① Copy read-only redis.conf from ConfigMap to writable /data

Redis can rewrite the conf file with 'config rewrite', and when Master-Replica roles change the 'replicaof' directive is rewritten. So redis.conf must live in a read-write directory.

📄 initContainers: command: cp redis.conf

cp /readonly-config/redis.conf /data/redis.conf chmod 600 /data/redis.conf
② Copy users.acl and set permissions

📄 initContainers: command: cp users.acl

cp /readonly-config/users.acl /data/users.acl chmod 600 /data/users.acl
③ Resolve Redis Cluster FQDN dynamically and inject cluster-announce-*name

📄 initContainers: command: cluster-announce-*name

POD_NAME=$(hostname) SERVICE_NAME="redis-cluster-service" NAMESPACE="default" POD_FQDN="${POD_NAME}.${SERVICE_NAME}.${NAMESPACE}.svc.cluster.local" echo "cluster-announce-hostname ${POD_FQDN}" >> /data/redis.conf echo "cluster-announce-human-nodename ${POD_NAME}" >> /data/redis.conf

🧑‍💻 containers: command: script notes

④ 🚩 Add a few handy aliases in .bashrc

📄 containers: command: .bashrc

cat << 'EOF' >> /root/.bashrc alias cls='clear' alias ll='ls -l --color=auto' alias ls='ls --color=auto' EOF

With '--color=auto', filenames are colored as shown below.
dir file: redis-sentinel-model
exec file: cluster_create.sh
tar file: file redis-8.8.2.tar
⑤ redis.tar timestamps are UTC (UK). Switch to host OS time (Korea time here).

📄 containers: command: localtime

# Mount the Host OS timezone into the container - name: tz-config mountPath: /etc/localtime readOnly: true # Refer to the Host OS /etc/localtime file - name: tz-config hostPath: path: /etc/localtime

➡ Prep is done. Let’s create the Pods.

<< Preparing Redis on Kubernetes ③	K8s Redis-Cluster Setup ② >>

Email 답글이 올라오면 이메일로 알려드리겠습니다.