Edu/Support

쿠버네티스 환경에서 Redis-Cluster 구축 실전 가이드 ①

명세서(YAML) 개요 및 내용

Redis-Cluster 개요

Redis-Cluster는 레디스 3개 파드(마스터)에 데이터를 분산해서 저장(관리)하고, 각 파드(마스터)는 백업(복제) 파드를 가지고 있다. 레디스 마스터 파드가 다운되면 백업(복제) 레디스가 마스터로 승격된다.
6개 파드(마스터 3개, 복제 3개)로 레디스-클러스터를 구성해보자.
🔗 Redis-Cluster에 대한 전반적인 내용은 여기를 보세요.

1. Redis-Cluster 명세서(YAML)

쿠버네티스에서 Redis-Cluster를 배포할 때는 설정(Config), 서비스(Service), 생성(StatefulSet) 역할로 분리하여 3개의 YAML 파일로 관리합니다.

┌─────────────────────────────────────────────────────┐ │ 1. redis-cluster-config.yaml (ConfigMap) │ │ : redis.conf, users.acl │ └──────────────────┬──────────────────────────────────┘ │ [1단계: 설정값(Config) 제공] ▼ ┌─────────────────────────────────────────────────────┐ │ 2. redis-cluster-service.yaml (Headless Service) │ │ : redis-cluster-service, clusterIP: None, port │ └──────────────────┬──────────────────────────────────┘ │ [2단계: 서비스 준비] ▼ ┌─────────────────────────────────────────────────────┐ │ 3. redis-cluster-statefulset.yaml (StatefulSet) │ │ : Config, Service -> redis-cluster-0~5 (6Pods) │ │ Persistent Volume Claim (PVC) │ └─────────────────────────────────────────────────────┘ [3단계: 레디스 파드 생성]

2. 배포 순서에 따른 파일별 내용 설명

🟢 [1단계] 레디스 설정: redis-cluster-config.yaml

종류(kind): ConfigMap
이름(metadata:name): redis-cluster-config
⚠️ 이름은 소문자(a-z), 숫자(0-9), 하이픈(`-`)만 사용하도록 엄격하게 제한 (대문자 사용 불가)
ConfigMap 설정 파일입니다. 여기에 설정된 지시자로 redis.conf 파일을 만듭니다.
기존 압축(tar) 파일에 기본으로 제공되는 redis.conf 파일은 사용되지 않습니다.
레디스 인스턴스(파드)마다 다른 값이 필요하면 StatefulSet에서 command 스크립트를 사용해서 동적으로 설정할 수 있습니다. 예) cluster-announce-hostname redis-cluster-0,1,2...

🧑‍💻 주요 값 설명

bind * -::* # IP가 동적으로 할당되고 변경되므로 모든 IP를 받을 수 있도록 설정합니다.
한국인터넷진흥원(KISA) [클라우드 취약점 점검 가이드]에서는 보안 목적으로 bind 항목에 IP를 설정하도록 강요한다. VM/물리서버에서는 그게 맞지만, 쿠버네티스 환경에서는 설정할 수가 없다.
(공공/금융권 등 프로젝트에서 감리위원에게 잘 설명할 필요가 있습니다)
protected-mode no # 'bind *'으로 설정했기 때문에 'yes'로 설정하면 외부에서 접속할 수 없다.
보안에 위배되는 것 같지만 쿠버네티스에서는 자체 보안이 있으므로 이렇게 설정해도 문제없다.
daemonize no # 'yes'로 설정하면 안된다.
requirepass password # 💥password는 꼭 설정하세요. 서버나 PC가 인터넷에 연결되어 있다면 개발환경이라도 꼭 password를 설정하세요. 레디스 해킹은 🕵️사람(해커)가 하지 않고 💻 프로그램이 24시간 돌면서 해킹합니다. Password가 없다면 개발용으로 몇 분 간만 띄워놓고 있어도 바로 해킹당할 수 있습니다.
자세한 내용은 여기를 참조하세요. 🔗 Redis Hacking
users.acl을 설정했을 경우 'requirepass'는 설정하지 않아도 됩니다.
masterauth password # 꼭 설정하세요.
cluster-node-timeout 3000 # 노드 다운 감지 시간(3000ms(3sec)): 3초로 설정합니다.
cluster-announce-hostname, cluster-announce-human-nodename 두 항목은 파드 생성 시 statefulset.yaml 파일 initContainer:command에서 파드 이름을 구해서 동적 주입합니다. 따라서 여기서는 설정하지 않습니다.
echo "cluster-announce-hostname ${POD_FQDN}" >> /data/redis.conf
echo "cluster-announce-human-nodename ${POD_NAME}" >> /data/redis.conf
users.acl: 90~91라인 설정. Password('#0cbc...' 64자리)는 별도로 설정해야 합니다.
자세한 내용은 여기를 참조하세요. 🔗 ACL

💾 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	    # 📍 파일 생성 필요  
  34	    aclfile /data/users.acl
  35	    # [REPLICATION]
  36	    # Redis-Cluster에서는 replica-priority 값은 사용되지 않습니다. 
  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	    # 노드 다운 감지 시간: 3000ms(3sec)
  69	    cluster-node-timeout 3000
  70	    # 마스터가 가지고 있어야하는 최소한의 복제(슬레이브) 개수
  71	    cluster-migration-barrier 1
  72	    # yes: 복제가 없는 마스터 노드 중 어느 하나라도 다운되면 클러스터가 
  73	    #      다운되어 클라이언트의 어떤 오퍼레이션도 동작하지 않는다.
  74	    # no:  복제가 없는 마스터 노드가 다운되더라도 클러스터는 다운되지 않고 살아있다.   
  75	    #      다운된 노드의 슬롯은 에러가 나지만 다른 노드의 슬롯에는 데이터가 
  76	    #      정상적으로 입력/수정/삭제/조회된다.
  77	    cluster-require-full-coverage no
  78	    # yes: 클러스터가 다운(Down) 상태이더라도 읽기 허용: default no
  79	    cluster-allow-reads-when-down yes
  80	    # yes: 클러스터가 다운(Down) 상태이더라도 Pub/Sub 샤드(Shard) 허용: default yes
  81	    cluster-allow-pubsubshard-when-down yes
  82	    # 📍 아래 두 항목은 파드 실행 시 initContainer/Command에서 파드별 
  83	    #    DNS 및 이름으로 동적 주입됨
  84	    # 🚩 IP 대신 Headless Service DNS 이름 사용
  85	    cluster-announce-hostname ""
  86	    # 🚩 노드 ID는 `e4a7f10...`과 같은 40자리 난수(Hash) 형태 
  87	    #    -> 쿠버네티스의 파드 이름(redis-cluster-0) 사용
  88	    cluster-announce-human-nodename ""
  89	
  90	  users.acl: |
  91	    user default on sanitize-payload #0cbc... ~* &* +@all

여기 제시한 값은 레디스게이트에서 1백여 이상 사이트에 설치/운영할 때 90% 이상 적용된 redis.conf 값입니다. (maxmemory 값은 데이터 사이즈에 맞게 조정하세요)

💻 물리서버/VM의 경우 아래 몇 가지 값을 수정해서 사용하세요.

bind 114.x.y.z 127.0.0.1 -::1 -> IP 지정
protected-mode yes
port -> default 💥6379 port는 해킹의 주요 타겟입니다. 반드시 다른 포트를 사용하세요.
daemonize yes
dir /app/redis -> pidfile, logfile 등도 이 dir에 위치
aclfile /app/redis/users.acl -> 사용자별로 권한 부여 가능: 사용 권장
#maxmemory <bytes> -> 주석처리(default)
① 레디스 전용 서버일 경우 시스템 메모리의 50%~90%까지 지정
② 메모리 여유가 충분하다면: 시스템 메모리가 16GB인데 레디스가 사용하는 메모리가 1~2GB이면 (현실적으로) 굳이 설정하지 않아도 됨
③ 💥 레디스가 시스템 메모리를 모두 사용하면 OS(Linux)에서 레디스 프로세스를 kill 시킵니다.
#cluster-announce-hostname "" -> 주석처리(default)
#cluster-announce-human-nodename "" -> 주석처리(default)

🟢 [2단계] 서비스(Service) 설정: redis-cluster-service.yaml

종류(kind): Service
이름(metadata:name): redis-cluster-service
⚠️ 이름은 소문자(a-z), 숫자(0-9), 하이픈(`-`)만 사용하도록 엄격하게 제한(대문자 사용 불가)
Service 설정 파일입니다. 파드들의 IP가 바뀌더라도 고정된 도메인 네임(FQDN:Full Qualified Domain Name)으로 개별 Redis에 접근할 수 있도록 미리 네트워크 주소판을 만들어주는 역할을 합니다.

🧑‍💻 주요 값 설명

clusterIP: None # 📍'None'으로 설정(개별 파드 DNS 단독 식별용)
port: 18504 # 레디스 포트
port: 28504 # 레디스 클러스터 포트

💾 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   # Headless Service 유지 (개별 파드 DNS 단독 식별용)
  9	  ports:
 10	  - port: 18504
 11	    name: redis-port    # 클라이언트 응답 및 데이터 통신 포트
 12	  - port: 28504
 13	    name: cluster-bus-port # ⭐ Redis Cluster 노드 간 가십(Gossip) 통신 전용 포트
 14	  selector:
 15	    app: redis-cluster

🟢 [3단계] 레디스 파드 생성 명세서: redis-cluster-statefulset.yaml

레디스 파드(replicas, initContainers, memory, pvc(disk volume)) 생성 명세서 파일입니다.

종류(kind): StatefulSet
이름(metadata:name): redis-cluster
⚠️ 이름은 소문자(a-z), 숫자(0-9), 하이픈(`-`)만 사용하도록 제한 (대문자 사용 불가)
이 이름으로 redis-cluster-0,1,2과 같이 숫자를 붙여 파드 이름을 짓습니다.
파드이름과 serviceName을 이용해서 아래와 같이 FQDN(Full Qualified Domain Name)을 만듭니다.
redis-cluster-0.redis-cluster-service.default.svc.cluster.local
레디스마다 고유한 FQDN 이름으로 레디스 간 또는 레디스와 App간에 통신할 수 있습니다.
IP가 변경되면 변경된 IP를 FQDN에 연결(설정)합니다.

🧑‍💻 주요 값 설명

configMap: name: redis-cluster-config (1단계 레디스 설정과 연결)
serviceName: redis-cluster-service (2단계 Service와 연결)
replicas: 6 # Redis 파드 6개 생성, Master(3개), Replica(3개)로 역할을 나누는 것은 Redis-Cluster 구성(생성) 시 결정된다.
image: redis:8.8.2 # 2026년 08월 17일(월) 발표된 버전 8.8.2 사용
imagePullPolicy: IfNotPresent # 로컬 이미지 사용
command 스크립트: 1단계 ConfigMap의 설정 파일 복사 및 동적 설정
volumeMounts: mountPath: /data: 레디스에서 사용/관리하는 모든 파일 (redis.conf, users.acl, aof files 등)을 저장합니다.

💾 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  # 로컬 이미지 사용 
  20	        command:
  21	        - /bin/sh
  22	        - -c
  23	        - |
  24	          # 1. ConfigMap에서 읽기 전용 redis.conf를 쓰기 가능한 /data 로 복사
  25	          cp /readonly-config/redis.conf /data/redis.conf
  26	          chmod 600 /data/redis.conf
  27	
  28	          # 2. users.acl 파일 복사 및 권한 부여
  29	          cp /readonly-config/users.acl /data/users.acl
  30	          chmod 600 /data/users.acl
  31	          
  32	          # 3. Redis Cluster 동적 FQDN 및 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	        # 📍 파드 메모리 및 CPU 자원 설정
  59	        resources:
  60	          requests:
  61	            memory: "1Gi"      # 최소 보장 메모리 (노드 스케줄링 기준)
  62	            cpu: "500m"        # 최소 보장 CPU (0.5 코어)
  63	          limits:
  64	            memory: "1.2Gi"    # 최대 사용 가능 메모리 한계치 (초과 시 OOM)
  65	            cpu: "1000m"       # 최대 사용 가능 CPU (1 코어)
  66	      containers:
  67	      - name: redis
  68	        image: redis:8.8.1
  69	        imagePullPolicy: IfNotPresent  # 로컬 이미지 사용
  70	        # 🚩 레디스 실행 전 /data/.bashrc를 /root/로 복사 후 레디스 서버 실행
  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	        # 🚩 추가된 Redis Cluster Bus (Gossip) 통신 포트
  86	        - containerPort: 28504 
  87	          name: cluster-port
  88	        volumeMounts:
  89	        - name: redis-data
  90	          mountPath: /data
  91	        # 컨테이너 내부에 Host OS의 타임존 마운트
  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	      # Host OS의 /etc/localtime 파일 참조
 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: 스크립트 설명

① ConfigMap에서 읽기 전용 redis.conf를 쓰기 가능한 /data 로 복사

레디스는 'config rewrite' 명령으로 conf 파일을 다시 쓸수도 있고, Master-Replica 역할이 변경될 경우 'replicaof' 지시자가 다시 쓰여집니다. 그래서 redis.conf 피일은 read-write 가능한 dir에 있어야 합니다.
cp /readonly-config/redis.conf /data/redis.conf chmod 600 /data/redis.conf
② users.acl 파일 복사 및 권한 부여

cp /readonly-config/users.acl /data/users.acl chmod 600 /data/users.acl
③ Redis Cluster 동적으로 FQDN를 구해서 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: 스크립트 설명

④ 🚩 .bashrc 파일에 사용하기 편리한 몇 가지 alias 지정

cat << 'EOF' >> /root/.bashrc alias cls='clear' alias ll='ls -l --color=auto' alias ls='ls --color=auto' EOF
'--color=auto'를 지정하면 파일명이 아래와 같이 몇 가지 색으로 구분된다.
dir file: redis-sentinel-model
exec file: cluster_create.sh
tar file: file redis-8.8.2.tar
⑤ redis.tar 파일 기준 시간이 UTC(영국) 이다. 한국 시간(host OS time)으로 변경한다.

# 컨테이너 내부에 Host OS의 타임존 마운트 - name: tz-config mountPath: /etc/localtime readOnly: true # Host OS의 /etc/localtime 파일 참조 - name: tz-config hostPath: path: /etc/localtime

➡ 이제 준비되었으니 파드를 생성하러 갑시다.

<< Kubernetes 레디스 준비 ③	K8s Redis-Cluster 구축 ② >>

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