DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브 DevOps 도구 및 베스트 프랙티스 마스터 - DevOps 지식 허브

문제 해결: Elasticsearch 클러스터 상태 확인 및 해석

Elasticsearch 클러스터 상태 진단을 위한 필수 기술을 마스터하세요. 이 가이드에서는 `_cat/health` API를 사용하여 상태를 확인하고 중요한 녹색, 노란색, 빨간색 지표를 해석하는 방법을 자세히 설명합니다. 할당되지 않은 샤드의 근본 원인, `_cat/shards` 및 `_cluster/allocation/explain`과 같은 고급 API를 사용한 심층 진단 방법, 그리고 중요한 클러스터 불안정성을 신속하고 효과적으로 해결하기 위한 실행 가능한 단계를 알아보세요.

문제 해결: Elasticsearch 클러스터 상태 확인 및 해석

Elasticsearch 클러스터 상태는 호출기가 울리기 전까지는 간단해 보이는 검사 중 하나입니다. API는 색상을 제공하지만, 색상은 시작점에 불과합니다. 녹색 클러스터도 느릴 수 있습니다. 노란색 클러스터는 짧은 유지보수 기간 동안 완벽하게 사용할 수 있습니다. 빨간색 클러스터는 하나의 작은 테스트 인덱스를 사용할 수 없음을 의미하거나, 고객 대상 검색에서 실제 데이터가 누락되었음을 의미할 수 있습니다.

Elasticsearch 클러스터 상태를 확인할 때, 저는 red에서 바로 위험한 복구 명령으로 건너뛰지 않으려고 합니다. 먼저 세 가지 질문에 답하고 싶습니다: 기본 샤드가 할당되었는지, 복제본이 할당되었는지, 클러스터가 현재 자체적으로 복구를 시도하고 있는지입니다. 아래 명령어는 광범위한 상태 색상에서 특정 이유로 이동하는 데 사용하는 명령어입니다.

상태 API로 시작

빠른 터미널 보기를 위해서는 _cat/health로 충분합니다:

curl -s "http://localhost:9200/_cat/health?v"

일반적인 응답은 다음과 같습니다:

epoch      timestamp cluster     status node.total node.data shards pri relo init unassign pending_tasks
1762219800 12:10:00  logs-prod   yellow          3         3    124  62    0    0        2             0

제가 가장 먼저 보는 필드는 status, node.total, node.data, relo, init, unassign, pending_tasks입니다. init 또는 relo가 0보다 큰 노란색 상태는 단순히 재시작 후 복구 중인 클러스터일 수 있습니다. 할당되지 않은 샤드가 있고 움직임이 없는 노란색 상태는 일반적으로 조사가 필요합니다.

자동화의 경우 _cat 출력을 구문 분석하는 대신 JSON API를 사용하세요:

curl -s "http://localhost:9200/_cluster/health?pretty"

해당 응답에는 active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards, delayed_unassigned_shards와 같은 필드가 포함됩니다. 이러한 이름은 스크립트 및 모니터링 검사에서 사용하기 더 쉽습니다.

녹색, 노란색, 빨간색의 실제 의미

녹색은 모든 기본 샤드와 구성된 모든 복제본 샤드가 할당되었음을 의미합니다. 쿼리가 빠르거나, 디스크가 정상이거나, 매핑이 잘 설계되었음을 의미하지는 않습니다. 이는 Elasticsearch가 할당해야 하는 샤드를 배치했음을 의미할 뿐입니다.

노란색은 모든 기본 샤드가 할당되었지만 하나 이상의 복제본 샤드가 할당되지 않았음을 의미합니다. 기본 샤드를 사용할 수 있으므로 데이터는 여전히 검색 가능해야 합니다. 위험은 중복성입니다. 복제본이 아직 할당되지 않은 상태에서 기본 샤드를 보유한 노드에 장애가 발생하면 해당 인덱스가 빨간색이 될 수 있습니다.

빨간색은 하나 이상의 기본 샤드가 할당되지 않았음을 의미합니다. 영향을 받는 인덱스에 대한 검색이 실패하거나 부분 결과를 반환할 수 있으며, 해당 샤드에 대한 쓰기가 정상적으로 진행되지 않을 수 있습니다. 빨간색은 즉각적인 주의가 필요하지만, 올바른 조치는 기본 샤드가 할당되지 않은 이유에 따라 다릅니다.

일반적인 소규모 클러스터 예는 하나의 복제본이 구성된 단일 노드 개발 클러스터입니다. Elasticsearch는 기본 샤드와 동일한 노드에 복제본을 배치하지 않기 때문에 노란색으로 유지됩니다. 이는 미스터리가 아니며 할당을 강제할 이유가 아닙니다. 다른 데이터 노드를 추가하거나 해당 인덱스의 복제본을 0으로 설정하세요:

curl -X PUT "http://localhost:9200/my-index/_settings"   -H 'Content-Type: application/json'   -d '{"index":{"number_of_replicas":0}}'

프로덕션에서 이 설정을 아무렇게나 사용하지 마십시오. 해당 인덱스의 중복성을 제거합니다.

정확한 할당되지 않은 샤드 찾기

상태 색상 다음에 샤드를 나열하세요:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason" | sort

UNASSIGNED를 찾으세요. prirep 열은 샤드가 기본(p)인지 복제본(r)인지 알려줍니다. 이 구분은 색상 자체보다 더 중요합니다. 할당되지 않은 복제본 몇 개는 일반적으로 내결함성 감소를 의미합니다. 할당되지 않은 기본 샤드 하나는 인덱스의 적어도 일부를 사용할 수 없음을 의미합니다.

계획된 노드 재시작 후 많은 할당되지 않은 샤드가 표시되면 지연된 할당도 확인하세요:

curl -s "http://localhost:9200/_cluster/health?pretty" | grep delayed_unassigned_shards

Elasticsearch는 노드가 떠난 후 복제본 재할당을 기다릴 수 있습니다. 노드가 빨리 돌아올 수 있기 때문입니다. 이 동작은 롤링 재시작 중 불필요한 네트워크 및 디스크 변동을 방지합니다.

Elasticsearch에 할당 실패 이유 묻기

할당 설명 API는 다음 단계로 가장 좋습니다. 할당되지 않은 샤드에 대해 물어볼 수 있습니다:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{}'

또는 특정 샤드에 대해 물어보세요:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "logs-2026.05.24",
    "shard": 0,
    "primary": false
  }'

unassigned_info, can_allocate, node_allocation_decisions를 읽으세요. 유용한 부분은 일반적으로 평이한 영어로 되어 있습니다: 디스크 워터마크 초과, 할당 비활성화, 일치하는 노드 속성 없음, 노드에 샤드가 너무 많음, 또는 노드가 하나만 존재하여 복제본을 배치할 수 없음.

설명이 allocation_delayed라고 표시되면 누락된 노드가 곧 돌아올 것으로 예상되는 경우에만 기다리세요. 설명이 할당 규칙을 충족하는 노드가 없다고 표시되면 기다려도 해결되지 않습니다.

노란색 클러스터 플레이북

노란색 상태의 경우 다음 순서를 사용합니다:

  1. 클러스터에 구성된 복제본 수에 충분한 데이터 노드가 있는지 확인합니다.
  2. _cat/allocation으로 디스크 워터마크를 확인합니다.
  3. 유지보수 중에 할당이 비활성화되었는지 확인합니다.
  4. 인덱스 수준 라우팅 필터 및 인식 규칙을 확인합니다.
  5. 용량을 추가하거나, 복제본 수를 줄이거나, 잘못된 규칙을 수정할지 결정합니다.

노드 수 확인은 간단합니다. 인덱스에 number_of_replicas: 2가 있으면 Elasticsearch는 하나의 기본 샤드와 두 개의 복제본을 배치하기 위해 세 개의 적합한 데이터 노드가 필요합니다. "적합한"이 중요합니다. 할당 인식에 별도의 영역이 필요한 경우 해당 영역에 노드가 필요하며, 세 개의 노드만 있으면 안 됩니다.

할당 및 디스크 확인:

curl -s "http://localhost:9200/_cat/allocation?v"

노드가 디스크 워터마크 위에 있으면 Elasticsearch가 새 샤드 할당을 거부할 수 있습니다. 공간을 확보하고, 노드를 추가하고, 디스크를 확장하거나, 스냅샷을 찍은 후 오래된 인덱스를 삭제하세요. 워터마크를 높이면 통제된 비상 상황에서 시간을 벌 수 있지만 용량을 생성하지는 않습니다.

할당 설정 확인:

curl -s "http://localhost:9200/_cluster/settings?include_defaults=true&pretty"

cluster.routing.allocation.enable이 none이면 할당이 비활성화된 것입니다. 이는 다시 켜는 것을 잊은 유지보수 스크립트 후에 흔히 발생합니다. 다음으로 다시 활성화하세요:

curl -X PUT "http://localhost:9200/_cluster/settings?pretty"   -H 'Content-Type: application/json'   -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

값이 transient로 설정되었는지도 확인하세요. 영구 및 일시적 설정 모두 동작에 영향을 줄 수 있습니다.

빨간색 클러스터 플레이북

빨간색 상태의 경우 속도를 늦추고 영향 범위를 식별하세요. allocate_empty_primary로 시작하지 마십시오. 해당 명령은 설계상 데이터 손실을 허용합니다.

먼저 영향을 받는 기본 샤드를 찾으세요:

curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"   | grep ' p '   | grep UNASSIGNED

그런 다음 할당 설명으로 하나를 검사하세요:

curl -X GET "http://localhost:9200/_cluster/allocation/explain?pretty"   -H 'Content-Type: application/json'   -d '{
    "index": "affected-index",
    "shard": 0,
    "primary": true
  }'

노드가 다운되어 기본 샤드가 할당되지 않은 경우, 가장 좋은 복구 방법은 해당 노드를 복원하는 것입니다. 서비스, 디스크, JVM 로그 및 네트워크 경로를 확인하세요. 다른 노드에 복제본 복사본이 있으면 Elasticsearch는 일반적으로 이를 승격해야 합니다. 그렇지 않은 경우 설명 출력과 로그가 일반적으로 이유를 알려줍니다.

데이터가 손실되었거나 손상된 경우 스냅샷에서 복원하세요. 이것이 깔끔한 복구 경로입니다. 스냅샷이 없고 데이터를 다른 소스에서 다시 빌드할 수 있는 경우 빈 기본 샤드를 할당하기로 결정할 수 있습니다:

curl -X POST "http://localhost:9200/_cluster/reroute?pretty"   -H 'Content-Type: application/json'   -d '{
    "commands": [
      {
        "allocate_empty_primary": {
          "index": "affected-index",
          "shard": 0,
          "node": "target-node-name",
          "accept_data_loss": true
        }
      }
    ]
  }'

샤드 내용을 잃는 것이 허용되는 경우에만 사용하세요. 이름 그대로입니다: Elasticsearch는 빈 기본 샤드를 할당하고 계속 진행합니다.

추측 대신 복구 관찰

수정 후 샤드 이동을 관찰하세요:

curl -s "http://localhost:9200/_cat/recovery?v&active_only=true"
curl -s "http://localhost:9200/_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason"
curl -s "http://localhost:9200/_cluster/health?pretty"

복구는 디스크 속도, 네트워크 대역폭, 샤드 크기 및 클러스터 복구 설정에 의해 제한될 수 있습니다. 큰 샤드는 예상보다 오래 INITIALIZING 상태로 있을 수 있습니다. 이는 멈춘 것과는 다릅니다. _cat/recovery에서 바이트 수와 파일 수가 이동 중이면 계속 작동하도록 두세요.

상태가 변경되지 않을 때 보류 중인 클러스터 작업도 확인하세요:

curl -s "http://localhost:9200/_cat/pending_tasks?v"

긴 대기열은 과부하된 마스터 노드 또는 완료할 수 없는 반복적인 할당 결정을 가리킬 수 있습니다.

실제 예제

_cat/health가 두 개의 할당되지 않은 샤드와 함께 노란색을 표시한다고 가정해 보겠습니다. _cat/shards는 둘 다 logs-2026.05.24의 복제본임을 보여줍니다. 할당 설명은 모든 데이터 노드가 낮은 디스크 워터마크 위에 있기 때문에 클러스터가 할당할 수 없다고 말합니다. 해결 방법은 수동으로 샤드를 재라우팅하는 것이 아닙니다. 해결 방법은 용량입니다: 스냅샷을 찍은 후 오래된 인덱스를 삭제하고, 스토리지를 추가하고, 데이터 노드를 추가하거나, 콜드 데이터를 다른 곳으로 이동하세요.

또 다른 예: 롤링 재시작 후 3노드 클러스터가 노란색입니다. _cluster/health는 delayed_unassigned_shards: 8을 보여줍니다. 중지된 노드가 이미 돌아오고 있습니다. 이 경우 몇 분 기다리는 것이 올바를 수 있습니다. 즉시 할당을 강제하면 추가 복구 작업이 발생하고 재시작 속도가 느려질 수 있습니다.

세 번째 예: 단일 노드 랩 클러스터가 영원히 노란색입니다. _cat/shards는 할당되지 않은 모든 샤드가 복제본임을 보여줍니다. 인덱스에는 하나의 복제본이 있습니다. Elasticsearch가 올바르게 작동하고 있습니다. 랩의 경우 복제본을 0으로 설정하거나 두 번째 데이터 노드를 추가하세요.

상태 확인을 정직하게 유지

클러스터 상태는 모니터링의 일부여야 하지만, 알림 규칙에는 컨텍스트가 필요합니다. 빨간색은 즉시 알림을 보냅니다. 노란색은 짧은 유지보수 기간을 넘어 지속되거나, 할당되지 않은 복제본이 증가하거나, 이유가 디스크 압박인 경우 알림을 보냅니다. 상태 색상과 함께 디스크 워터마크, 노드 수, JVM 압박 및 스냅샷 성공을 추적하세요. 색상은 시작 위치를 알려주고, 샤드 및 할당 API는 다음에 수행할 작업을 알려줍니다.

상태 확인이 사용자 증상과 일치하지 않는 경우

때로는 클러스터가 녹색인데 사용자가 여전히 불평하는 경우가 있습니다. 이는 모순이 아닙니다. 클러스터 상태는 샤드 할당에 관한 것이지 쿼리 지연 시간이나 정확성에 관한 것이 아닙니다. 상태가 녹색이지만 검색이 느린 경우 검색 지연 시간, 스레드 풀, 핫 샤드, JVM 압박 및 스토리지 지연 시간으로 이동하세요. 과부하된 데이터 노드가 하나 있는 녹색 클러스터는 여전히 고장난 것처럼 느껴질 수 있습니다.

반대의 경우도 발생합니다. 클러스터가 무해한 이유(예: 복제본이 구성된 단일 노드 개발 환경)로 노란색일 수 있습니다. 유용한 습관은 상태를 비즈니스 영향과 연결하는 것입니다. 어떤 인덱스가 영향을 받았습니까? 기본 샤드입니까 복제본입니까? 애플리케이션이 지금 해당 인덱스에서 읽고 있습니까? 계획된 유지보수 중입니까? 이러한 질문은 모든 노란색 상태를 재난처럼 취급하지 않도록 합니다.

고객 대면 시스템의 경우 Elasticsearch 외부에 작은 런북 테이블을 유지하는 것을 좋아합니다: 인덱스 패턴, 소유 서비스, 데이터 소스, 스냅샷 정책, 데이터를 재생할 수 있는지 여부, 파괴적인 복구를 승인하는 사람. 빨간색 인시던트 중에 이 테이블은 종종 다른 대시보드보다 더 유용합니다. clickstream-*를 Kafka에서 재생할 수 있는 경우 복구 선택은 업스트림 복사본 없이 사용자 생성 문서를 보유한 인덱스와 다릅니다.

더 안전한 명령 습관

가능하면 명시적인 인덱스 이름을 사용하세요. 와일드카드는 편리하지만 영향 범위를 숨깁니다. 설정을 변경하거나 데이터를 삭제하는 명령을 실행하기 전에 패턴이 일치하는 항목을 나열하세요:

curl -s "http://localhost:9200/_cat/indices/logs-prod-*?v&s=index"

인시던트의 명령 출력을 보관하세요. 할당 설명 결과, 샤드 목록 및 상태 응답을 티켓에 붙여넣으세요. Elasticsearch 상태는 복구 중에 빠르게 변경되며, 결정이 내려진 이유를 이해하기 위해 이전 출력이 필요할 수 있습니다.

보안이 활성화된 경우 진단을 위한 최소한의 유용한 권한이 있는 사용자로 이러한 명령을 실행하고, 파괴적인 작업을 위한 별도의 더 제한된 프로세스를 사용하세요. 스트레스가 많은 인시던트에서는 상태만 검사하고 있던 동일한 셸에 쓰기 명령을 붙여넣기가 너무 쉽습니다.

클러스터가 녹색으로 돌아온 후 확인할 사항

녹색이 인시던트의 끝은 아닙니다. 예상한 노드에 복제본이 다시 빌드되었는지, 디스크가 여전히 워터마크에 가까운지, number_of_replicas: 0, 긴 refresh_interval 또는 비활성화된 할당과 같은 임시 설정으로 남겨진 인덱스가 있는지 확인하세요.

또한 복구 후 스냅샷이 성공적으로 수행되고 있는지 확인하세요. 방금 샤드 문제가 있었던 클러스터는 보존, 리포지토리 자격 증명 또는 스냅샷 스케줄링에 허점을 노출했을 수 있습니다. 복구가 스냅샷이 없어 운에 의존했다면 이를 기록하고 다음 장애 전에 수정하세요.

마지막으로 알림을 검토하세요. 모니터링보다 먼저 사람이 문제를 발견한 경우 빨간색 상태, 장기간 지속되는 노란색 상태, 디스크 워터마크 압박, 누락된 노드, 실패한 스냅샷 및 반복적인 마스터 선거에 대한 알림을 추가하거나 조정하세요. 클러스터 상태 색상은 유용하지만, 가장 좋은 알림은 색상이 변경된 이유와 영향을 받는 인덱스를 알려줍니다.