SHARD ALLOCATION

OpenSearch red·unassigned shard 장애

cluster health에서 primary·replica unassigned를 구분하고 Allocation Explain의 disk·filter·awareness·same_shard·max_retry 결정을 확인해 강제 stale primary 없이 안전하게 재할당합니다.

OpenSearch red clusterunassigned shardscluster allocation explaindisk watermarksame_shard replicaretry_failed reroute

환경OpenSearch 2.x·3.x · Security plugin HTTPS · cluster monitor와 승인된 snapshot status 조회 권한의 0600 netrc

분류데이터베이스

검토일2026-09-04

진행5단계 · 조회 우선

SAFE OPERATING BOUNDARY

중단·복구 기준부터 확인하세요

STOP CONDITIONS

여기서는 멈추세요

red primary와 yellow replica, 정확한 index·shard·Allocation Explain 결과를 구분하지 못했다면 reroute를 실행하지 않습니다.
no_valid_shard_copy·corruption이고 검증된 snapshot·원본 node·RPO 승인이 없다면 강제 primary 할당이나 index 삭제를 하지 않습니다.
netrc가 0600이 아니거나 TLS 검증·최소 cluster monitor 권한이 준비되지 않았다면 API 진단을 중단합니다.

ROLLBACK

복구 기준

retry_failed 자체는 설정을 바꾸지 않고 재할당을 재시도합니다. 장애 중 수정한 persistent·transient allocation setting과 index replica/filter는 0600 backup과 change diff의 정확한 이전 값으로 복원하고 Allocation Explain·health를 다시 확인합니다. shard data가 손상됐거나 유효 copy가 없다면 검증된 snapshot과 같은 OpenSearch 호환 버전으로 복원하며 강제 stale primary 할당을 rollback 수단으로 사용하지 않습니다.

ESCALATION PACK

담당자에게 전달할 자료

cluster health의 status·primary·unassigned·pending task와 shard별 prirep·reason
Allocation Explain의 can_allocate·decider·disk 정보, node role·attribute·index/cluster allocation setting
node·recovery 로그 요약, snapshot 상태와 설정 backup checksum, retry 전후 health·업무 조회 결과

2026년 9월 4일 기준 공식 upstream 문서와 현재 지원 명령을 대조했습니다. 먼저 최소 범위 읽기 전용 조회로 사실을 확인하고, 변경은 영향·백업·복구 경로와 담당자 승인을 확보한 대상에만 적용합니다. <...> 자리표시자는 승인된 리터럴 값으로 직접 치환하며 외부 입력으로 shell 명령을 조립하거나 eval하지 않습니다.

BEFORE YOU START

이런 증상에서 시작합니다

_cluster/health가 red이고 active primary shard가 부족함
yellow 상태에서 replica shard가 unassigned로 남음
Allocation Explain에 disk_threshold·filter·awareness·same_shard NO가 표시됨
failed allocation retries exceeded 또는 no_valid_shard_copy가 표시됨

CHECK THE BRANCH

놓치기 쉬운 원인 분기

red와 unassigned primary인 경우

일부 데이터가 조회되지 않을 수 있는 우선 복구 상황입니다. 유효 shard copy·snapshot 존재를 확인하고 accept_data_loss 강제 할당을 실행하지 않습니다.

yellow와 unassigned replica인 경우

primary는 사용 가능하지만 redundancy가 부족합니다. 단일 node의 same_shard면 replica 수 설계와 운영 복원력을 재검토합니다.

disk_threshold·filter·awareness가 NO인 경우

disk 여유, index·cluster allocation filter, node role·attribute와 zone topology를 원래 설계에 맞게 복구합니다. watermark를 임시로 무력화하지 않습니다.

max_retry 또는 recovery 실패인 경우

disk·network·permission·corruption 원인을 먼저 해결하고 dry-run으로 reroute 결정을 확인한 뒤 retry_failed를 한 번만 실행합니다.

FOLLOW THE FLOW

순서대로 확인하기

조회시스템을 변경하지 않는 확인 단계

cluster health·unassigned primary/replica 확인

TLS 검증을 유지하고 0600 netrc 또는 승인된 credential helper를 사용합니다. 먼저 red/yellow와 unassigned 개수, shard role·reason만 확인합니다.

credential 권한

stat -Lc '%a %U:%G %n' <OPENSEARCH_NETRC>

cluster health

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cluster/health?filter_path=cluster_name,status,timed_out,number_of_nodes,number_of_data_nodes,active_primary_shards,unassigned_shards,delayed_unassigned_shards,number_of_pending_tasks'

unassigned shard

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cat/shards?h=index,shard,prirep,state,unassigned.reason,node&s=state,index,shard'

index·node 이름은 내부 식별정보이므로 외부 공유 전에 마스킹합니다.

node 목록

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cat/nodes?h=name,ip,node.role,master,disk.used_percent,heap.percent,ram.percent,cpu&s=name'

결과 읽기

red는 최소 한 primary가 unassigned, yellow는 primary는 모두 배정됐지만 replica 일부가 unassigned입니다. 우선순위와 데이터 위험이 다릅니다.

다음 판단

첫 unassigned shard의 Allocation Explain과 disk 정보를 조회합니다.

조회시스템을 변경하지 않는 확인 단계

Allocation Explain으로 차단 decider 확인

빈 body는 첫 unassigned shard를 설명합니다. 특정 shard는 index·shard·primary를 검토한 JSON 파일로 지정하고 include_disk_info를 켭니다.

첫 unassigned 설명

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> -H 'Content-Type: application/json' -X POST 'https://<OPENSEARCH_HOST>:9200/_cluster/allocation/explain?include_disk_info=true' --data '{}'

특정 shard 설명

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> -H 'Content-Type: application/json' -X POST 'https://<OPENSEARCH_HOST>:9200/_cluster/allocation/explain?include_disk_info=true&include_yes_decisions=false' --data-binary @<REVIEWED_SHARD_REQUEST.json>

JSON에는 index·shard·primary만 넣고 credential은 넣지 않습니다.

allocation·disk

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cat/allocation?h=node,shards,disk.indices,disk.used,disk.avail,disk.percent&s=disk.percent:desc'

결과 읽기

can_allocate와 각 decider의 NO·THROTTLE 설명을 그대로 분류합니다. same_shard, disk_threshold, filter, awareness, enable, max_retry, no_valid_shard_copy는 서로 다른 해결책이 필요합니다.

다음 판단

cluster·index setting과 node role·disk·snapshot 상태를 최소 범위로 확인합니다.

조회시스템을 변경하지 않는 확인 단계

disk·allocation setting·node role·snapshot 확인

persistent·transient allocation setting과 대상 index의 replica/filter, node role·attribute를 확인합니다. 전체 mapping·document는 조회하지 않습니다.

cluster allocation setting

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cluster/settings?flat_settings=true&include_defaults=true&filter_path=persistent.cluster.routing.allocation.*,transient.cluster.routing.allocation.*,defaults.cluster.routing.allocation.*'

대상 index setting

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/<URL_ENCODED_INDEX>/_settings?flat_settings=true&filter_path=*.settings.index.number_of_replicas,*.settings.index.routing.allocation.*,*.settings.index.unassigned.*'

node role·attribute

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_nodes?filter_path=nodes.*.name,nodes.*.roles,nodes.*.attributes,nodes.*.fs.total'

snapshot 상태

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_snapshot/_status?ignore_unavailable=true'

repository·index·node 이름이 포함될 수 있어 제한된 터미널에서 확인합니다.

결과 읽기

disk 부족은 데이터를 검토된 보존 정책으로 줄이거나 node 용량을 복구하고, filter·awareness는 실제 topology와 맞춥니다. 단일 node replica는 물리적으로 배정될 수 없습니다.

다음 판단

node 로그와 shard copy·snapshot 존재를 확인하고 안전한 최소 변경을 정합니다.

주의서버 부하나 권한을 고려할 단계

node 오류·유효 shard copy·복구 입력 확인

no_valid_shard_copy·corruption·node left면 데이터 손실 위험이 큽니다. node를 되살리거나 검증된 snapshot 복원을 우선하며 stale primary 강제 할당은 안내하지 않습니다.

OpenSearch service 로그

journalctl -u opensearch.service --since '<INCIDENT_START>' --until '<INCIDENT_END>' --no-pager | grep -Ei -C 5 'shard|allocation|recovery|corrupt|disk|watermark|exception|error'

index·query·문서 일부가 포함될 수 있어 공유 전에 마스킹합니다.

recovery 상태

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cat/recovery?h=index,shard,time,type,stage,source_node,target_node,files_percent,bytes_percent,translog_ops_percent&s=time:desc'

pending task

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cluster/pending_tasks'

설정 증거 백업

install -d -m 0700 <APPROVED_BACKUP_DIR>
umask 077
curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cluster/settings?flat_settings=true' > <APPROVED_BACKUP_DIR>/cluster-settings.before.json
chmod 0600 <APPROVED_BACKUP_DIR>/cluster-settings.before.json
sha256sum <APPROVED_BACKUP_DIR>/cluster-settings.before.json

결과 읽기

corruption·유효 copy 없음이면 retry가 데이터를 만들지 못합니다. snapshot checksum·복원 지점과 업무 RPO를 확인하고 데이터 담당자에게 escalation합니다.

다음 판단

disk·node·filter 원인을 해결한 뒤 reroute dry-run과 retry_failed 한 번을 승인합니다.

변경데이터·서비스 상태가 달라질 수 있는 단계

원인 복구 후 reroute dry-run·retry와 health 검증

disk·node·permission·allocation filter 같은 근본 원인을 먼저 복구합니다. 그 뒤 dry-run으로 결정을 확인하고 max_retry에 막힌 shard만 한 번 재시도합니다.

변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.

retry dry-run

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> -H 'Content-Type: application/json' -X POST 'https://<OPENSEARCH_HOST>:9200/_cluster/reroute?dry_run=true&retry_failed=true&explain=true' --data '{}'

승인된 retry_failed 1회

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> -H 'Content-Type: application/json' -X POST 'https://<OPENSEARCH_HOST>:9200/_cluster/reroute?retry_failed=true&explain=true' --data '{}'

dry-run이 예상 shard만 재시도하고 근본 원인이 해소됐음을 확인한 뒤 한 번만 실행합니다. allocate_stale_primary·accept_data_loss는 사용하지 않습니다.

health 대기

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cluster/health?wait_for_status=yellow&timeout=60s&filter_path=status,timed_out,active_primary_shards,unassigned_shards,initializing_shards,relocating_shards,number_of_pending_tasks'

남은 unassigned 설명

curl --fail --silent --show-error --netrc-file <OPENSEARCH_NETRC> 'https://<OPENSEARCH_HOST>:9200/_cat/shards?h=index,shard,prirep,state,unassigned.reason,node&s=state,index,shard'

결과 읽기

red가 해소되고 primary가 모두 active여야 최소 복구입니다. yellow가 남으면 replica redundancy가 부족하므로 topology·replica 설계를 계속 복구합니다.

다음 판단

retry_failed는 되돌릴 설정이 아니라 allocation 재시도입니다. 설정 변경을 했다면 0600 backup의 persistent·transient 값을 검토해 원복하고 dry-run·health를 재검증합니다. data-loss 강제 할당 대신 유효 node·snapshot 복원을 사용합니다.

PRIMARY REFERENCES

공식 문서

배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.

중단·복구 기준부터 확인하세요

여기서는 멈추세요

복구 기준

담당자에게 전달할 자료

이런 증상에서 시작합니다

놓치기 쉬운 원인 분기

red와 unassigned primary인 경우

yellow와 unassigned replica인 경우

disk_threshold·filter·awareness가 NO인 경우

max_retry 또는 recovery 실패인 경우

순서대로 확인하기

공식 문서

함께 확인할 가이드