Elasticsearch 입문 26편 — Cluster Operations (master-eligible·voting·rolling restart·split-brain)

이 글은 Elasticsearch 입문에서 운영까지 시리즈 38편 중 26편이에요. 25편까지가 "한 노드에서 어떻게 색인·검색하나" 였다면, 이제부터는 "여러 노드를 한 클러스터로 묶어 어떻게 죽지 않게 운영하나" 자리예요. 단일 노드는 학습용으로 충분해도, 운영 환경에서는 한 줄도 안 통하는 가정. 분산 시스템의 책임이 본격적으로 시작되는 자리가 Cluster Operations 예요.

단일 노드는 학습용 — 운영은 cluster

1편부터 25편까지 본문 예제는 거의 단일 노드 Docker 기준이었어요. 그게 학습에는 최적이지만, 운영에 그대로 가져가면 한 노드가 죽는 순간 서비스 전체가 죽는 구조라 가용성·내구성 측면이 0 에 가까워져요.

운영 클러스터는 보통 최소 3개 노드 부터 시작해요. Replica = 1 만 둬도 데이터가 두 벌이라 한 노드가 죽어도 OK 고, 마스터 선출에 필요한 quorum 도 노드 3개부터 안전하게 잡혀요. 이 3 이라는 숫자가 ES 운영의 첫 번째 마법 숫자예요.

분산이 되는 순간 네트워크 파티션·시계 불일치·메시지 순서 어긋남 같은 새 사고들이 한꺼번에 들어와요. 이 글은 그 사고들을 Node 역할 분리 · Master 정족수 · Rolling Restart 4단계 · Voting Exclusion 네 도구로 막는 표준 패턴을 정리합니다.

Node 종류 — 역할 분리가 곧 운영 안정

ES 8.x 의 Node 는 roles 라는 다중 역할 시스템으로 나뉘어요. elasticsearch.yml 의 node.roles: [master, data, ingest] 같은 식으로 한 노드에 여러 역할 을 박을 수 있고, 운영 규모가 커지면 한 역할 한 노드 로 쪼개는 게 표준이에요.

작은 규모(노드 < 6) 는 모든 역할 통합 노드 3개 로 시작해도 됩니다. 트래픽이 커지면 Master 전용 3개 + Data 노드 N개 + Coordinating 노드 2~3개 로 분리하는 패턴이 일반.

왜 분리하나 — 마스터 노드는 클러스터 상태(매핑·라우팅 테이블) 를 메모리에 들고 있고, 그 상태가 모든 데이터 노드 에 브로드캐스트돼요. Master 가 GC pause 로 멎으면 클러스터 전체가 멎고, 그래서 마스터 노드는 GC pause 가 짧은 작은 힙(8~16GB) + 가벼운 부하 가 답이에요. Data 노드(=무거운 검색·색인) 와 같은 자리에 두면 부하 때문에 GC pause 가 길어져 마스터 선출이 자주 흔들려요.

# Master 전용 노드 예시 (elasticsearch.yml)
node.name: master-1
node.roles: [master]
discovery.seed_hosts: ["master-1", "master-2", "master-3"]
cluster.initial_master_nodes: ["master-1", "master-2", "master-3"]

# Data 전용 노드 예시
node.name: data-1
node.roles: [data, ingest]
discovery.seed_hosts: ["master-1", "master-2", "master-3"]

Master-eligible Node — 클러스터의 뇌

Master 노드는 클러스터 안에서 오직 한 명만 활성 이고, 나머지 master-eligible 노드들은 대기 상태로 있다가 현재 마스터가 죽으면 새 마스터를 선출해요. 이 선출 = election 과정을 ES 8.x 는 Raft 알고리즘의 변종 으로 풀어요.

왜 홀수, 그리고 왜 3개 — 정족수(quorum) 가 (N/2) + 1 이라서 N=3 이면 2 표가 모이면 통과, N=5 면 3 표, N=2 면 2 표 전부 필요 — 즉 짝수는 한 노드만 죽어도 마스터 선출 불가 가 되니까 의미 X. 그래서 master-eligible 노드 = 3 또는 5 가 표준이에요. 1개는 절대 X(=장애 시 클러스터 전체 멈춤).

마스터의 일은 데이터 처리가 아니라 상태 관리 예요. 어떤 인덱스가 있고 / 각 인덱스에 샤드가 몇 개고 / 각 샤드가 어느 노드에 떠 있고 / 어떤 노드가 죽었는지 — 이런 cluster state 메타데이터를 모든 노드에 푸시하는 게 본업.

# 현재 마스터 확인
GET /_cat/master?v
id                     host        ip          node
zk3o5VtMQ5...  10.0.1.10   10.0.1.10   master-1

# master-eligible 노드 목록
GET /_cat/nodes?v&h=name,node.role,master
name      node.role  master
master-1  m          *
master-2  m          -
master-3  m          -
data-1    di         -
data-2    di         -

master 컬럼의 * 가 활성 마스터, - 가 대기 상태. node.role 의 m 이 master-eligible, d 가 data, i 가 ingest.

Voting & Bootstrap — 8.x 의 정족수 구성

ES 7.x 부터 zen discovery 가 사라지고 Voting Configuration 기반으로 마스터 선출이 재설계됐어요. 이게 8.x 의 표준이고, 이전 시대 자료에 나오는 discovery.zen.minimum_master_nodes 같은 설정은 이제 무시되거나 에러 라서 한 번 정리하고 가요.

Cluster Bootstrap — 클러스터를 처음 만들 때 한 번만 필요한 작업이에요. cluster.initial_master_nodes 설정에 시작 시점의 master-eligible 노드 이름들 을 박아 두면, 그 노드들이 모여 첫 voting configuration 을 구성하고 첫 마스터를 뽑아요. 이미 만들어진 클러스터에 새 노드를 붙일 때는 이 설정 X — 헷갈리면 split-brain 의 원인이 돼요.

# 새 클러스터 만들 때 (3개 master-eligible 모두에 같은 값)
cluster.initial_master_nodes: ["master-1", "master-2", "master-3"]
discovery.seed_hosts: ["master-1:9300", "master-2:9300", "master-3:9300"]

Voting Configuration — 클러스터가 살아 움직이는 동안 현재 표결권을 가진 노드 집합 을 ES 가 자동 관리해요. 보통 master-eligible 노드 = voting 노드 가 일치하고, 노드를 늘리거나 줄이면 자동 갱신.

# 현재 voting configuration 확인
GET /_cluster/state/metadata/voting_config_exclusions

# 더 자세히는 cluster state 안에 last_committed_config
GET /_cluster/state?filter_path=metadata.cluster_coordination
{
  "metadata": {
    "cluster_coordination": {
      "term": 4,
      "last_committed_config": ["master-1", "master-2", "master-3"],
      "last_accepted_config": ["master-1", "master-2", "master-3"]
    }
  }
}

Split-brain 방지 — voting configuration 의 핵심 목표가 split-brain 방지예요. N개 voting 노드 → 정족수 (N/2)+1 룰 덕에, 네트워크 파티션으로 2개 노드 vs 1개 노드 로 갈리면 2개 쪽만 정족수를 만족해 마스터를 가져요. 1개 쪽은 읽기 가능 · 쓰기 불가 · 마스터 선출 불가 상태로 격리되고, 네트워크가 복구되면 자동 합류해요.

이 메커니즘이 정상 동작하려면 master-eligible = 홀수 · ≥ 3 · 같은 AZ 에 몰빵 X 세 조건이 동시에 만족돼야 해요. AZ 한 쪽이 통째로 죽어도 다른 쪽에 정족수가 남도록 분산이 필요.

Cluster Health — green / yellow / red 의 정확한 의미

운영 중 가장 자주 보는 API 가 _cluster/health 예요. 이 한 호출로 클러스터 전체 상태 가 한 줄 색깔로 요약돼서 모니터링·알람의 핵심 입력이 돼요.

GET /_cluster/health
{
  "cluster_name": "my-cluster",
  "status": "green",
  "number_of_nodes": 5,
  "number_of_data_nodes": 2,
  "active_primary_shards": 12,
  "active_shards": 24,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 0
}

색깔 셋의 정확한 의미:

yellow 는 사고 아님 — 단일 노드 개발 클러스터는 거의 항상 yellow 예요. Replica = 1 인데 노드가 1개라서 replica 가 다른 노드에 갈 자리가 없으니까. 운영 클러스터에서 short-term yellow 는 OK (rolling restart 중·새 노드 추가 중) 지만, long-term yellow 는 점검 필요.

red 는 즉시 대응 — primary 하나가 어디에도 없는 상태라, 그 샤드에 속한 데이터를 읽지도 쓰지도 못해요. 가장 자주 만나는 원인이 디스크 watermark · 노드 장애 후 미복구 · index.routing.allocation. 설정 미스* 셋이에요.

# red 원인 진단
GET /_cluster/allocation/explain
{
  "index": "my-index",
  "shard": 0,
  "primary": true
}

이 API 가 "왜 이 샤드가 할당되지 못했는지" 를 사람이 읽을 수 있는 문장으로 풀어 줘요. 디스크 사용률 92% 초과·노드 X 가 죽음·allocation filter 가 가로막음 같은 식.

Index-level vs Cluster-level — _cluster/health?level=indices 또는 ?level=shards 로 더 세분화도 가능. 보통 한 인덱스만 red 인데 전체가 red 로 표시 되는 경우가 많아 — 인덱스 단위로 봐야 어떤 데이터가 문제인지 잡혀요.

Rolling Restart — 무중단 업그레이드 4단계

운영 클러스터를 버전 업그레이드 · 설정 변경 · 보안 패치 할 때 전체 다운타임 없이 한 노드씩 끄고 켜는 패턴이 Rolling Restart 예요. 이게 ES 운영의 가장 자주 쓰는 작업이고, 4단계 절차 를 외워 두면 사고 90% 가 막힙니다.

1단계 — Shard 재할당 비활성화

노드 하나를 끄려면 그 위의 샤드를 다른 노드로 옮겨야 하는 게 정상이지만, 몇 분 뒤 다시 켤 노드라면 그 이동 자체가 낭비예요. 그래서 일시 정지.

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "primaries"
  }
}

primaries 옵션 — 새 primary 는 할당 OK 지만 replica 는 멈춤. 즉 새 인덱스 색인은 계속 되지만 기존 데이터 재배치 는 일시 정지.

2단계 — Flush 와 Sync

메모리에 떠 있는 indexing buffer 를 디스크에 내려서 재시작 후 복구 가 빠르도록 정리.

POST /_flush
# 7.x 까지는 _flush/synced 가 있었지만 8.x 에서 deprecated. 그냥 _flush 면 OK

이게 없으면 노드 재시작 후 translog replay 에 시간이 오래 걸려 yellow 가 길어져요.

3단계 — Restart (한 노드씩)

# OS 레벨
sudo systemctl restart elasticsearch

# 또는 Docker
docker restart es-node-1

재시작 후 health 가 yellow → green 으로 돌아오는 걸 기다려요. 보통 최소 1분, 최대 10분 수준. 이 사이에 다음 노드는 절대 끄지 X — 두 노드가 동시에 내려가면 quorum 깨짐 + replica 미보유 인덱스 red 위험.

4단계 — Allocation 다시 켜기

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": null
  }
}

null 로 보내면 기본값(all) 으로 복원. 그러면 자동 재할당이 다시 돌고 initializing_shards · relocating_shards 가 0 으로 떨어질 때까지 기다리면 끝.

전체 흐름 한 줄 — disable allocation → flush → restart → wait green → enable allocation 을 각 노드마다 반복. 5개 노드 클러스터면 30~60분 정도가 일반.

노드 추가·제거 — Voting Exclusion 의 역할

노드 추가 는 단순해요. 새 노드의 elasticsearch.yml 에 discovery.seed_hosts 로 기존 master 들의 주소를 박고, node.roles 를 정의하고 시작하면 자동 join. 클러스터가 cluster state 를 새 노드에 동기화하고, allocation 이 켜져 있으면 샤드도 자동으로 옮겨 와요.

# 새 data 노드 추가 예시
node.name: data-3
node.roles: [data]
discovery.seed_hosts: ["master-1:9300", "master-2:9300", "master-3:9300"]
# initial_master_nodes 는 박지 X (이미 만들어진 클러스터라서)

노드 제거 (decommission) 가 까다로워요. 그냥 노드를 끄면 그 위의 샤드들이 unassigned 상태가 됐다가 다른 노드로 재할당되는데, 그 동안 yellow/red 위험이 있고 replica 가 1 뿐인 데이터 는 일시적으로 데이터 손실 위험에 노출돼요.

표준 절차는 샤드 먼저 빼고 → 노드 끄기 입니다.

# 1) 노드 X 에서 모든 샤드 제외
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.exclude._name": "data-3"
  }
}

# 2) 그 노드의 모든 샤드가 빠질 때까지 기다림
GET /_cat/shards?h=index,shard,prirep,state,node | grep data-3
# 결과가 빌 때까지 대기

# 3) 노드 끄기
sudo systemctl stop elasticsearch

master-eligible 노드 제거 는 Voting Exclusion 까지 추가로 필요해요. 그냥 빼면 voting configuration 에 죽은 노드 이름이 남아 정족수 계산이 어긋날 수 있어서.

# 1) voting exclusion 추가
POST /_cluster/voting_config_exclusions?node_names=master-3

# 2) 노드 끄기
sudo systemctl stop elasticsearch

# 3) 작업이 다 끝나면 exclusion 초기화
DELETE /_cluster/voting_config_exclusions

이 절차를 빼먹으면 5개 voting 노드 → 4개로 줄였을 때 정족수가 여전히 3 인 게 아니라 잠깐 3 또는 4 로 흔들려 split-brain 위험이 생겨요.

Cross-cluster Replication (CCR) — 한 줄 소개

CCR 은 한 클러스터의 인덱스를 다른 지역·다른 클러스터 로 실시간 복제 해 주는 기능이에요. Active-Passive DR(Disaster Recovery) 구성·지역별 읽기 가속·BI 분리 같은 자리에 써요. 8.x 기준 Platinum 이상 라이선스가 필요한 유료 기능 이고, OpenSearch 진영은 Cross-Cluster Replication 플러그인으로 비슷한 자리를 풀어요.

핵심 개념 셋만 미리 — Leader index (원본·서울) · Follower index (복제본·도쿄) · Remote cluster (서울에서 도쿄를 부르는 등록). CCR 은 near real-time 이라서 follower 에 약간 지연된 복제본 이 떠 있고, 장애 발생 시 follower 를 unfollow 해서 독립 인덱스로 승격시킬 수 있어요.

이 글에서는 한 줄 소개로 마무리하고, 38편(Series Conclusion 직전 깊이 편) 또는 별도 CCR Deep 편에서 인덱스 라이센스·승격 절차·multi-region 토폴로지까지 다룰 예정.

자주 만나는 사고 7가지

사고 1 — Master-eligible 노드가 1개

원인 — 비용 절감으로 master 노드 1개 + data 노드 N개 구성으로 시작하면, 그 master 가 죽는 순간 클러스터 전체가 멎어요. quorum (N/2)+1 = 1 이고 그 1이 죽으면 새 마스터를 뽑을 후보가 없음.

해결 — master-eligible = 3 (또는 5) 가 운영 최소. 작은 규모면 3개 통합 노드(role=[master,data,ingest]) 로 시작해도 OK 지만, master 만큼은 무조건 3개. 비용보다 가용성 이 비싼 자산.

사고 2 — Split-brain (네트워크 파티션)

원인 — master-eligible = 2 인 클러스터에서 두 노드 사이 네트워크가 끊기면 각자 자기 자신을 마스터로 뽑아 두 개의 마스터 + 두 개의 cluster state 가 생겨요. 데이터 무결성 깨짐.

해결 — master-eligible 홀수 가 1차 방어, AZ 분산 이 2차 방어. ES 7.x+ 의 voting configuration 이 이걸 자동으로 막아 주지만, 잘못된 cluster.initial_master_nodes 설정으로 우회될 위험은 여전. 이미 만든 클러스터에는 이 설정 박지 X 가 핵심 규칙.

사고 3 — Rolling Restart 중 yellow → red

원인 — Rolling restart 도중 재시작한 노드가 다시 올라오기 전에 다음 노드를 끄면, 어떤 인덱스의 모든 복제본이 동시에 사라져 primary 까지 unavailable 이 됨.

해결 — 한 노드 끄고 health 가 green 으로 복귀할 때까지 무조건 대기. 자동 스크립트라면 green wait 가 명시적인 polling 단계 로 들어가야 해요. GET /_cluster/health?wait_for_status=green&timeout=10m 가 유용.

사고 4 — Node Decommission 후 shard 미이동

원인 — allocation.exclude._name 으로 노드를 빼려 했는데 디스크 high watermark(기본 90%) 에 걸려 받을 노드가 없어 샤드가 그대로 남아요. 노드 끄면 데이터 손실.

해결 — 다른 노드의 디스크 여유를 먼저 확보(인덱스 정리 · 노드 추가 · watermark 조정). cluster.routing.allocation.disk.watermark.high 를 일시적으로 95% 로 올려 빼는 작업을 통과시키고, 끝나면 원복하는 패턴도 자주 씁니다.

사고 5 — Zen Discovery 시대 잔존 설정

원인 — 7.x 이전 시대의 discovery.zen.minimum_master_nodes · discovery.zen.ping.unicast.hosts 같은 설정이 elasticsearch.yml 에 남아 있으면, 8.x 에서는 시작 거부 또는 deprecation warning 이 나요.

해결 — 7.x → 8.x 업그레이드 전 discovery.zen.* 키 전수 제거. 표준 키는 discovery.seed_hosts (구 unicast.hosts) 와 cluster.initial_master_nodes 두 개만 남기는 방향.

사고 6 — Master 노드가 GC Pause 로 흔들림

원인 — Master 와 Data 역할을 한 노드에 합쳤는데 대용량 검색·집계 가 들어와 JVM 이 수 초 GC pause 에 걸리면, 다른 노드들이 마스터가 죽었다고 판단해 재선출 을 시도해요. 운영 중 마스터 핑퐁이 잦으면 cluster state 동기화가 자주 깨져요.

해결 — Master 전용 노드 분리 + 마스터 노드 힙 8~16GB 작게 유지 + cluster.fault_detection.* timeout 을 살짝 늘려도 OK. 운영 클러스터 규모가 6+ 노드면 master 전용 3개 분리가 표준.

사고 7 — Voting Exclusion 미정리

원인 — master-eligible 노드를 뺀 뒤 _cluster/voting_config_exclusions 를 비우지 않고 몇 달 방치 하면, voting configuration 이 옛 노드 이름을 계속 들고 있다가 나중에 같은 이름의 새 노드가 합류 할 때 혼란이 생겨요.

해결 — decommission 작업이 끝나면 항상 DELETE /_cluster/voting_config_exclusions 로 초기화. 운영 체크리스트 마지막 줄에 박아 두는 게 안전.

운영 권장 패턴 5가지

운영 클러스터의 Master-eligible 노드는 정확히 3개 또는 5개, 그리고 전용 노드 로 가져가요. 데이터 노드와 합치면 안정성이 떨어지고, 짝수면 quorum 의 의미가 없어져요. 비용보다 가용성이 비싼 자산이라는 한 줄이 운영의 시작.

AZ(가용 영역) 셋 이상에 master-eligible 노드를 분산 하세요. 한 AZ 가 통째로 사라져도 정족수가 남는 배치가 핵심. 클라우드 환경이면 node attribute 로 AZ 를 기록하고 cluster.routing.allocation.awareness.attributes: zone 로 ES 가 자동으로 zone-aware 할당을 해 주도록 박아 둡니다.

Rolling Restart 절차서를 문서화 해서 disable allocation → flush → restart → wait green → enable allocation 5단계를 사람·자동화 둘 다 같은 순서로 실행하도록 만들어요. 운영자가 매번 머릿속에서 기억해 실행하면 사고 3(yellow→red) 가 반복돼요.

Decommission 체크리스트 를 만들어 두세요. exclude → wait empty → stop node → voting exclusion (master only) → cleanup exclusion 5단계. 빠뜨리면 사고 4(미이동) · 사고 7(잔존 exclusion) 이 그대로 들어와요.

클러스터 헬스 모니터링 은 _cluster/health 한 호출의 status · unassigned_shards · number_of_nodes 세 메트릭만 봐도 90% 가 잡혀요. 5분 이상 yellow 또는 어떤 순간 red 는 즉시 알람으로 묶고, number_of_nodes 가 기대값과 다르면 노드 한 대가 빠진 신호니까 같이 알람. 30편(Monitoring) 에서 깊이.

시험 직전 한 번 더 — 압축 노트

• 단일 노드 = 학습용. 운영은 최소 3개 노드 부터.
• Node 역할 = master · data · ingest · coordinating · remote_cluster_client · ml · transform. 운영 규모가 크면 역할 분리.
• Master-eligible = 클러스터 상태 관리·선출 후보. 3 또는 5 (홀수) · 전용 노드 가 표준.
• 정족수 = (N/2) + 1. N=3 이면 2 표, N=5 면 3 표.
• Voting Configuration = ES 8.x 의 정족수 구성. _cluster/voting_config_exclusions 로 master 노드 제거 시 사용.
• Cluster Bootstrap = cluster.initial_master_nodes 는 처음 만들 때만. 기존 클러스터에 박으면 split-brain 위험.
• Cluster Health 색깔 = green (정상) · yellow (replica 일부 미할당, 손실 X) · red (primary 일부 미할당, 일부 데이터 접근 불가).
• Rolling Restart 4단계 = disable allocation → flush → restart → enable allocation. 노드마다 green 대기 필수.
• Node 추가 = seed_hosts 박고 자동 join. initial_master_nodes 박지 X.
• Node Decommission = exclude._name → wait empty → stop. master 면 voting exclusion 추가.
• CCR = Cross-cluster Replication. leader · follower · remote cluster. Platinum 라이선스. DR · 지역 가속용.
• 7대 사고: Master 1개 · Split-brain · Rolling restart 중 red · Decommission 미이동 · Zen 잔존 설정 · Master GC pause · Voting exclusion 미정리.
• 운영 5규칙: Master 3개 전용 · AZ 분산 · Rolling restart 절차서 · Decommission 체크리스트 · Health 알람.

시리즈 다른 편

• 이전 글 = 25편 데이터 수집 (Logstash·Beats·Filebeat·Metricbeat)
• 다음 글 = 27편 Shard Allocation — Awareness·Filtering·Forced Awareness·Rebalance
• 28편 = Snapshot·Restore — repository·SLM·복원 시나리오
• 29편 = Security — TLS·Realm·RBAC·API Key
• 30편 = Monitoring — Elastic Stack Monitoring·Prometheus·Grafana
• 31편 = Performance Tuning — Heap·Refresh·Merge·Bulk size
• 38편 = 시리즈 마무리 — 결정 트리·체크리스트·자격증

한 줄 정리 — Elasticsearch Cluster Operations = Node 역할 분리 + Master 홀수·전용 + Rolling Restart 4단계 + Decommission 절차 + Voting Exclusion 관리 의 다섯 도구로 분산 시스템의 책임 을 풀어내는 운영 표준. Master 3개 전용 · AZ 분산 · green 대기 한 줄이 사고 90% 를 막아요.