elasticsearch-cluster-health

クラスターの健全性を診断する

非グリーン状態の Elasticsearch クラスターを読み取り専用でトリアージします。問題の箇所を特定し、割り当て判定要因を分類して、最も可能性の高い原因を1つ、対処方法とともに報告します。クラスターの状態は決して変更せず、調査結果を提示して、オペレーターが対応できるようにします。

環境設定

このスキルは elastic CLI を通じて Elasticsearch の操作を実行します。 elastic CLI がインストールされていない場合は、何に必要なのかをユーザーに伝えてください。認証情報を推測したり、HTTP API を直接呼び出したり、ほかの回避策を試したりしないでください。

このスキルでは、HTTP 短縮形式（例：GET /、GET /_cat/indices、GET /{index}/_mapping、 GET /{index}/_settings/index.mode、POST /_query）で操作を記載しています。このドキュメント末尾の 操作テーブルでは、各短縮形式に対応する elastic CLI コマンドを示しています。HTTP API を直接呼び出すのではなく、必ず CLI を使用してください。

手順

1. 全体のステータスを確認します。 GET /_cluster/health を呼び出します。判定には status フィールドを使用します。

   • green — すべてのプライマリとレプリカが割り当てられています。正常であると報告し、終了します。
   • yellow — すべてのプライマリは割り当てられていますが、少なくとも1つのレプリカが割り当てられていません。データは引き続き読み取れますが、冗長性が低下しています。これはデータ損失ではありません。
   • red — 少なくとも1つのプライマリが割り当てられていません。そのシャードのデータは利用できない状態のため、緊急として扱います。

   unassigned_shards、initializing_shards、relocating_shards も確認します。判定：ステータスが yellow または red の場合にのみ続行します。initializing_shards > 0 かつ unassigned_shards == 0 の場合、クラスターは自動的に復旧中です。GET /_cat/recovery を呼び出して進捗を確認し、待機したうえで、エスカレーションする前に GET /_cluster/health を再確認します。

   必要なデータ：クラスター全体の status とシャード数。

2. 問題を1つのインデックスに絞り込みます。 GET /_cluster/health?level=indices を呼び出し、クラスター全体のステータスに影響しているインデックスを選びます。

   • red のインデックスは、どの yellow のインデックスよりも優先します。
   • red または yellow のインデックスの中では、unassigned_shards が最も多いものを優先します。
   • red のシステムインデックス（.security、.kibana*、.fleet-*）は、スタックの残りがこれに依存しているため、アプリケーションのインデックスより優先します。

   必要に応じて GET /_cat/shards/{index}?h=index,shard,prirep,state,unassigned.reason を呼び出し、そのインデックス内の未割り当てシャードをすべて一覧表示して、障害がプライマリ（prirep=p）かレプリカ（prirep=r）かを確認します。

   判定：以降の手順では、クラスターの復旧につながるインデックスを1つだけ対象にします。

   必要なデータ：インデックスごとの status と unassigned_shards。取得できる場合はシャードの役割（プライマリかレプリカか）。

3. トリガーと根本原因を切り分けます。 本文を指定せずに POST /_cluster/allocation/explain を呼び出して、Elasticsearch に未割り当てシャードを選ばせるか、最も問題のあるシャードを明示的に指定します。

   { "index": "<index>", "shard": <id>, "primary": <true|false> }
   

   次のフィールドを順番に確認します。

   • primary — false はレプリカが未割り当て（通常は yellow）、true はプライマリが未割り当て（通常は red）であることを示します。
   • can_allocate — 割り当てに関する最上位の判定（no、yes、throttled、no_valid_shard_copy など）です。
   • unassigned_info.reason — 再割り当てのトリガー（例：NODE_LEFT、INDEX_CREATED）です。can_allocate が no の場合、これは根本原因ではありません。シャードが未割り当てになった理由を説明するだけです。
   • allocate_explanation — 人が読める形式の概要です。報告では原文のまま引用します。
   • node_allocation_decisions[].deciders[] — ノードごとの判定要因の結果です。decision: "NO" の判定要因を探します。判定要因の名前（例：disk_threshold、filter、awareness）が根本原因の分類です。 判断：
   • Yellow + primary: false — 影響はレプリカの冗長性に限られ、データ損失はありません。手順 4 に進み、ブロックしている判定要因を特定してください（NODE_LEFT で止めないでください）。
   • Red + primary: true — そのシャードのデータが失われています。手順 4 に進み、can_allocate が no_valid_shard_copy の場合は、直ちにデータ損失の可能性があるものとして扱ってください。

   必要なデータ：選択したインデックスで、代表的な未割り当てシャード 1 つの割り当て説明レスポンス。

4. 判定要因を分類します。 ブロックしているシグナルを原因クラスに対応付けます。unassigned_info.reason のトリガーよりも、decision: "NO" の判定要因を優先してください。

   シグナル	原因クラス	一般的な対処方法（オペレーターが実施）
   decider: disk_threshold、decision: NO	ディスクの高／低ウォーターマーク超過	該当ノードのディスク領域を解放する、データノードの容量を追加する、または GET /_cat/allocation で使用状況を確認してから cluster.routing.allocation.disk.watermark.* を調整する
   decider: filter または decider: awareness、decision: NO	割り当てフィルタリングまたはゾーン認識	index.routing.allocation.*／認識属性を満たすノードを追加する、またはインデックス／クラスターの割り当て設定を調整する
   decider: throttling またはリカバリー進行中	一時的なリカバリー	待機し、GET /_cat/recovery を監視して GET /_cluster/health を再確認する
   can_allocate: no_valid_shard_copy（多くの場合、node_allocation_decisions が空）	存続しているシャードコピーがない	手順 5 を参照 — データ損失のシナリオ
   can_allocate: yes だがシャードが未割り当てのまま	割り当ての遅延またはクラスター状態の追いつき待ち	unassigned_info.at の遅延を確認し、待機して再確認する

   ディスク圧迫（NODE_LEFT 後によくある yellow シナリオ）の場合：レプリカは残りのノードに再配置されます。残存ノードが高ウォーターマーク（cluster.routing.allocation.disk.watermark.high、デフォルトは 90%）を超えていると、プライマリは割り当てられたままでも、disk_threshold 判定要因によってレプリカの割り当てがブロックされます。解決策はディスク容量の確保またはウォーターマークの緩和であり、インデックスを削除したり、空のプライマリを強制的に作成したりすることではありません。

   必要なデータ：判定要因名、explanation テキスト、node_allocation_decisions に記載された影響対象ノード名。

5. 対処方法を推奨します — 読み取り専用のトリアージはここで終了です。 最も可能性の高い単一の原因（判定要因クラスと、変更を加えずそのまま引用した allocate_explanation）と、主な対処方法を 1 つ報告します。緊急度は色とシャードの役割に合わせてください。 Yellow／レプリカ未割り当て（データ損失なし）：

   • すべてのプライマリは割り当て済みで、未割り当てなのはレプリカのみであり、データ損失はないことを明確に伝えます。
   • 単に「ノードが離脱した」とするのではなく、実際の原因（例：es-node-2 のディスク使用率が高いウォーターマークに達したこと）を示します。
   • GET /_cat/allocation を確認したうえで、ディスク領域の解放、ストレージの拡張、データノードの追加、またはディスクのウォーターマークの調整を推奨します。
   • インデックスの削除、allocate_empty_primary、正常なプライマリを上書きする強制割り当て、または根拠のないクラスタ全体の再起動は推奨しないでください。

   Red／no_valid_shard_copy によるプライマリ未割り当て（データ損失のリスクあり）：

   • プライマリシャードが未割り当てであり、そのシャードへのクエリやルーティングが失敗すること、また、指名されたインデックスに限定された緊急の問題として扱うことを明確に伝えます。
   • 唯一のコピーは離脱したノード上にあり、残りのノードに有効なコピーがないため、Elasticsearch はプライマリを割り当てられないこと（can_allocate: no_valid_shard_copy）を説明します。
   • 次の順に復旧方法を示します。
     1. データディレクトリが無事であれば、離脱したノードを再起動します。シャードのコピーが戻ります。
     2. スナップショットがある場合は、インデックスに復元する（または新しいインデックスに復元してから再インデックスする）方法を示します。
     3. 最後の手段に限る： POST /_cluster/reroute の allocate_empty_primary を使用します。**空のプライマリが作成され、そのシャード内のすべてのドキュメントが恒久的に失われます。**データ損失を明示し、最初の対処法や安易な修正策として提示しないでください。
   • データ損失について説明せずにインデックスの削除を推奨したり、データ損失への警告なしに allocate_empty_primary を推奨したりしないでください。

   自己修復中：

   • 判定結果でスロットリングまたはアクティブなピアリカバリーが示されている場合は、待機して上記の読み取り専用 API を再確認するよう推奨します。

   リルート、スナップショットの復元、設定変更は実行せず、原因と対処方法のみを示してください。

ガイドライン

• **読み取り専用：**トリアージには GET／POST の explain API のみを使用してください。対処方法は助言にとどめ、書き込み操作はオペレーターが実施します。
• きっかけ ≠ 原因：unassigned_info.reason: NODE_LEFT はイベントの説明です。割り当てが引き続き失敗する理由は、node_allocation_decisions の判定結果が示します。
• **レプリカとプライマリ：**Yellow かつ primary: false は冗長性の不足であり、データ損失ではありません。Red かつ primary: true は、そのシャードのデータが失われていることを意味します。
• **1 つのインデックス、1 つの原因：**影響が最も大きいインデックスと、最も強い NO 判定の原因を選び、すべてのシャードを列挙するのは避けてください。
• **Cat の補助 API：**原因となる判定クラスが不明な場合やリカバリー中の場合は、ノードごとのディスク使用率に GET /_cat/allocation を、進行中のリカバリーに GET /_cat/recovery を使用してください。

例

**Yellow — ノード離脱後のディスクウォーターマーク。**ヘルス情報では logs-2025-07 のレプリカが未割り当てで、状態は Yellow です。割り当ての explain API は primary: false、unassigned_info.reason: NODE_LEFT を返しますが、es-node-2 の disk_threshold 判定は NO です（「高いウォーターマークを超過しています……90%」）。報告内容：データ損失はありません。根本原因は割り当て先ノードのディスク逼迫です。「ノード離脱」だけを理由とせず、ディスクまたはウォーターマークへの対処を提案してください。

**Red — 有効なコピーがないプライマリ。**ヘルス情報では orders-2025 が Red で、未割り当てのシャードが 1 つあります。explain API は primary: true、can_allocate: no_valid_shard_copy、last_allocation_status: no_valid_shard_copy を返します。報告内容：緊急の問題です。プライマリデータが失われています。ノードまたはスナップショットからの復元を提案してください。allocate_empty_primary に言及する場合は、明示的にデータ損失を警告し、最後の手段としてのみ示してください。

Operations

HTTP API (shorthand)	elastic CLI command
GET /_cluster/health	elastic es cluster health
GET /_cluster/health?level=indices	elastic es cluster health --level indices
POST /_cluster/allocation/explain	elastic es cluster allocation-explain
POST /_cluster/allocation/explain (specific shard)	elastic es cluster allocation-explain --index '<index>' --shard <id> --primary true (replica: false)
GET /_cat/allocation	elastic es cat allocation
GET /_cat/recovery	elastic es cat recovery
GET /_cat/shards/{index}?h=index,shard,prirep,state,unassigned.reason	elastic es cat shards --index '<index>' --h index,shard,prirep,state,unassigned.reason
POST /_cluster/reroute (last-resort empty primary — operator only)	elastic es cluster reroute --commands '<json>'