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

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

노란색 또는 빨간색 Elasticsearch 클러스터가 발생했나요? 할당되지 않은 샤드, 디스크 압박, 노드 손실 및 안전한 복구 옵션을 진단하세요.

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

노란색 또는 빨간색 Elasticsearch 클러스터는 미스터리 상태가 아닙니다. 일반적으로 Elasticsearch가 하나 이상의 샤드를 원하는 위치에 배치할 수 없음을 의미합니다. 작업은 어떤 샤드가 멈췄는지, 할당이 차단된 이유, 올바른 해결책이 대기, 리소스 확보, 노드 복구, 스냅샷 복원 또는 의도적인 데이터 손실 수용인지 찾는 것입니다.

클러스터 상태를 진단 자체가 아닌 분류 신호로 취급합니다. 녹색은 모든 기본 및 복제본 샤드가 할당되었음을 의미합니다. 노란색은 모든 기본 샤드가 할당되어 검색 및 쓰기가 일반적으로 계속될 수 있지만 하나 이상의 복제본이 누락되었음을 의미합니다. 빨간색은 하나 이상의 기본 샤드가 할당되지 않아 하나 이상의 인덱스의 일부를 사용할 수 없음을 의미합니다. 빨간색은 애플리케이션 읽기 또는 쓰기를 즉시 중단시킬 수 있습니다.

간단한 보기부터 시작하세요:

GET /_cluster/health?pretty
GET /_cat/health?v

status, number_of_nodes, active_primary_shards, unassigned_shards, initializing_shards 및 relocating_shards를 확인하세요. 노드 재시작 후 초기화 또는 재배치 중인 샤드가 보이면 클러스터가 이미 복구 중일 수 있습니다. Elasticsearch가 단순히 작업을 수행 중인지 알기 전에 할당 설정을 변경하지 마세요.

그런 다음 할당되지 않은 샤드를 나열하세요:

GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index,shard

prirep 열이 중요합니다. p 샤드는 기본입니다. 빨간색 클러스터에는 항상 하나 이상의 할당되지 않은 기본 샤드가 있습니다. r 샤드는 복제본입니다. 노란색 클러스터에는 일반적으로 할당되지 않은 복제본만 있습니다.

이 상황에서 가장 유용한 API는 할당 설명입니다:

GET /_cluster/allocation/explain?pretty

특정 샤드의 경우 명시적으로 지정하세요:

GET /_cluster/allocation/explain?pretty
{
  "index": "logs-2026.05.24",
  "shard": 0,
  "primary": false
}

can_allocate 답변과 노드 수준 결정을 읽으세요. Elasticsearch는 일반적으로 할당을 차단한 정확한 규칙(디스크 워터마크, 할당 필터링, 동일 샤드 규칙, 노드 이탈 후 지연 할당, 기본 데이터 누락, 호환되지 않는 버전 또는 노드 역할 불일치)을 알려줍니다.

클러스터가 노란색인 경우

노란색은 소규모 클러스터에서 흔합니다. 전형적인 경우는 number_of_replicas: 1인 단일 노드 개발 클러스터입니다. Elasticsearch는 복제본을 기본 샤드와 동일한 노드에 배치할 수 없으므로 복제본이 영원히 할당되지 않은 상태로 남습니다. 랩톱 환경에서는 긴급 상황이 아닙니다. 구성 불일치입니다.

복제본 수를 확인하세요:

GET /my-index/_settings?filter_path=*.settings.index.number_of_replicas

단일 노드 비프로덕션 클러스터의 경우 복제본을 0으로 설정하세요:

PUT /my-index/_settings
{
  "index": {
    "number_of_replicas": 0
  }
}

프로덕션의 경우 의도적으로 중복성을 줄이지 않는 한 복제본을 줄여 문제를 숨기지 마세요. 인덱스에 하나의 복제본이 있어야 하는 경우 최소 두 개의 적격 데이터 노드가 필요합니다. 두 개의 복제본이 있는 경우 최소 세 개의 적격 데이터 노드가 필요합니다. 계층화로 인해 덜 명확해질 수 있습니다. 웜 인덱스 복제본은 할당 규칙에 웜 노드가 필요한 경우 핫 전용 노드에 할당할 수 없습니다.

디스크 압박은 다음으로 흔한 노란색 원인입니다. 노드 디스크 사용량을 확인하세요:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,roles,disk.used_percent,disk.avail,heap.percent,cpu,load_1m

Elasticsearch는 디스크 워터마크를 사용하여 노드가 가득 차는 것을 방지합니다. 기본값은 버전 및 구성에 따라 다르므로 실제 클러스터 설정을 확인하세요:

GET /_cluster/settings?include_defaults=true&flat_settings=true&filter_path=**cluster.routing.allocation.disk.watermark**

노드가 높은 워터마크를 초과하면 Elasticsearch는 해당 노드에 더 많은 샤드를 할당하지 않습니다. 플러드 스테이지 워터마크에 도달하면 Elasticsearch는 노드를 보호하기 위해 영향을 받는 인덱스를 쓰기 차단 상태로 설정할 수 있습니다. 지속적인 해결책은 오래된 데이터를 삭제하고, 데이터를 더 많은 노드로 이동하고, 디스크를 늘리고, 과도하게 큰 샤드 수를 줄이거나, ILM 보존을 조정하는 것입니다. 일시적으로 워터마크를 높이면 시간을 벌 수 있지만 첫 번째 조치가 되어서는 안 됩니다.

실용적인 정리 순서는 다음과 같습니다:

GET /_cat/indices?v&s=store.size:desc
GET /_cat/shards?v&s=store:desc

크고 오래된 인덱스를 찾고, 소유 팀과 보존 기대치를 확인하고, 필요한 경우 스냅샷을 찍은 다음, 제거가 허용된 데이터만 삭제하세요:

DELETE /old-logs-2025.12.*

공간을 확보한 후 할당이 자동으로 재개될 수 있습니다. 그렇지 않은 경우 할당 설명을 다시 실행하세요. 이전 이유가 머리에 캐시되어 있을 수 있지만 클러스터는 이제 다른 규칙에 의해 차단될 수 있습니다.

할당 필터링은 특히 하드웨어 마이그레이션 후에 또 다른 빈번한 노란색 원인입니다. 누군가가 더 이상 존재하지 않는 노드 속성을 요구하도록 인덱스를 설정했을 수 있습니다:

GET /my-index/_settings?flat_settings=true&filter_path=*.settings.index.routing.allocation*
GET /_cluster/settings?flat_settings=true&filter_path=**routing.allocation**

규칙이 잘못된 경우 제거하거나 업데이트하세요:

PUT /my-index/_settings
{
  "index.routing.allocation.require.box_type": null,
  "index.routing.allocation.include._name": null,
  "index.routing.allocation.exclude._name": null
}

설정에 표시된 정확한 키를 사용하세요. 읽지 않고 프로덕션에 광범위한 재설정을 붙여넣지 마세요. 할당 규칙은 특정 데이터를 규정 준수 제어 계층에 유지하는 등 타당한 이유로 존재하는 경우가 있습니다.

클러스터가 빨간색인 경우

빨간색은 더 신중한 접근과 더 나은 기록이 필요합니다. 첫 번째 질문은 누락된 기본 샤드에 복구 가능한 복사본이 어딘가에 있는지 여부입니다.

할당되지 않은 기본 샤드를 나열하세요:

GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason | grep ' p UNASSIGNED'

그런 다음 어떤 노드가 있는지 확인하세요:

GET /_cat/nodes?v&h=name,ip,roles,master,uptime,heap.percent,disk.avail

노드가 누락된 경우 가장 좋은 복구 경로는 해당 노드를 다시 가져오는 것입니다. 누락된 노드의 서비스, 디스크 마운트, 호스트 네트워킹, 인증서 및 로그를 확인하세요. 데이터 경로에 대한 액세스 권한을 잃은 노드는 다른 빈 노드로 시작할 수 있으며, 이는 기본 샤드 복구에 도움이 되지 않습니다.

Elasticsearch 노드에서 로그는 일반적으로 API보다 더 빨리 실제 실패를 보여줍니다. 샤드 잠금 실패, 손상된 인덱스 파일, 마스터 검색, TLS 핸드셰이크 오류, 디스크 읽기 전용 파일 시스템 또는 노드 역할 변경에 대한 메시지를 찾으세요. 일반적인 실제 실패는 디스크가 다른 경로로 다시 마운트된 후 노드가 다시 시작되는 경우입니다. Elasticsearch는 시작되지만 데이터 경로가 비어 있어 클러스터에 필요한 샤드 복사본이 여전히 없습니다.

기본 샤드에 대한 할당 설명을 실행하세요:

GET /_cluster/allocation/explain?pretty
{
  "index": "orders-2026.05.24",
  "shard": 2,
  "primary": true
}

설명에 유효한 샤드 복사본을 찾을 수 없다고 표시되면 파괴적인 작업을 수행하기 전에 중단하고 스냅샷을 확인하세요:

GET /_snapshot/_all
GET /_snapshot/my-repository/_all?verbose=false

스냅샷 복원은 일반적으로 빈 기본 샤드를 할당하는 것보다 안전합니다. 빈 기본 샤드는 해당 샤드 ID에 대해 새로운 빈 샤드를 생성합니다. 복구 작업이 아닙니다. Elasticsearch에 "이 샤드의 이전 데이터가 사라졌음을 수락합니다"라고 알리는 것입니다.

최후의 수단 명령은 다음과 같습니다:

POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "orders-2026.05.24",
        "shard": 2,
        "node": "es-data-03",
        "accept_data_loss": true
      }
    }
  ]
}

사용 가능한 노드 복사본이 없고 복원할 수 있는 스냅샷이 없는지 확인한 후에만 사용하세요. 인시던트에서 해당 선택을 승인한 사람과 영향을 받은 인덱스 및 샤드를 기록하세요. 데이터 손실 결정이 명시적일 때 향후 디버깅이 훨씬 쉬워집니다.

할당 문제처럼 보이지만 실제로는 클러스터 문제인 경우

때로는 클러스터가 안정적인 멤버십을 유지할 수 없기 때문에 샤드가 할당되지 않습니다. 마스터 적격 노드가 서로 통신할 수 없으면 선출된 마스터가 반복적으로 변경될 수 있으며 할당이 중단되거나 일시 중지됩니다. 마스터 안정성을 확인하세요:

GET /_cat/master?v
GET /_cat/nodes?v&h=name,roles,master,ip

마스터가 자주 변경되면 네트워크 안정성, DNS, 노드 인증서 및 검색 설정을 검사하세요. 최신 Elasticsearch 클러스터의 경우 cluster.initial_master_nodes는 초기 클러스터 부트스트래핑을 위한 것이며 영구적인 검색 버팀목으로 남겨두는 설정이 아닙니다. discovery.seed_hosts는 적절한 시드 호스트를 가리켜야 하며 모든 노드는 동일한 클러스터 이름과 호환 가능한 보안 설정을 사용해야 합니다.

높은 JVM 압력도 할당 증상을 유발할 수 있습니다. 긴 가비지 컬렉션 일시 중지에 갇힌 데이터 노드는 마스터의 관점에서 클러스터를 이탈했다가 다시 합류할 수 있습니다. 이는 시스템이 완전히 충돌하지 않았더라도 할당되지 않은 샤드를 생성할 수 있습니다.

힙 및 가비지 컬렉션 로그를 확인하세요:

GET /_cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,node.role
GET /_nodes/stats/jvm?filter_path=nodes.*.jvm.mem,nodes.*.jvm.gc

힙이 지속적으로 높으면 맹목적으로 힙을 늘리지 마세요. Elasticsearch는 일반적으로 힙이 파일 시스템 캐시에 충분한 메모리를 남길 때 가장 잘 작동합니다. 과도한 집계, 많은 fielddata 사용, 너무 많은 샤드, 공격적인 인덱싱 또는 더 나은 매핑이 필요한 쿼리를 찾으세요.

샤드 수는 많은 상태 문제 뒤에 조용한 원인이 될 수 있습니다. 작은 샤드가 많은 클러스터는 메타데이터 추적 및 샤드 이동에 너무 많은 노력을 소비합니다. 다음을 사용하세요:

GET /_cat/indices?v&h=index,pri,rep,docs.count,store.size,pri.store.size&s=pri:desc
GET /_cluster/stats?filter_path=indices.shards,indices.count,nodes.count

모든 일일 로그 인덱스에 많은 기본 샤드가 있지만 데이터가 거의 없는 경우 향후 인덱스에 대한 인덱스 템플릿을 수정하세요. 그런 다음 기존 데이터에 대한 축소, 롤오버 또는 재인덱싱 계획을 고려하세요.

실용적인 분류 순서

누군가 "Elasticsearch가 빨간색입니다"라고 말하면 다음 순서를 사용합니다:

  1. _cluster/health로 상태를 확인합니다.
  2. _cat/shards로 할당되지 않은 샤드를 나열합니다.
  3. 기본 샤드 실패와 복제본 실패를 구분합니다.
  4. 대표 샤드 하나에 대해 _cluster/allocation/explain을 실행합니다.
  5. 예상되는 모든 노드가 있는지 확인합니다.
  6. 디스크 워터마크 및 할당 규칙을 확인합니다.
  7. 빨간색 기본 샤드의 경우 빈 기본 샤드 할당을 고려하기 전에 누락된 노드를 복구하거나 스냅샷에서 복원을 시도합니다.
  8. 클러스터가 녹색으로 전환된 후 처음에 비정상 상태를 만든 원인을 찾습니다.

마지막 단계가 중요합니다. 디스크를 추가하거나, 노드를 다시 시작하거나, 복제본을 줄인 후 클러스터가 녹색으로 전환될 수 있지만, ILM 보존이 잘못되었거나, 샤드 수가 너무 많거나, 노드 크기가 부족하거나, 배포 프로세스가 계속 노드 속성을 변경하는 경우 동일한 인시던트가 다시 발생합니다.

클러스터 상태 문제 해결은 하나의 마법 명령을 암기하는 것보다 추측을 거부하는 것에 더 가깝습니다. Elasticsearch는 할당 결정을 노출합니다. 이를 읽고 노드 및 인덱스 설정과 비교하여 확인하고 실제 차단자와 일치하는 가장 작은 수정을 선택하세요.

클러스터가 다시 녹색이 된 후

색상이 변경되었다고 해서 인시던트를 종료하지 마세요. 녹색은 지금 샤드가 할당되었음을 의미할 뿐입니다. 다음 트래픽 급증, 디스크 증가 주기 또는 노드 재시작에 클러스터가 충분히 건강하다는 것을 증명하지 않습니다. 세부 사항이 아직 생생할 때 간단한 사후 조치 노트를 작성하는 것이 좋습니다. 영향을 받은 인덱스, 관련된 노드, 복구를 차단한 할당 규칙 및 이를 수정한 명령 또는 인프라 변경 사항입니다.

수정으로 인해 새로운 위험이 발생했는지 확인하세요. 노란색을 녹색으로 바꾸기 위해 복제본을 줄인 경우 인덱스의 중복성이 줄어들었음을 기록하세요. 디스크 워터마크를 높인 경우 용량이 추가된 후 낮추라는 알림을 추가하세요. 스냅샷을 복원한 경우 애플리케이션이 정상 쓰기를 재개하기 전에 복원된 인덱스에 예상 별칭 및 쓰기 설정이 있는지 확인하세요.

몇 가지 빠른 확인은 미완료 작업을 찾는 데 도움이 됩니다:

GET /_cat/recovery?v&active_only=true
GET /_cat/pending_tasks?v
GET /_cat/aliases?v
GET /_cluster/health?wait_for_status=green&timeout=30s

pending_tasks는 영원히 증가해서는 안 됩니다. 복구는 결국 비어 있어야 합니다. 별칭은 중요합니다. 다른 이름으로 인덱스를 복원하면 애플리케이션이 손상된 이전 대상을 쓰거나 의도된 데이터의 일부만 읽을 수 있기 때문입니다.

또한 디스크 인시던트 후 쓰기 차단을 확인하세요:

GET /*/_settings?filter_path=*.settings.index.blocks*

Elasticsearch가 플러드 스테이지 차단을 설정한 경우 디스크 압력이 해결된 후에만 제거하세요:

PUT /my-index/_settings
{
  "index.blocks.read_only_allow_delete": null
}

가장 유용한 예방 작업은 일반적으로 지루합니다. 작동하는 스냅샷, 테스트된 복원, 현실적인 ILM 보존, 충분한 디스크 여유 공간 및 클러스터 크기와 일치하는 샤드 수입니다. 안정적인 스냅샷과 합리적인 샤드 크기를 갖춘 클러스터는 영리한 응급 명령과 복원 경로가 없는 클러스터보다 복구하기 훨씬 쉽습니다.

상태 인시던트 중 하지 말아야 할 일

모든 노드를 한 번에 다시 시작하지 마세요. 클러스터가 비정상적으로 보일 때 유혹적이지만 롤링하고 관찰하는 접근 방식이 더 안전합니다. 정상 노드를 다시 시작하면 Elasticsearch가 복구에 필요한 샤드 복사본을 제거할 수 있습니다. 다시 시작해야 하는 경우 한 번에 하나의 노드만 수행하고 단계 사이에 클러스터가 안정화될 때까지 기다리세요.

할당을 비활성화하고 잊지 마세요. 유지 관리 중에는 임시 할당 변경이 일반적이지만 잊어버린 설정은 유지 관리 기간이 끝난 후 오랫동안 복제본이 할당되지 않은 상태로 남을 수 있습니다. 항상 영구 및 일시적 설정을 모두 확인하세요:

GET /_cluster/settings?flat_settings=true&include_defaults=false

크기만 기준으로 인덱스를 삭제하지 마세요. 큰 인덱스는 비즈니스에 중요할 수 있습니다. 작은 인덱스는 제거해도 안전할 수 있습니다. 정리를 보존 정책, 스냅샷 및 애플리케이션 소유권과 연결하세요. 실제 중단에서 가장 빠른 안전한 정리는 일반적으로 정렬된 크기 목록에서 추측하는 것이 아니라 만료된 로그 또는 메트릭 인덱스를 삭제하는 것입니다.

Kibana와 Elasticsearch가 문제에 대해 동일한 언어를 사용한다고 가정하지 마세요. Kibana는 광범위한 빨간색 상태를 표시할 수 있지만 Elasticsearch API는 정확한 할당되지 않은 샤드를 표시합니다. 가시성을 위해 UI를 사용하지만 결정을 위해 API를 사용하세요.