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

일반적인 Elasticsearch 샤드 할당 실패 문제 해결

일반적인 Elasticsearch 샤드 할당 실패를 식별하고 해결하는 방법을 배웁니다. 이 가이드는 할당되지 않은 샤드 식별, 디스크 공간 오류, 노드 사용 불가, 할당 필터링과 같은 문제 진단, 그리고 건강한 Elasticsearch 클러스터를 유지하기 위한 실행 가능한 솔루션과 모범 사례를 다룹니다.

일반적인 Elasticsearch 샤드 할당 실패 문제 해결

샤드 할당 실패는 Elasticsearch가 추상화를 멈추는 지점입니다. 클러스터 상태가 노란색이나 빨간색으로 변하고, 검색 결과가 부분적으로 반환되며, 인덱싱 속도가 느려지고, 팀은 문제가 디스크, 누락된 노드, 잘못된 할당 규칙 또는 손상된 샤드 데이터 중 무엇인지 파악해야 합니다.

제가 가장 자주 보는 실수는 모든 할당되지 않은 샤드를 동일하게 취급하는 것입니다. 계획된 재시작 후 지연된 복제본 샤드는 주요 주문 인덱스의 할당되지 않은 기본 샤드와 같은 긴급 상황이 아닙니다. 어떤 샤드가 할당되지 않았는지, 기본 샤드인지 복제본인지, 그리고 Elasticsearch가 할당 결정에 대해 무엇을 말하는지부터 시작하세요.

상태 신호를 올바르게 읽기

클러스터 상태부터 시작하세요:

GET /_cluster/health?pretty

중요한 필드는 status, active_primary_shards, active_shards, relocating_shards, initializing_shards, unassigned_shards, delayed_unassigned_shards입니다.

노란색은 모든 기본 샤드가 할당되었지만 하나 이상의 복제본이 할당되지 않았음을 의미합니다. 데이터는 여전히 사용 가능해야 하지만 중복성이 줄어듭니다.

빨간색은 하나 이상의 기본 샤드가 할당되지 않았음을 의미합니다. Elasticsearch가 복제본을 승격시키거나, 샤드가 있던 노드를 복구하거나, 스냅샷에서 복원할 수 없는 한 해당 샤드의 데이터는 사용할 수 없습니다.

relocating_shards 또는 initializing_shards가 0이 아닌 경우 클러스터가 이미 복구 중일 수 있습니다. 일시적으로 색상이 노란색이라고 해서 정상적인 복구를 방해하지 마십시오.

할당되지 않은 샤드 나열

_cat/shards를 사용하여 정확한 문제를 확인하세요:

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

UNASSIGNED를 찾으세요. prirep 열은 샤드가 기본(p)인지 복제본(r)인지 알려줍니다. unassigned.reason 열은 NODE_LEFT, INDEX_CREATED, CLUSTER_RECOVERED 또는 ALLOCATION_FAILED와 같은 간단한 이유를 제공합니다.

대규모 클러스터의 경우 범위를 좁히세요:

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

인덱스, 샤드 번호 및 기본/복제본 플래그를 확인한 후 Elasticsearch에 실제 설명을 요청하세요.

할당 설명 API 사용

현재 할당되지 않은 샤드의 경우:

GET /_cluster/allocation/explain
{}

특정 샤드의 경우:

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

can_allocate, allocate_explanation, unassigned_info 및 node_allocation_decisions를 읽으세요. 노드 결정은 특히 각 노드가 거부된 이유를 보여주기 때문에 유용합니다. 일반적인 결정자에는 디스크 임계값, 동일 샤드 규칙, 할당 필터, 인식 규칙 및 노드당 총 샤드 수 제한이 포함됩니다.

출력에 기본 샤드에 대해 no_valid_shard_copy가 표시되면 심각하게 받아들이세요. Elasticsearch는 현재 해당 기본 샤드의 사용 가능한 복사본을 보지 못합니다.

원인 1: 적합한 노드 부족

복제본이 하나 있는 단순한 단일 노드 클러스터는 영원히 노란색으로 유지됩니다. Elasticsearch는 복제본을 기본 샤드와 동일한 노드에 배치하지 않습니다. 두 개의 복제본으로 구성된 인덱스가 있는 3노드 클러스터에는 세 개의 적합한 데이터 노드가 필요합니다. 할당 인식에서 복사본을 영역에 분산해야 하는 경우 필요한 영역에 충분한 노드도 필요합니다.

복제본 설정 확인:

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

이것이 실험실 또는 임시 환경인 경우 복제본을 줄이세요:

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

프로덕션의 경우 일반적으로 적합한 데이터 노드를 추가하거나 비현실적인 복제본 수를 조정하는 것이 더 나은 해결책입니다. 복제본을 낮추면 중복성이 제거됩니다.

원인 2: 디스크 워터마크

디스크 압력은 가장 일반적인 할당 차단 요인 중 하나입니다. Elasticsearch는 디스크 워터마크를 사용하여 노드가 가득 차는 것을 방지합니다. 노드가 임계값을 초과하면 Elasticsearch는 샤드 할당을 중지하고 샤드를 이동시킬 수 있습니다.

할당 및 디스크 사용량 확인:

GET /_cat/allocation?v
GET /_cat/nodes?v&h=name,ip,disk.used_percent,disk.avail,heap.percent,ram.percent,node.role

할당 설명 출력은 노드가 낮거나 높은 디스크 워터마크 위에 있다고 말할 수 있습니다. 인덱스가 플러드 스테이지 조건에 도달한 경우 Elasticsearch는 영향을 받는 인덱스에 쓰기 차단을 설정할 수도 있습니다.

좋은 수정은 용량 수정입니다: 스냅샷을 확인한 후 오래된 인덱스 삭제, 디스크 추가, 데이터 노드 추가, 데이터를 다른 계층으로 이동, 또는 인덱스 수명 주기 관리를 통해 보존 기간 단축.

통제된 비상 상황에서 워터마크를 변경하는 것은 합리적일 수 있지만 용량 계획은 아닙니다. 모든 데이터 노드가 거의 가득 찬 경우 임계값을 높이면 클러스터가 실패에 더 가깝게 실행될 뿐입니다.

플러드 스테이지 이벤트 후 공간을 확보한 후 읽기 전용 차단을 확인하세요:

GET /my-index/_settings?filter_path=*.settings.index.blocks.write,*.settings.index.blocks.read_only_allow_delete

디스크 압력이 해결된 후에만 차단을 제거하세요:

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

원인 3: 유지 보수 후 할당 비활성화

팀은 종종 롤링 유지 보수 중에 할당을 비활성화한 다음 다시 활성화하는 것을 잊어버립니다.

클러스터 설정 확인:

GET /_cluster/settings?include_defaults=true&pretty

cluster.routing.allocation.enable을 찾으세요. 값에는 all, primaries, new_primaries 및 none이 포함됩니다. none인 경우 복제본 및 기타 샤드 이동이 정상적으로 할당되지 않습니다.

할당 다시 활성화:

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

또한 transient 설정을 확인하세요. 일시적인 유지 보수 설정은 영구 섹션이 정상으로 보이더라도 여전히 클러스터에 영향을 미칠 수 있습니다.

원인 4: 제한적인 할당 필터

인덱스 수준 필터는 인덱스를 특정 노드에 고정할 수 있습니다:

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

클러스터 수준 필터는 노드를 할당에서 제외할 수 있습니다:

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

노드 속성도 중요합니다:

GET /_cat/nodeattrs?v

일반적인 실패는 다음과 같습니다: 인덱스에 box_type: hot이 필요하지만 핫 노드가 교체되었고 새 노드에 node.attr.box_type: hot이 없습니다. Elasticsearch는 규칙을 정확히 따르고 있습니다. 규칙이 이제 잘못되었습니다.

지나치게 제한적인 인덱스 필터를 제거하려면:

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

인덱스에 있는 정확한 설정 이름을 사용하세요. 실제 영역 또는 계층 요구 사항을 인코딩하는 할당 규칙을 맹목적으로 제거하지 마십시오.

원인 5: 노드 이탈 후 지연된 할당

노드가 이탈하면 Elasticsearch는 복제본 샤드 할당을 지연시킬 수 있습니다. 노드가 빠르게 돌아올 수 있기 때문입니다. 이는 정상적인 재시작 중에 큰 샤드를 네트워크를 통해 복사하는 것을 방지합니다.

지연된 샤드 확인:

GET /_cluster/health?pretty

delayed_unassigned_shards가 0보다 크고 노드가 돌아올 것으로 예상되면 기다리는 것이 가장 좋은 조치일 수 있습니다. 또한 인덱스 설정을 검사할 수 있습니다:

GET /my-index/_settings?filter_path=*.settings.index.unassigned.node_left.delayed_timeout

기본값은 일반적으로 1분이지만 항상 클러스터와 버전을 확인하세요. 일부 팀은 큰 샤드의 계획된 롤링 재시작을 위해 이를 늘립니다. 실제 실패로 인해 복제본이 불편할 정도로 오래 누락되지 않도록 너무 길게 설정하지 마십시오.

원인 6: 노드에 너무 많은 샤드

index.routing.allocation.total_shards_per_node는 하나의 인덱스에서 동일한 노드에 있을 수 있는 샤드 수를 제한할 수 있습니다. 클러스터 수준 샤드 제한도 적용될 수 있습니다. 이러한 설정은 유용하지만 소규모 클러스터에서 할당을 차단할 수 있습니다.

인덱스 설정 확인:

GET /my-index/_settings?filter_path=*.settings.index.routing.allocation.total_shards_per_node

5개의 기본 샤드, 1개의 복제본, 2개의 데이터 노드 및 낮은 노드당 제한이 있는 경우 Elasticsearch는 합법적인 배치를 찾지 못할 수 있습니다. 제한을 수정하거나, 노드를 추가하거나, 샤드 수를 재설계하세요.

원인 7: 기본 샤드의 유효한 복사본 없음

이것은 무서운 경우입니다. 할당 설명은 기본 샤드에 대한 유효한 샤드 복사본이 없다고 보고할 수 있습니다. 기본 샤드가 있는 유일한 노드가 사라졌을 수 있습니다. 디스크가 실패했을 수 있습니다. 샤드 데이터가 손상되었을 수 있습니다.

먼저, 누락된 노드가 돌아올 것으로 예상되면 복구를 시도하세요. 시스템 로그, Elasticsearch 로그, 디스크 상태 및 네트워크 연결을 확인하세요. 유효한 복제본이 있으면 Elasticsearch는 일반적으로 이를 승격시켜야 합니다.

유효한 복사본이 없으면 스냅샷에서 복원하세요:

POST /_snapshot/my_repository/snapshot_name/_restore
{
  "indices": "affected-index"
}

데이터를 소스 시스템에서 재구축할 수 있고 샤드 내용 손실을 수용하는 경우 allocate_empty_primary를 사용할 수 있지만 데이터 손실 작업입니다:

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

누락된 데이터가 사라졌거나 재구축 가능하다고 의식적으로 결정하지 않는 한 "클러스터를 녹색으로 만들기" 위해 이것을 사용하지 마십시오.

복구 모니터링

변경 후 진행 상황을 모니터링하세요:

GET /_cat/recovery?v&active_only=true
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
GET /_cluster/health?pretty

큰 샤드는 시간이 걸립니다. _cat/recovery에서 바이트 수가 이동 중이면 클러스터가 작동 중인 것입니다. 아무 변화도 없으면 할당 설명을 다시 확인하세요. 첫 번째 수정 후 Elasticsearch의 결정이 변경되어 다음 차단 요인이 드러날 수 있습니다.

실제로 도움이 되는 예방

워터마크에 도달하기 전에 디스크를 모니터링하세요. 단순히 가득 찬 디스크가 아닌 추세에 대해 경고하세요.

로그 및 메트릭에 ILM 또는 데이터 스트림을 사용하여 보존이 자동으로 이루어지도록 하세요.

스냅샷을 최신 상태로 유지하고 복원을 테스트하세요. 복원한 적이 없는 스냅샷은 희망에 불과합니다.

샤드 크기와 샤드 수를 합리적으로 유지하세요. 너무 많은 작은 샤드는 할당 및 복구를 데이터 볼륨이 암시하는 것보다 느리게 만듭니다.

할당 필터 및 노드 속성을 문서화하세요. 6개월 후에 누군가가 노드를 교체하고 인덱스를 할당 가능하게 만든 속성을 잊어버릴 것입니다.

노란색을 경고로, 빨간색을 인시던트로 취급하세요. 노란색은 유지 보수 중에 허용될 수 있지만 배경 소음이 되어서는 안 됩니다. 빨간색은 적어도 하나의 기본 샤드를 사용할 수 없음을 의미하며, 기다릴수록 쉬운 복구 옵션이 줄어들 수 있습니다.

인시던트를 위한 현장 체크리스트

샤드 할당이 중단되면 매번 동일한 증거를 수집하세요. 이렇게 하면 팀이 이론 사이를 오가는 것을 방지할 수 있습니다.

실행:

GET /_cluster/health?pretty
GET /_cat/nodes?v&h=name,ip,roles,master,disk.used_percent,heap.percent,ram.percent
GET /_cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason&s=state,index
GET /_cat/allocation?v
GET /_cat/recovery?v&active_only=true
GET /_cluster/settings?include_defaults=true&pretty

그런 다음 대표적인 할당되지 않은 샤드에 대해 할당 설명을 실행하세요. 여러 개가 있으면 이유별로 그룹화하세요. 디스크 워터마크로 인해 차단된 10개의 할당되지 않은 복제본은 하나의 문제입니다. no_valid_shard_copy가 있는 3개의 기본 샤드는 다른 문제입니다.

영향을 받는 데이터를 재구축할 수 있는지 기록하세요. 업스트림 큐의 로그, 에이전트의 메트릭 및 파생 검색 인덱스는 소스 시스템에서 복구할 수 있습니다. 사용자 생성 콘텐츠 또는 규정 준수 기록은 그렇지 않을 수 있습니다. 복구 명령은 비즈니스 현실을 따라야 합니다.

기다려야 할 때와 행동해야 할 때

복구가 활발히 진행 중이거나, 누락된 노드가 곧 돌아올 것으로 예상되거나, 지연된 할당이 정확히 구성한 대로 수행되고 있을 때 기다리세요. _cat/recovery로 진행 상황을 확인할 수 있습니다. 이동하는 바이트 수와 파일 수는 좋은 신호입니다.

할당 설명이 영구적인 차단 요인(적합한 노드 없음, 모든 노드의 디스크 워터마크, 할당 비활성화, 누락된 노드 속성 또는 유효한 샤드 복사본 없음)을 표시할 때 행동하세요. 기다리는 것은 모든 노드를 거부하는 규칙을 수정하지 않습니다.

중요한 인덱스의 기본 샤드가 할당되지 않은 경우 신속하게 에스컬레이션하세요. 복제본 실패는 안전성을 감소시킵니다. 기본 샤드 실패는 가용성을 감소시킵니다.

복구 속도를 늦추지 않기

대규모 복구는 일반 검색 및 인덱싱과 경쟁합니다. 한 번에 너무 많은 노드를 추가하거나, 더 많은 노드를 다시 시작하거나, 디스크 및 네트워크 용량을 확인하지 않고 복구 동시성을 높이면 클러스터가 덜 안정적이 될 수 있습니다.

복구 설정을 조정하는 경우 의도적으로 수행하고 원래 값을 기록하세요. 동시 복구와 같은 설정은 일부 환경에서는 도움이 되고 다른 환경에서는 해가 될 수 있습니다. 이론상 더 빠른 복구는 디스크에 과부하를 주고 쿼리 지연 시간을 증가시켜 사용자가 더 심각한 중단을 경험할 수 있습니다.

핫 노드를 주시하세요. 할당은 기술적으로 성공할 수 있지만 샤드 크기, 계층 규칙 또는 고르지 않은 디스크 사용량으로 인해 하나의 노드에 너무 많은 작업을 배치할 수 있습니다. _cat/allocation, 노드 통계 및 모니터링 시스템을 사용하여 즉각적인 실패가 해결된 후 클러스터가 균형을 이루는지 확인하세요.

사후 조치

대부분의 샤드 할당 인시던트에는 예방 스토리가 있습니다. 디스크 워터마크 인시던트는 보존, ILM 또는 용량 계획을 가리킵니다. 할당 필터 인시던트는 누락된 런북 문서를 가리킵니다. 유효한 복사본 없음 인시던트는 스냅샷 및 업스트림 재생을 가리킵니다. 느린 복구는 샤드 크기 및 하드웨어를 가리킵니다.

상태가 녹색이라고 해서 인시던트를 종료하지 마십시오. 임시 복제본 변경을 제거하고, 정상적인 새로 고침 간격을 복원하고, 변경된 경우 할당을 다시 활성화하고, 스냅샷을 확인하고, 이전에 문제를 잡았을 알림을 추가하세요.

특수 사례: 닫힌 인덱스와 숨겨진 인덱스

때로는 인덱스가 닫혀 있거나, 숨겨져 있거나, 건드리고 있다는 것을 몰랐던 시스템 기능의 일부이기 때문에 할당되지 않을 수 있습니다. 시스템 인덱스가 있는 경우 광범위한 와일드카드 명령을 주의하세요. 최신 클러스터에서는 보안, Kibana, 변환 및 기타 스택 기능이 자체 인덱스를 유지 관리할 수 있습니다.

좁은 패턴을 사용하고 검사하려는 경우에만 숨겨진 인덱스를 포함하세요. 시스템 인덱스에 할당 문제가 있는 경우 Elasticsearch뿐만 아니라 관련 스택 구성 요소 로그도 확인하세요. 예를 들어, Kibana 저장 객체 인덱스 문제는 Elasticsearch 샤드 할당 문제와 Kibana 시작 실패로 나타날 수 있습니다.

규칙은 사용자 데이터와 동일합니다: 정확한 인덱스를 식별하고, 그것을 소유한 것이 무엇인지 이해한 다음, 수정을 선택하세요. 제품 수준 영향을 이해하지 않는 한 빨간색 상태를 지우기 위해 시스템 인덱스를 삭제하거나 강제 할당하지 마십시오.