Redis Cluster 구축 방법 — 6노드 설정부터 운영까지

Redis Cluster 기본 개념

16384개의 해시 슬롯을 여러 Master 노드에 분배합니다.

Master1: Slot 0 ~ 5460
Master2: Slot 5461 ~ 10922
Master3: Slot 10923 ~ 16383

각 Master에 Replica 1개 → 총 6노드 최소 구성

키는 HASH_SLOT = CRC16(key) % 16384 로 슬롯이 결정됩니다.

1. 설치 및 노드 설정

6개 서버 (또는 VM/컨테이너) 준비: 포트 7001~7006

# redis-7001.conf (나머지도 포트만 변경)
port 7001
bind 0.0.0.0
cluster-enabled yes
cluster-config-file nodes-7001.conf
cluster-node-timeout 5000
appendonly yes
appendfsync everysec
maxmemory 4gb
maxmemory-policy allkeys-lru
protected-mode no

# 각 노드 시작
redis-server redis-7001.conf &
redis-server redis-7002.conf &
redis-server redis-7003.conf &
redis-server redis-7004.conf &
redis-server redis-7005.conf &
redis-server redis-7006.conf &

2. 클러스터 생성

redis-cli --cluster create \
  192.168.1.1:7001 \
  192.168.1.2:7002 \
  192.168.1.3:7003 \
  192.168.1.4:7004 \
  192.168.1.5:7005 \
  192.168.1.6:7006 \
  --cluster-replicas 1

# 앞의 3개 → Master, 뒤의 3개 → 각 Master의 Replica
# --cluster-replicas 1 = Master당 Replica 1개

>>> Performing hash slots allocation on 6 nodes...
Master[0] -> Slots 0 - 5460
Master[1] -> Slots 5461 - 10922
Master[2] -> Slots 10923 - 16383
Adding replica 192.168.1.4:7004 to 192.168.1.1:7001
...
[OK] All 16384 slots covered.

3. 클러스터 상태 확인

# 클러스터 정보
redis-cli -c -h 192.168.1.1 -p 7001 cluster info

# 노드 목록
redis-cli -c -h 192.168.1.1 -p 7001 cluster nodes

# 슬롯 분배 확인
redis-cli --cluster check 192.168.1.1:7001

4. Docker Compose로 로컬 테스트 환경

# docker-compose.yml
version: '3.8'
services:
  redis-1: { image: redis:7-alpine, command: redis-server /etc/redis.conf, volumes: [./redis.conf:/etc/redis.conf], ports: ["7001:7001"] }
  redis-2: { image: redis:7-alpine, command: redis-server /etc/redis.conf --port 7002, ports: ["7002:7002"] }
  redis-3: { image: redis:7-alpine, command: redis-server /etc/redis.conf --port 7003, ports: ["7003:7003"] }
  redis-4: { image: redis:7-alpine, command: redis-server /etc/redis.conf --port 7004, ports: ["7004:7004"] }
  redis-5: { image: redis:7-alpine, command: redis-server /etc/redis.conf --port 7005, ports: ["7005:7005"] }
  redis-6: { image: redis:7-alpine, command: redis-server /etc/redis.conf --port 7006, ports: ["7006:7006"] }

docker-compose up -d
# 클러스터 초기화
docker exec redis-1 redis-cli --cluster create \
  redis-1:7001 redis-2:7002 redis-3:7003 \
  redis-4:7004 redis-5:7005 redis-6:7006 \
  --cluster-replicas 1 --cluster-yes

5. 클라이언트 연결

Spring Boot (Lettuce)

spring:
  data:
    redis:
      cluster:
        nodes:
          - 192.168.1.1:7001
          - 192.168.1.2:7002
          - 192.168.1.3:7003
        max-redirects: 3
      password: your-password
      lettuce:
        cluster:
          refresh:
            adaptive: true        # 토폴로지 변경 자동 감지
            period: 30s

Python (redis-py)

from redis.cluster import RedisCluster

rc = RedisCluster(
    startup_nodes=[
        {"host": "192.168.1.1", "port": 7001},
        {"host": "192.168.1.2", "port": 7002},
    ],
    decode_responses=True,
    skip_full_coverage_check=True,
)

rc.set("key", "value")
rc.get("key")

6. Hash Tag로 같은 슬롯에 키 배치

Multi-key 명령어(MGET, MSET, Pipeline)는 같은 슬롯에 있는 키만 가능합니다.

# 위험: 다른 슬롯에 배치될 수 있음
rc.mget("user:1:profile", "user:1:session")  # CROSSSLOT 오류 가능

# 안전: Hash Tag로 같은 슬롯 보장
rc.mget("{user:1}:profile", "{user:1}:session")
# CRC16("user:1") % 16384 → 같은 슬롯

7. 노드 추가 (온라인 확장)

# 새 Master 추가
redis-cli --cluster add-node \
  192.168.1.7:7007 \        # 새 노드
  192.168.1.1:7001           # 기존 클러스터 아무 노드

# 슬롯 재분배
redis-cli --cluster reshard 192.168.1.1:7001
# 이동할 슬롯 수 입력 → 새 노드 ID 입력 → all (전체에서 균등 이동)

# Replica 추가
redis-cli --cluster add-node \
  192.168.1.8:7008 \
  192.168.1.1:7001 \
  --cluster-slave \
  --cluster-master-id <master-node-id>

8. Failover 테스트

# Master 강제 종료 시뮬레이션
redis-cli -h 192.168.1.1 -p 7001 DEBUG SLEEP 30

# 다른 터미널에서 Replica가 승격되는지 확인
watch redis-cli --cluster check 192.168.1.1:7001

기본 cluster-node-timeout 5000 (5초) 후 Replica가 Master로 승격됩니다.

운영 체크리스트

• 모든 슬롯 커버 확인: cluster info | grep cluster_state:ok
• 각 Master에 최소 1개 Replica 확인
• maxmemory 설정 및 maxmemory-policy 확인
• 클라이언트 자동 재연결 + 토폴로지 갱신 설정
• Hash Tag 사용 규칙 팀 내 공유
• 정기적 Failover 테스트 (분기 1회)