이번 내용에서는 Kubernetes 환경에서 Redis Cluster를 어떻게 구성하고, 각 구성요소가 어떤 역할을 하는지 초보자 관점에서 단계별로 설명합니다.
핵심은 단순히 Redis Pod를 여러 개 실행하는 것이 아니라,
StatefulSet → ConfigMap → PVC → Headless Service → Cluster 초기화 → 애플리케이션 연결
이 전체 흐름을 이해하는 것입니다.
1단계. 전체 Redis Cluster 구조 이해하기
구성하려는 기본 구조는 다음과 같습니다.
Spring Boot
│
│ Redis 요청
▼
┌───────────────────────────────┐
│ Kubernetes Cluster │
│ │
│ Redis-0 Redis-1 Redis-2 │
│ Master Master Master │
│ │ │ │ │
│ PVC-0 PVC-1 PVC-2 │
└───────────────────────────────┘
Redis 한 대만 운영할 경우 해당 Redis에 장애가 발생하면 이를 사용하는 애플리케이션도 영향을 받을 수 있습니다.
Redis Cluster에서는 Redis를 여러 노드로 구성하고 데이터를 여러 노드에 분산합니다.
하지만 여기서 중요한 점이 있습니다.
현재 예제는 다음 설정을 사용합니다.
--cluster-replicas 0
따라서 구조는 다음과 같습니다.
Redis-0 = Master
Redis-1 = Master
Redis-2 = Master
Replica = 없음
즉 Redis Cluster는 맞지만 완전한 고가용성(HA) 구조는 아닙니다.
Master가 장애 났을 때 대신 동작할 Replica가 없기 때문입니다.
2단계. Kubernetes 구성요소 전체 보기
Redis Cluster를 구성하기 위해 다음 요소들을 사용합니다.
구성요소역할쉽게 표현하면
| StatefulSet | Redis Pod 생성 및 관리 | Redis 서버 관리자 |
| PVC | Redis 데이터 저장 | Redis용 디스크 |
| ConfigMap | redis.conf 관리 | Redis 설정 파일 |
| Headless Service | Redis Pod별 DNS 제공 | Redis 노드 주소록 |
| Job | Redis Cluster 초기 생성 | Redis 노드 묶기 |
| Kustomize | 여러 YAML 관리 | YAML 묶음 관리 도구 |
그리고 애플리케이션에서는 일반적으로 Lettuce 같은 Redis Client를 통해 Redis Cluster에 접속합니다.
Spring Boot
│
Lettuce
│
▼
Redis Cluster
│
┌────────────┼────────────┐
▼ ▼ ▼
Redis-0 Redis-1 Redis-2
│ │ │
▼ ▼ ▼
PVC-0 PVC-1 PVC-2
중요한 것은 Redis Pod 세 개가 하나의 PVC를 공유하지 않는다는 것입니다.
Redis-0 → PVC-0
Redis-1 → PVC-1
Redis-2 → PVC-2
각 Redis 노드는 자기 데이터를 자기 Volume에 저장합니다.
3단계. 왜 Deployment가 아니라 StatefulSet인가?
Redis는 데이터를 저장하는 Stateful 애플리케이션입니다.
Deployment는 일반적인 Web/WAS처럼 Pod 이름이나 Identity가 크게 중요하지 않은 애플리케이션에 많이 사용합니다.
예를 들어 Deployment Pod 이름은 다음처럼 만들어질 수 있습니다.
redis-784fd76c9-x28jx
redis-784fd76c9-a91ks
redis-784fd76c9-p39ls
반면 StatefulSet은 순번이 붙습니다.
dev-redis-token-0
dev-redis-token-1
dev-redis-token-2
Pod가 다시 생성되어도 논리적인 이름이 유지됩니다.
또한 각 Pod마다 별도의 PVC를 연결할 수도 있습니다.
따라서 Redis, MongoDB 같은 상태 저장형 애플리케이션은 StatefulSet과 궁합이 좋습니다.
4단계. StatefulSet 핵심 설정 이해하기
예를 들어 다음과 같은 설정이 있습니다.
kind: StatefulSet
spec:
serviceName: "dev-redis-token"
replicas: 3
replicas: 3은 Redis Pod를 세 개 실행하겠다는 의미입니다.
결과적으로 다음과 같이 생성됩니다.
dev-redis-token-0
dev-redis-token-1
dev-redis-token-2
Redis 컨테이너를 실행할 때는 다음과 같이 redis.conf를 지정합니다.
command:
- redis-server
- "/redis-config/redis.conf"
전체 연결 관계는 다음과 같습니다.
ConfigMap
│
▼
redis.conf
│
▼
Redis Server 실행
즉 Redis 설정을 컨테이너 이미지에 직접 넣는 것이 아니라 ConfigMap으로 외부에서 관리하는 구조입니다.
5단계. Redis Cluster의 두 가지 포트
Redis Cluster에서는 보통 두 종류의 통신이 필요합니다.
ports:
- containerPort: 6379
- containerPort: 16379
5.1 6379
일반적인 Redis Client 통신에 사용합니다.
Spring Boot
│
│ TCP 6379
▼
Redis
5.2 16379
Redis Cluster 노드 간 통신에 사용됩니다.
Redis-0 ───── Redis-1
│ │
└──── Redis-2
노드들은 Cluster Bus를 통해 서로 클러스터 상태, 장애 정보 등을 교환합니다.
Redis 기본 포트가 6379라면 Cluster Bus 포트는 일반적으로 여기에 10000을 더한 16379를 사용합니다.
6단계. PVC가 필요한 이유 💾
StatefulSet에서는 volumeClaimTemplates를 이용해 Pod마다 PVC를 만들 수 있습니다.
예를 들면 다음과 같습니다.
volumeClaimTemplates:
- metadata:
name: redis-data
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
Redis Pod가 세 개라면 개념적으로 다음처럼 생성됩니다.
Redis-0
│
▼
PVC-0
Redis-1
│
▼
PVC-1
Redis-2
│
▼
PVC-2
PVC는 Redis 컨테이너의 /data 디렉터리에 연결할 수 있습니다.
volumeMounts:
- name: redis-data
mountPath: /data
따라서 Redis 입장에서는 /data에 파일을 저장하지만 실제 데이터는 Kubernetes Storage에 보관됩니다.
Redis
│
▼
/data
│
▼
PVC
│
▼
PV / Storage
7단계. ConfigMap과 redis.conf
ConfigMap에는 Redis 설정 파일인 redis.conf를 저장할 수 있습니다.
대표적인 설정은 다음과 같습니다.
maxmemory 2gb
maxmemory-policy allkeys-lru
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes
dir /data
하나씩 살펴보겠습니다.
7.1 maxmemory 2gb
Redis가 사용할 수 있는 메모리를 제한합니다.
Redis Memory
0 GB
│
├── 500 MB
├── 1 GB
├── 1.5 GB
└── 2 GB ← 최대
7.2 maxmemory-policy allkeys-lru
Redis 메모리가 가득 찼을 경우 오래 사용되지 않은 Key를 제거하는 정책입니다.
Redis Memory FULL
↓
최근 사용 Key
최근 사용 Key
오래 사용하지 않은 Key ← 제거 후보
7.3 cluster-enabled yes
Redis Cluster 기능을 활성화합니다.
Redis
↓
cluster-enabled yes
↓
Redis Cluster Mode
7.4 cluster-config-file nodes.conf
Redis Cluster의 노드 및 슬롯 정보를 저장하는 파일입니다.
Redis Cluster
│
▼
nodes.conf
이 파일은 관리자가 직접 편집하는 일반 설정 파일이라기보다 Redis가 클러스터 상태를 기록·관리하는 내부 파일에 가깝습니다.
7.5 cluster-node-timeout 5000
Redis Cluster에서 노드 장애 판단 등에 사용되는 timeout 기준값입니다.
5000 ms
=
5초
8단계. AOF는 무엇인가? 💾
다음 설정이 있습니다.
appendonly yes
이것이 AOF(Append Only File) 활성화입니다.
AOF는 Redis에서 발생하는 데이터 변경 명령을 디스크에 기록하는 영속화 방식입니다.
예를 들어 다음과 같은 명령이 발생했다고 가정합니다.
SET user:1 Kim
SET user:2 Lee
DEL user:3
Redis는 이러한 변경 작업을 AOF에 기록할 수 있습니다.
구조는 다음과 같습니다.
Application
│
▼
Redis
│
├── Memory
│
└── AOF
│
▼
/data
│
▼
PVC
Redis Pod가 재시작되더라도 PVC에 AOF 데이터가 남아 있으면 데이터를 다시 복구할 수 있습니다.
9단계. Headless Service가 필요한 이유 🌐
일반 Kubernetes Service는 하나의 가상 IP를 제공합니다.
Service
10.10.10.100
│
┌───────┼───────┐
▼ ▼ ▼
Redis-0 Redis-1 Redis-2
애플리케이션 입장에서는 뒤에 Redis가 몇 대인지 크게 신경 쓰지 않고 Service 주소로 접속할 수 있습니다.
하지만 Redis Cluster에서는 각 Redis Node를 개별적으로 식별할 수 있어야 합니다.
따라서 다음과 같이 설정합니다.
clusterIP: None
이것이 Headless Service입니다.
Headless Service는 Service IP 하나로 트래픽을 로드밸런싱하는 것이 핵심이 아니라 각 Pod를 DNS를 통해 직접 찾을 수 있게 해줍니다.
10단계. Headless Service 사용 시 DNS
예를 들어 Redis Pod가 다음과 같다고 하겠습니다.
dev-redis-token-0
dev-redis-token-1
dev-redis-token-2
Service가 다음과 같고,
dev-redis-token
Namespace가 다음이라면,
dev-db
각 Pod는 다음과 같은 DNS를 사용할 수 있습니다.
dev-redis-token-0.dev-redis-token.dev-db.svc.cluster.local
dev-redis-token-1.dev-redis-token.dev-db.svc.cluster.local
dev-redis-token-2.dev-redis-token.dev-db.svc.cluster.local
구조를 단순화하면 다음과 같습니다.
Pod이름.Service이름.Namespace.svc.cluster.local
즉 Redis Pod IP가 변경되더라도 안정적인 DNS 이름을 이용해 접근할 수 있습니다.
11단계. Redis Pod 3개 ≠ Redis Cluster
StatefulSet으로 Redis Pod를 세 개 실행했다고 하겠습니다.
Redis-0
Redis-1
Redis-2
이 상태에서는 단순히 독립적인 Redis Server 세 개가 실행된 것에 불과합니다.
Redis Server
Redis Server
Redis Server
아직 서로 같은 Redis Cluster 구성원인지 모릅니다.
따라서 별도의 Cluster 초기화 과정이 필요합니다.
이때 사용하는 대표적인 명령이 다음과 같습니다.
redis-cli --cluster create
12단계. Redis Cluster 초기화 Job
Kubernetes Job을 이용하여 Redis Cluster 생성 명령을 실행할 수 있습니다.
예를 들면 다음과 같습니다.
redis-cli --cluster create \
dev-redis-token-0....:6379 \
dev-redis-token-1....:6379 \
dev-redis-token-2....:6379 \
--cluster-replicas 0
동작 흐름은 다음과 같습니다.
Redis-0
Redis-1
Redis-2
↓
redis-cli --cluster create
↓
Redis Cluster 생성
Job은 이 작업을 한 번 실행하고 완료되는 용도로 사용할 수 있습니다.
13단계. --cluster-replicas 0 의미
이 설정은 굉장히 중요합니다.
--cluster-replicas 0
의 의미는:
Master마다 Replica를 만들지 않는다.
입니다.
따라서 최종 구조는 다음과 같습니다.
Master-0
Master-1
Master-2
Replica = 0
Redis Cluster의 16,384개 Hash Slot을 세 Master가 나눠 담당합니다.
예를 들어:
Master-0
Slot 0 ~ 5460
Master-1
Slot 5461 ~ 10922
Master-2
Slot 10923 ~ 16383
하지만 Master-1에 장애가 발생했다고 해보겠습니다.
Master-0 Master-1 Master-2
✅ ❌ ✅
│
▼
Replica 없음
Master-1을 대신할 Redis가 없습니다.
따라서 해당 Master가 담당하고 있던 Slot을 사용할 수 없어 서비스에 문제가 생길 수 있습니다.
14단계. 운영 환경에서는 3 Master + 3 Replica 검토
실제 운영 환경에서는 다음과 같은 구성을 많이 검토합니다.
Redis Cluster
Master-0 Master-1 Master-2
│ │ │
│ │ │
Replica-0 Replica-1 Replica-2
총 Redis Node는:
Master 3개
+
Replica 3개
=
6개
가 됩니다.
예를 들어 Master-1이 장애 났다면:
Master-1
❌
│
▼
Replica
│
▼
Master 승격
Replica가 새로운 Master로 승격되어 장애에 대응할 수 있습니다.
15단계. Redis Cluster의 핵심 — Hash Slot
Redis Cluster에서는 데이터를 여러 Redis 서버에 분산하기 위해 Hash Slot을 사용합니다.
Redis Cluster에는 총:
16,384개 Hash Slot
이 있습니다.
Key가 들어오면 다음 방식으로 Slot을 계산합니다.
Key
│
▼
CRC16
│
▼
% 16384
│
▼
Hash Slot
공식적인 개념은 다음과 같습니다.
HASH_SLOT = CRC16(Key) mod 16384
즉 Key마다 담당 Slot이 결정됩니다.
16단계. Hash Slot 실제 예제
다음 데이터를 저장한다고 하겠습니다.
SET user:123 "Kim"
Redis Cluster에서 Key를 계산합니다.
user:123
│
▼
CRC16
│
▼
% 16384
│
▼
Slot 8000
현재 Slot 분배가 다음과 같다고 해보겠습니다.
Redis-0
Slot 0 ~ 5460
Redis-1
Slot 5461 ~ 10922
Redis-2
Slot 10923 ~ 16383
Slot 8000은 Redis-1 영역입니다.
따라서 실제 데이터는 다음 흐름으로 처리됩니다.
SET user:123
↓
Hash Slot 계산
↓
Slot 8000
↓
Redis-1
↓
Redis-1의 데이터
이것이 Redis Cluster의 Sharding 개념입니다.
17단계. Redis Cluster를 사용하는 이유
Standalone Redis는 모든 데이터를 한 Redis가 처리합니다.
Redis
│
┌──────┼──────┐
▼ ▼ ▼
Key A Key B Key C
데이터가 계속 증가하면 한 Redis의 CPU, Memory 성능이 한계에 도달할 수 있습니다.
Redis Cluster에서는 데이터를 여러 Redis Node로 분산할 수 있습니다.
Key
│
Hash Slot 계산
│
┌───────┼───────┐
▼ ▼ ▼
Redis-0 Redis-1 Redis-2
즉 Redis Cluster의 가장 큰 특징 중 하나는 Scale-Out과 데이터 Sharding입니다.
18단계. Spring Boot에서 Redis Cluster 연결
Spring Boot에서는 Redis Cluster Node 목록을 설정할 수 있습니다.
예:
spring:
data:
redis:
cluster:
nodes: ${REDIS_CLUSTER_NODES}
환경 변수에는 다음과 같이 여러 Redis Node를 지정합니다.
Redis-0:6379,
Redis-1:6379,
Redis-2:6379
전체 구조는 다음과 같습니다.
Spring Boot
│
▼
Lettuce
│
▼
Redis Cluster
│
┌───┼───┐
▼ ▼ ▼
R0 R1 R2
Spring Boot는 일반적으로 Lettuce와 같은 Redis Client를 통해 Cluster Topology를 파악하면서 데이터를 처리합니다.
19단계. Lettuce Topology Refresh
Kubernetes에서는 Redis Pod가 재시작될 수 있습니다.
Redis Pod
│
▼
재시작
│
▼
IP 변경 가능
Redis Cluster Node 상태도 변경될 수 있습니다.
그래서 Lettuce는 Cluster Topology Refresh 기능을 사용할 수 있습니다.
예를 들어:
.enablePeriodicRefresh(Duration.ofSeconds(30))
이라고 하면 주기적으로 Redis Cluster 구성을 확인합니다.
Lettuce
│
│ 30초마다
▼
Redis Cluster
"현재 Cluster 구성이 어떻게 되어 있지?"
Kubernetes처럼 Pod 상태가 변화할 수 있는 환경에서는 중요한 기능입니다.
20단계. ArgoCD PostSync Hook
ArgoCD를 사용하면 Redis Cluster 초기화 Job을 배포 과정에 포함할 수도 있습니다.
예:
argocd.argoproj.io/hook: PostSync
의도하는 흐름은 다음과 같습니다.
ArgoCD Sync
│
▼
ConfigMap
Service
StatefulSet
│
▼
Redis Pod 실행
│
▼
PostSync
│
▼
Redis Cluster Init Job
│
▼
redis-cli --cluster create
즉 Kubernetes 리소스가 배포된 후 Redis Cluster 생성 작업을 자동화하려는 것입니다.
21단계. Kustomize 역할
Redis Cluster를 구성하다 보면 YAML 파일이 여러 개 생깁니다.
예를 들어:
redis-statefulset.yaml
redis-service.yaml
redis-configmap.yaml
redis-cluster-init-job.yaml
각각 실행하면 관리하기 불편할 수 있습니다.
kubectl apply -f redis-statefulset.yaml
kubectl apply -f redis-service.yaml
kubectl apply -f redis-configmap.yaml
kubectl apply -f redis-cluster-init-job.yaml
Kustomize를 사용하면 다음처럼 묶어서 관리할 수 있습니다.
resources:
- redis-cluster-init-job.yaml
- redis-configmap.yaml
- redis-service.yaml
- redis-statefulset.yaml
즉 Kustomize는 Redis 자체 기능이 아니라 Kubernetes YAML을 효율적으로 관리하는 도구입니다.
22단계. 전체 구조 한눈에 보기 🔎
ConfigMap
│
redis.conf
│
▼
StatefulSet
│
┌───────────┼───────────┐
▼ ▼ ▼
Redis-0 Redis-1 Redis-2
│ │ │
▼ ▼ ▼
PVC-0 PVC-1 PVC-2
▲ ▲ ▲
│ │ │
└──── Headless Service ─┘
│
│
Pod별 DNS 제공
│
▼
Cluster Init Job
│
▼
redis-cli --cluster create
│
▼
Redis Cluster
│
▼
16,384 Hash Slot
│
┌─────────┼─────────┐
▼ ▼ ▼
Redis-0 Redis-1 Redis-2
▲
│
Lettuce
│
▲
Spring Boot
이 구조를 이해하는 것이 Kubernetes Redis Cluster의 핵심입니다.
23단계. 구성요소 중요도 정리
중요도구성핵심 역할
| ⭐⭐⭐⭐⭐ | StatefulSet | Redis Pod의 안정적인 Identity |
| ⭐⭐⭐⭐⭐ | Headless Service | 각 Redis Node의 안정적인 DNS |
| ⭐⭐⭐⭐⭐ | PVC | Redis 데이터 영속성 |
| ⭐⭐⭐⭐⭐ | Hash Slot | Redis Cluster 데이터 분산 |
| ⭐⭐⭐⭐⭐ | Replica | 장애 대응 및 HA |
| ⭐⭐⭐⭐ | ConfigMap | redis.conf 외부 관리 |
| ⭐⭐⭐⭐ | AOF | Redis 데이터 영속화 |
| ⭐⭐⭐⭐ | Init Job | Redis Cluster 생성 |
| ⭐⭐⭐ | Kustomize | Kubernetes YAML 관리 |
| ⭐⭐⭐ | Lettuce | 애플리케이션과 Redis 연결 |
24단계. 운영 환경에서는 추가로 고려할 사항 ⚠️
학습용으로는 3 Master만으로 Redis Cluster 구조를 이해할 수 있습니다.
하지만 실제 운영 환경에서는 다음 항목을 추가로 검토해야 합니다.
Redis Master × 3
Redis Replica × 3
+
Pod Anti-Affinity
+
PodDisruptionBudget
+
PVC / Storage 성능
+
AOF / RDB 정책
+
CPU / Memory
Request / Limit
+
Readiness Probe
Liveness Probe
+
Monitoring / Alert
+
Backup
+
Authentication / ACL
+
TLS
특히 중요한 점은:
3 Master + 0 Replica
구성을 단순히 “Redis가 이중화됐다”고 생각하면 안 된다는 것입니다.
Redis Cluster를 구성하여 데이터는 분산되어 있지만 Master를 대신할 Replica가 없으므로 Master 장애에 대한 자동 복구 능력이 부족합니다.
25단계. 지금까지 배운 구성요소 연결하기
지금까지 각각 따로 보았던 구성요소는 실제로 다음처럼 연결됩니다.
ConfigMap
│
└── redis.conf
│
▼
StatefulSet
│
├── Redis Pod
│
└── PVC
│
└── /data
│
├── AOF
└── nodes.conf
Headless Service
│
└── Redis Pod별 DNS
Cluster Init Job
│
└── redis-cli --cluster create
│
▼
Redis Cluster
│
└── 16,384 Hash Slots
Spring Boot
│
└── Lettuce
│
▼
Redis Cluster
핵심만 기억하면 다음과 같습니다.
ConfigMap
→ Redis 설정
StatefulSet
→ Redis Pod 관리
PVC
→ Redis 데이터 저장
Headless Service
→ Redis Pod별 고정 DNS 제공
Cluster Init Job
→ 독립적인 Redis들을 하나의 Cluster로 연결
Hash Slot
→ 데이터를 Redis Node별로 분산
Replica
→ Master 장애 시 대신 동작
Lettuce
→ 애플리케이션에서 Redis Cluster 접근
26단계. 운영형 구조로 확장하면
실제 운영을 생각한다면 다음 단계는 3 Master + 3 Replica Redis Cluster입니다.
예를 들어 Kubernetes Worker Node가 세 대라면 개념적으로 다음과 같이 분산할 수 있습니다.
Worker Node-1
├── Master-0
└── Replica-1
Worker Node-2
├── Master-1
└── Replica-2
Worker Node-3
├── Master-2
└── Replica-0
왜 Master-0과 Replica-0을 같은 Worker Node에 넣지 않는지도 중요합니다.
Worker-1 장애
Master-0 ❌
Replica-0 ❌
처럼 동시에 장애가 발생하는 것을 막기 위해서입니다.
따라서 다음 단계에서는 Pod Anti-Affinity를 이용하여 Master와 해당 Replica를 서로 다른 Worker Node에 배치하는 방법까지 이해하면 Redis Cluster의 실제 운영 설계로 연결할 수 있습니다.
쿠버네티스 환경에서 Redis Cluster 구축하기
MSA 기반 프로젝트를 진행하면서, 각 마이크로서비스가 인증 처리를 위해 하나의 레디스를 공유하도록 구성할 필요가 있었습니다. 하지만 단일 레디스로는 장애 발생 시 전체 서비스에 영향을
velog.io
'J-H-T > Redis' 카테고리의 다른 글
| [REDIS - 1단계] RedisShake가 무엇이고 K8s에서 어디에 위치하는가 ! (0) | 2026.08.14 |
|---|
댓글