Redis / Valkey 일상 운영과 장애 시나리오 (Cluster와 Sentinel)

설치 가이드가 아닙니다: 설치된 Redis Cluster나 Sentinel 기반 master/replica 구성을 일상적으로 관리하고, 문제가 생겼을 때 복구하기 위한 시나리오별 런북입니다(Redis 7.2, Redis 8, Valkey). Cluster: 상태 점검, 노드 추가/제거, rebalance/reshard, 수동 failover(FORCE/TAKEOVER 차이), 장애 노드 교체와 --cluster fix. Sentinel: 상태와 quorum, SENTINEL FAILOVER, 노드 추가/제거와 SENTINEL RESET, 설정 변경. 두 구성 모두 메모리 압박과 big/hot key 진단을 다룹니다. 무엇을 할지 모르겠다면 상태 점검부터 시작하십시오. 백업에서의 복원과 보안 강화는 별도의 Redis 가이드에 있습니다.

구성: Redis Cluster (master 3대 이상 + replica) 또는 Sentinel (master 1대 + replica + Sentinel 3대)

시나리오

• Cluster 상태 점검 (--cluster check, CLUSTER INFO / NODES) — 읽기 전용: 모든 slot이 할당되어 있는지, 노드들의 설정이 일치하는지, 다운(fail)된 노드나 replica 없는 master가 있는지 확인합니다. 무엇을 할지 확실하지 않다면 여기서 시작하십시오.
• Cluster에 노드 추가 (master 또는 replica) — 새 인스턴스(cluster-enabled yes, 빈 상태)가 준비됨: cluster에 master로 추가되어 slot을 받거나, 특정 master의 replica가 됩니다. 중단 없음.
• Cluster에서 노드 제거 (slot 비우기 + del-node) — Master 또는 replica를 퇴역시킴: master의 slot을 다른 master로 옮긴 뒤 노드를 cluster에서 제거합니다. 중단은 없으며, 이동 중에는 ASK 리다이렉션이 발생합니다.
• Slot 재분배 (rebalance / reshard) — Master 간 slot이나 메모리가 불균형하거나, 새 master가 slot을 받지 못했거나, 일정 수의 slot을 한 master에서 다른 master로 옮겨야 하는 경우.
• 수동 failover: replica를 master로 전환 (CLUSTER FAILOVER, FORCE, TAKEOVER) — Master 서버에 유지보수가 예정되어 있거나(계획, 데이터 손실 없음), master에 접근할 수 없는데 자동 failover가 일어나지 않은 경우(FORCE / TAKEOVER, 데이터 손실 위험).
• 장애 master / 노드 교체 (FORGET, 새 replica, --cluster fix) — 노드의 서버가 영구 유실됨: replica가 master로 승격되었다면 이전 노드를 forget시키고 새 replica를 추가합니다. Replica가 없었다면 slot이 주인 없이 남으므로 --cluster fix로 할당합니다(해당 slot의 데이터는 유실).
• Sentinel 상태: master, replica, Sentinel, quorum — 읽기 전용: Sentinel이 보는 master 주소, replica, 다른 Sentinel, CKQUORUM, 최근 failover 이벤트를 확인합니다. Sentinel 구성에서 무엇을 할지 확실하지 않다면 여기서 시작하십시오.
• Sentinel로 수동 failover (SENTINEL FAILOVER) — Master 서버에 유지보수 예정: Sentinel이 가장 적합한 replica를 master로 승격하고, 나머지 replica와 클라이언트를 새 master로 전환합니다. 중단은 1–2초이며, master가 동작 중이면 데이터 손실은 없습니다.
• Sentinel 환경에서 노드 추가 / 제거 / 교체 (SENTINEL RESET) — Replica나 Sentinel을 영구 제거했거나 새로 추가한 경우: 새 replica는 REPLICAOF로 연결하고, Sentinel의 이전 기록은 SENTINEL RESET으로 정리합니다.
• Quorum과 Sentinel 설정 변경 (SENTINEL SET) — Sentinel 수가 바뀌었거나 failover가 너무 늦게/너무 일찍 트리거되는 경우: quorum, down-after-milliseconds, failover-timeout, parallel-syncs를 모든 Sentinel에서 변경합니다.
• 메모리 압박: 사용량, fragmentation, eviction 진단 — used_memory가 maxmemory에 근접, 'OOM command not allowed' 오류, eviction 증가, RSS가 예상보다 크거나 replica/AOF 버퍼가 비대해진 경우. 진단은 읽기 전용이며 해결 방법은 따로 설명합니다.
• Big key와 hot key 찾기 (--bigkeys, --memkeys, --hotkeys) — 특정 노드의 메모리나 CPU가 다른 노드보다 높거나, 지연 급증이 있거나, DEL이 오래 걸리는 경우: 가장 크고 가장 많이 접근되는 키를 찾아 안전하게 정리합니다(UNLINK).

시작하기 전에

• 관리 서버에 …가 설치되어 있고(…와 함께 제공, /usr/bin/…), …… 인스턴스에…모든 cluster 노드에 클라이언트 포트와 cluster bus 포트(port + 10000) 모두로…Sentinel(…)과 Redis(…)에… 접근할 수 있습니다.
• … 비밀번호(requirepass / masterauth)를 알고 있습니다. 단계에서 입력을 요청하거나 REDIS_PASS 환경 변수에서 가져옵니다. ACL을 쓴다면 사용자에게 +@admin(cluster/sentinel 명령)과 +@keyspace 권한이 있어야 합니다.
• 변경 요청을 등록하고 애플리케이션 팀에 알렸습니다. Failover와 slot 이동은 클라이언트에 짧은 MOVED/ASK 리다이렉션이나 연결 끊김을 일으킬 수 있으며, cluster-aware 클라이언트는 이를 자동으로 따라갑니다.
• 새 인스턴스 …가 Redis Cluster 설치 가이드대로 준비되어 있습니다: 같은 … 버전, cluster-enabled yes, 같은 requirepass/masterauth, 빈 데이터 디렉터리(이전 nodes-.conf, RDB/AOF 없음), 방화벽에서 클라이언트 포트와 bus 포트(port + 10000) 개방.

가이드 단계

• 상태: slot 할당, 노드, 설정 일치 (읽기 전용) — Cluster 점검 (--cluster check) · 노드, 역할, replica 분포 표시 · 결과 해석
• 1. 진단: 새 노드가 비어 있고 접근 가능한가? — 새 노드와 cluster 점검
• 2. 적용: 노드 추가 — Cluster에 노드 추가 (--cluster add-node) · 새 master에 slot 분배 (rebalance) · 새 master의 replica 계획
• 3. 검증 — Cluster와 새 노드 검증
• 1. 진단: 노드가 master인가, slot이 있는가? — 제거할 노드의 역할과 slot 확인
• 2. 적용: slot 비우기 및 노드 제거 — Master의 slot을 다른 master로 이동 · Cluster에서 노드 제거 (--cluster del-node) · 제거한 서버의 서비스 비활성화
• 3. 검증 — Cluster 검증
• 1. 진단: 현재 분포 — Master별 slot, 키, 메모리
• 2. 적용 — …Slot 균등화 (rebalance)…Slot …개 이동 (reshard)…
• 1. 진단 — Replica의 역할과 master 연결 확인
• 2. 적용 — Failover 시작 (CLUSTER FAILOVER… FORCE… TAKEOVER…)
• 3. 검증 — 새 구성 검증
• 1. 진단: 유실 노드와 slot 할당 — Fail 상태 노드와 주인 없는 slot 확인
• 2. 적용: 유실 노드 forget — 모든 노드에서 유실 노드 forget (CLUSTER FORGET) · 주인 없는 slot 할당 (--cluster fix) · 새 노드를 replica로 추가
• 3. 검증 및 후속 작업 — Cluster 검증
• 상태: master, replica, Sentinel (읽기 전용) — Sentinel이 보는 master와 quorum · Replica와 다른 Sentinel 목록 표시 · Sentinel 로그에서 최근 failover 이벤트 검색
• 1. 진단 — Quorum과 replica 준비 상태 확인
• 2. 적용 — Failover 시작 (SENTINEL FAILOVER)
• 3. 검증 — 새 master와 replica 검증
• 1. 진단 — Sentinel이 알고 있는 replica와 Sentinel 수
• 2. 적용 — 새 replica를 master에 연결 · 제거할 replica의 서비스 중지 · 새 Sentinel 기동 · 제거할 Sentinel 중지 · 모든 Sentinel에서 SENTINEL RESET
• 3. 검증 — 수와 quorum 재확인
• 1. 진단 — 각 Sentinel의 현재 설정 확인
• 2. 적용 — 모든 Sentinel에서 … 값을 …로 변경
• 1. 진단: 메모리, 한도, eviction — 메모리 사용량과 한도 확인 (INFO memory) · MEMORY DOCTOR와 MEMORY STATS · 메모리 설정 확인
• 2. 해결 방안 — 상황별 해결
• 1. 진단: big key와 hot key — 유형별 가장 큰 키 (--bigkeys) · 메모리 기준 가장 큰 키 (--memkeys) · Hot key (--hotkeys) · 키의 크기와 유형 점검
• 2. 해결 — Big key 안전 삭제 (UNLINK)