Elasticsearch 일상 운영 및 장애 시나리오 (8.x / 9.x)

설치 가이드가 아닙니다. 설치된 Elasticsearch 8.x / 9.x cluster를 일상적으로 관리하고 문제가 생겼을 때 복구하기 위한 시나리오별 runbook입니다. 상태 점검과 allocation explain, 할당되지 않은 shard 해결(디스크, filtering, retry_failed, replica, 최후 수단 stale/empty primary), disk watermark, read_only_allow_delete 블록, node 추가와 안전한 제거, alias를 이용한 무중단 reindex, ILM과 rollover, _shrink / _split, snapshot에서 단일 index를 새 이름으로 복원하는 작업을 다룹니다. 무엇을 할지 모르겠다면 상태 점검부터 시작하십시오. snapshot repository 구성과 SLM, 보안 강화, 버전 업그레이드는 별도의 Elasticsearch 가이드에 있습니다.

구성: Elasticsearch 8.x / 9.x cluster(node 1–N개), TLS 및 인증 활성화

시나리오

• Cluster 상태: status, node, 할당되지 않은 shard, 디스크 — 읽기 전용: green/yellow/red, node 목록, 할당되지 않은(UNASSIGNED) shard와 그 원인(allocation explain), 디스크 사용량과 watermark, 대기 중인 작업. 무엇을 할지 확실하지 않으면 여기서 시작하십시오.
• 할당되지 않은(UNASSIGNED) shard 해결 (explain 기준) — cluster가 yellow 또는 red이고 shard가 할당되지 않습니다. allocation explain의 원인에 따라 디스크, allocation filtering, 재시도 한도(retry_failed), replica 수, 또는 최후 수단으로 이전 사본에서 primary를 할당합니다.
• Disk watermark 설정 확인 / 변경 — 디스크 사용량 때문에 shard가 이동하거나 할당되지 않습니다. watermark 임계값(low / high / flood_stage)을 일시적 또는 영구적으로 변경하거나 기본값으로 되돌립니다.
• index가 읽기 전용이 됨: read_only_allow_delete 블록 제거 — 쓰기가 'FORBIDDEN/12/index read-only / allow delete (api)' 또는 'TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark'로 거부됩니다. 먼저 디스크 공간을 확보한 뒤 블록을 제거합니다.
• cluster에 node 추가 (enrollment token) — 용량이 필요합니다. 새 서버에 Elasticsearch를 설치했고, enrollment token으로 cluster에 합류합니다. shard는 자동으로 재분배됩니다. 서비스 중단은 없습니다.
• node 안전하게 제거 (exclude, 비우기, 종료) — node를 퇴역시키거나 하드웨어를 교체합니다. allocation exclude로 shard를 다른 node로 옮기고, node가 비었는지 확인한 뒤, master-eligible이면 voting exclusion을 지정하고 종료합니다.
• Reindex: mapping/설정 변경을 위해 새 index와 alias로 무중단 전환 — mapping 필드 타입, analyzer, shard 수를 바꿔야 합니다. 새 index를 만들고 _reindex로 데이터를 복사한 뒤 alias를 새 index로 원자적으로 전환합니다.
• Index lifecycle (ILM) 및 rollover 구성 / 문제 해결 — 로그/시계열 index가 계속 커지거나 삭제되지 않습니다. ILM 정책(rollover + delete), index template, 초기 index(write alias)를 구성하고, 기존 정책이 진행되지 않는 이유를 explain으로 확인합니다.
• shard 수 조정: _shrink (줄이기) / _split (늘리기) — index의 shard 수를 잘못 정했습니다. 너무 작은 shard(oversharding)는 _shrink로 합치고, 너무 큰 shard는 _split으로 나눕니다. 전환은 alias로 합니다.
• snapshot에서 단일 index를 새 이름으로 복원 — index가 삭제되었거나 손상되었습니다. 운영 중인 index는 건드리지 않고 snapshot repository에서 해당 index만 새 이름(rename)으로 복원하며, 검증 후 alias로 서비스에 투입합니다.

시작하기 전에

• … (…)에 root 권한, curl, cluster의 HTTP CA 인증서(…)가 있고, elastic 사용자(또는 manage + index 권한이 있는 사용자)의 비밀번호를 알고 있습니다. API 호출은 HTTPS로 이 node에 보냅니다.
• 변경 요청이 등록되었고 애플리케이션 팀에 알렸습니다. shard 이동, reindex, resize 작업은 디스크, 네트워크, CPU 부하를 일으키므로 업무 집중 시간을 피해 수행하십시오. 되돌릴 수 없는 단계(삭제, stale/empty primary) 전에는 최신 snapshot이 있어야 합니다: Snapshot.
• 새 서버는 cluster 설치 가이드의 운영체제 준비 및 소프트웨어 설치 단계로 준비되어 있습니다: 같은 Elasticsearch 버전, vm.max_map_count, heap, swap 비활성, 방화벽에서 9200/9300 열림. 서비스는 한 번도 시작하지 않았습니다(enrollment는 첫 시작 전에만 가능).

가이드 단계

• API 접근 — API용 임시 자격 증명 파일
• 상태: health, node, shard, 디스크 (읽기 전용) — Cluster 상태, node, 할당되지 않은 shard · shard가 할당되지 않은 이유 확인 (allocation explain) · 디스크 사용량 및 watermark · 대기 중인 작업 및 결과 해석
• 1. 진단: shard가 왜 할당되지 않는가? — index의 shard와 explain 판정
• 2. 적용 — 실패한 할당 재시도 (retry_failed) · replica 수를 node 수에 맞추기 · Allocation filtering 제거 · 디스크 문제로 이동 · 이전 사본에서 primary 할당 (allocate_stale_primary) · 빈 primary 할당 (allocate_empty_primary)
• 3. 검증 — shard 시작 확인
• 1. 진단 — 디스크 사용량과 현재 임계값
• 2. 적용 — …임계값 변경…임계값을 기본값으로 되돌리기…
• 1. 진단: 블록 및 디스크 — 블록된 index와 디스크 확인 · 디스크 공간 확보 방법
• 2. 적용 — 블록 제거
• 3. 검증 — 쓰기가 되는지 테스트
• 1. 진단 — cluster 상태 확인
• 2. 적용: enrollment 및 합류 — node enrollment token 생성 · token으로 새 node 구성 · node.name 및 네트워크 설정 확인 · 서비스 시작
• 3. 검증 — node가 합류해 shard를 받는지 확인
• 1. 진단 — node의 shard와 역할 확인
• 2. 적용: 비우기 및 종료 — node에서 shard 이동 (allocation exclude) · node가 비워질 때까지 대기 · master-eligible node를 voting에서 제외 · node 중지 · exclude와 voting exclusion 제거
• 3. 검증 — cluster 상태 검증
• 1. 진단 및 준비 — 소스 index와 alias 확인 · 새 mapping/설정으로 새 index 생성
• 2. 적용: 복사 및 alias 전환 — 데이터 복사 (_reindex, 백그라운드) · task 모니터링 · 새 index 준비 및 문서 수 비교 · alias를 새 index로 원자적 전환
• 3. 후속 작업 — 이전 index 닫기 (나중에 삭제)
• 1. ILM 정책, template, 초기 index — ILM 정책 생성 · index template 생성 · write alias와 함께 초기 index 생성
• 진단: ILM이 왜 진행되지 않는가? — ILM 상태와 오류 index 확인 · 실패한 스텝 재시도
• 수동 rollover — alias를 즉시 rollover
• 1. 진단 — index의 shard 수와 크기
• 3. 적용 — …Shrink…Split…: … → … (… shard) · alias를 새 index로 전환
• 4. 후속 작업 — 소스 index 닫기 (나중에 삭제)
• 1. 진단: snapshot에 index가 있는가? — snapshot과 그 안의 index 확인
• 2. 적용: 새 이름으로 복원 — index를 …… 이름으로 복원 · 검증 및 서비스 투입
• 정리 — 자격 증명 파일 삭제