Elasticsearch 클러스터 상태 문제 해결: 단계별 가이드

Elasticsearch는 강력한 분산 시스템이지만, 다른 분산 아키텍처와 마찬가지로 최적의 상태를 유지하려면 적극적인 모니터링과 때때로 개입이 필요합니다. 클러스터 상태는 배포의 운영 준비 상태와 데이터 안전성을 결정하는 가장 중요한 지표입니다. 클러스터 상태가 녹색(Green)에서 노란색(Yellow) 또는 치명적으로 빨간색(Red)으로 전환되면 데이터 무결성 또는 가용성이 위협받습니다.

이 종합 가이드에서는 노란색 및 빨간색 상태 복구에 중점을 두고 일반적인 Elasticsearch 클러스터 상태 문제를 진단하고 해결하는 전문가 단계를 제공합니다. 실용적인 Cat API와 단계별 점검을 사용하여 근본 원인을 신속하게 파악하고 수정 조치를 구현합니다.

1. Elasticsearch 클러스터 상태 이해

문제를 해결하기 전에 각 클러스터 상태 색상이 무엇을 의미하는지 이해하는 것이 중요합니다. 클러스터 상태는 클러스터 노드 전반에 걸쳐 기본 샤드와 복제 샤드의 할당 상태에 따라 결정됩니다.

상태	의미	영향
녹색(Green)	모든 기본 및 복제 샤드가 성공적으로 할당되었습니다.	클러스터가 완전히 작동하며 복원력이 있습니다.
노란색(Yellow)	모든 기본 샤드는 할당되었지만 하나 이상의 복제 샤드가 할당되지 않았습니다.	데이터는 사용 가능하지만 클러스터에는 노드 장애에 대한 완전한 복원력이 없습니다.
빨간색(Red)	하나 이상의 기본 샤드가 할당되지 않아 사용할 수 없습니다.	실패한 샤드를 포함하는 인덱스의 데이터 손실 또는 접근 불가. 긴급 조치가 필요합니다.

2. 초기 진단: 클러스터 상태 확인

모든 문제 해결 과정의 첫 번째 단계는 현재 상태를 확인하고 클러스터 상태 API 및 노드 API를 사용하여 기본 메트릭을 수집하는 것입니다.

2.1단계: 클러스터 상태 확인

_cat/health API를 사용하여 개요를 확인합니다. ?v 매개변수는 노드 수와 총 샤드 수를 포함한 상세 출력을 제공합니다.

GET /_cat/health?v

예시 출력 (노란색 상태):

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

상태가 노란색 또는 빨간색이면 unassign 아래의 값을 기록합니다.

2.2단계: 노드 상태 및 메모리 확인

예상한 모든 노드가 올바르게 연결되고 작동하는지 확인합니다. 또한 힙 사용량(성능 및 안정성에 중요)을 확인합니다.

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

이 목록에 노드가 누락된 경우 연결 문제 또는 중지된 서비스가 있을 수 있습니다.

3. 빨간색 클러스터 상태 해결 (기본 샤드 실패)

빨간색 상태는 데이터에 즉시 액세스할 수 없음을 의미합니다. 목표는 기본 샤드를 가능한 한 빨리 온라인 상태로 복구하는 것입니다.

3.1단계: 할당되지 않은 기본 샤드 식별

_cat/shards API를 사용하여 문제를 일으키는 정확한 인덱스와 샤드를 찾습니다. 특히 UNASSIGNED로 표시되고 p(기본) 역할을 가진 항목을 찾습니다.

GET /_cat/shards?v | grep UNASSIGNED

예시 출력:

index_logs 0 p UNASSIGNED

3.2단계: 할당 설명 확인

이것은 가장 중요한 진단 단계입니다. 할당 설명 API는 특정 샤드(또는 할당되지 않은 모든 샤드)가 할당될 수 없는 이유를 알려줍니다.

GET /_cluster/allocation/explain

빨간색 상태의 일반적인 이유:

노드 실패: 기본 샤드를 보유한 노드가 충돌했거나 클러스터에서 제거되었습니다. 실패한 노드에 다른 노드에 충분한 복제본이 있는 경우, 기본 샤드는 자동으로 복제본을 승격해야 합니다. 모든 복사본(기본 및 복제본)이 실패한 노드에 있었다면, 노드가 복구되지 않는 한 샤드는 손실됩니다.
데이터 손상: 디스크의 기본 샤드 파일이 손상되어 노드가 초기화하지 못하게 됩니다.

3.3단계: 빨간색 상태에 대한 실행 계획

시나리오 A: 노드 오프라인 (선호)
- 기본 샤드를 보유한 노드가 단순히 오프라인 상태인 경우, 노드 서비스를 복원합니다(예: Elasticsearch 재시작 또는 네트워크 문제 해결). 노드가 클러스터에 다시 참여하면 기본 샤드가 복구되어야 합니다.
시나리오 B: 기본 샤드 손실 (최후의 수단)
- 노드가 영구적으로 손실되었고 복제본이 없었다면 데이터는 손실됩니다. allocate_empty_primary 명령을 사용하여 수동으로 복구를 건너뛰어야 합니다. 경고: 이렇게 하면 새롭고 비어 있는 기본 샤드가 생성되어 해당 인덱스 세그먼트에 대한 영구적인 데이터 손실이 발생합니다.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_empty_primary" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]", 
        "accept_data_loss" : true
      }
    }
  ]
}

모범 사례: allocate_empty_primary를 사용하기 전에 항상 해당 인덱스에 대한 스냅샷 또는 백업이 존재하는지 확인하십시오.

4. 노란색 클러스터 상태 해결 (복제 샤드 실패)

노란색 상태는 클러스터가 작동 중이지만 취약하다는 것을 의미합니다. 주요 목표는 누락된 복제본을 할당하는 것입니다.

4.1단계: 할당 설명 사용

상태가 노란색이면 _cluster/allocation/explain API(3.2절)를 사용하여 복제본이 할당되지 않는 이유를 이해합니다. 복제본에 대한 설명은 일반적으로 더 간단합니다.

노란색 상태의 일반적인 이유:

이유 코드	설명	수정
`NO_AVAILABLE_NODES`	클러스터 크기가 너무 작습니다 (예: 복제본 수가 2인데 노드가 2개만 있습니다).	데이터 노드를 더 추가하거나 `number_of_replicas`를 줄입니다.
`NOT_ENOUGH_DISK_SPACE`	노드가 낮거나 높은 워터마크 임계값에 도달했습니다.	오래된 인덱스를 삭제하고, 디스크 공간을 확보하거나, 디스크 워터마크를 조정합니다.
`ALLOCATION_DISABLED`	샤드 할당이 클러스터 설정에 의해 명시적으로 비활성화되었습니다.	`PUT /_cluster/settings`를 사용하여 라우팅을 다시 활성화합니다.
`PRIMARY_NOT_ACTIVE`	기본 샤드가 아직 초기화 중이거나 복구 중입니다.	기본이 활성 상태(녹색)가 될 때까지 기다립니다.

4.2단계: 노드 요구 사항 및 제약 조건 확인

클러스터가 복제본 할당의 기본 요구 사항을 충족하는지 확인합니다.

노드 수: N개의 복제본의 경우, 기본 샤드와 복제본 샤드가 동일한 노드에 있지 않도록 하려면 최소 N+1개의 데이터 노드가 필요합니다.
디스크 워터마크: Elasticsearch는 디스크 사용량이 높은 워터마크(기본값 90%)를 초과하면 노드에 대한 샤드 할당을 중지합니다.

# 디스크 할당 설정 확인
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# 예시: 높은 워터마크를 95%로 설정 (임시!)
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

4.3단계: 수동 재라우팅 (할당 논리가 실패하는 경우)

드문 경우이지만, 표준 할당 프로세스가 충분한 리소스에도 불구하고 멈춘 것처럼 보이면 allocate_replica 명령을 사용하여 특정 정상 노드로의 복제본 할당을 수동으로 강제할 수 있습니다.

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. 고급 문제 해결 및 일반적인 함정

빨간색 또는 노란색 상태가 지속되면 근본 원인이 표준 샤드 할당 논리 외부에 있을 수 있습니다.

5.1 네트워크 연결 및 스플릿 브레인

분산 시스템에서는 파티셔닝(스플릿 브레인)이 심각한 문제를 일으킬 수 있습니다. 마스터 후보 노드가 통신할 수 없으면 클러스터가 안정적인 마스터를 선출하지 못할 수 있으며, 이는 할당되지 않은 샤드로 이어집니다.

조치: 모든 노드 간의 네트워크 연결, 특히 마스터 후보 노드 간의 연결을 확인합니다.
구성 확인: discovery.seed_hosts 목록이 정확하고 클러스터 부트스트랩 중에 cluster.initial_master_nodes 설정이 올바르게 사용되었는지 확인합니다.

5.2 높은 JVM 메모리 압력

과도한 힙 사용량(종종 75% 이상)은 빈번하고 긴 가비지 컬렉션(GC) 일시 중지를 유발합니다. 이러한 일시 중지 동안 노드가 응답하지 않는 것처럼 보일 수 있으며, 마스터 노드가 해당 노드를 삭제하여 할당되지 않은 샤드로 이어집니다.

조치: 힙 사용량(_cat/nodes?h=heap.percent)을 모니터링합니다. 지속적으로 높은 경우 노드 메모리 확장, 인덱싱 프로세스 최적화 또는 인덱스 수명 주기 관리(ILM) 구현을 고려하십시오.

5.3 샤드 할당 필터링

할당 필터(태그 또는 ID와 같은 노드 속성 사용)의 우발적인 적용은 다른 노드에 할당될 수 있는 샤드가 할당되지 못하게 할 수 있습니다.

# 인덱스 수준 할당 규칙 확인
GET /[index-name]/_settings
# 다음을 찾습니다: index.routing.allocation.require.*

# 필요한 경우 인덱스 할당 규칙 재설정
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

빠른 복구를 위한 요약 체크리스트

상태	주요 진단 도구	핵심 조치 단계
노란색(Yellow)	`GET /_cluster/allocation/explain`	1. 디스크 공간 확인. 2. 노드 수 대 복제본 수 확인. 3. 할당 필터링 규칙 확인. 4. 기본 복구 대기.
빨간색(Red)	`GET /_cat/shards?v \| grep UNASSIGNED`	1. 이전에 호스팅했던 노드의 로그 확인. 2. 실패한 노드 재시작 시도. 3. 기본 샤드가 손실되었다고 확인되었고 백업이 없는 경우 `allocate_empty_primary` 사용 (데이터 손실 위험).

_cat API와 중요한 _cluster/allocation/explain 엔드포인트를 체계적으로 활용하면 클러스터 상태 저하의 원인을 신속하게 파악하고 클러스터를 안정적인 녹색 상태로 복원하는 데 필요한 수정 단계를 구현할 수 있습니다.