Elasticsearch クラスターヘルスのトラブルシューティング：ステップバイステップガイド

Elasticsearchクラスターのヘルスチェック：ステップバイステップガイド

Elasticsearchは堅牢な分散システムですが、他の分散アーキテクチャと同様に、最適なヘルスを維持するにはアクティブな監視と時折の介入が必要です。クラスターのヘルスステータスは、デプロイメントの運用準備状況とデータの安全性を判断するための最も重要な指標です。クラスターがGreenからYellow、あるいはクリティカルなRedに移行すると、データの整合性や可用性が脅かされます。

この包括的なガイドでは、特にYellowおよびRedステータスからの復旧に焦点を当て、一般的なElasticsearchクラスターのヘルス問題の診断と解決のための専門的なステップを提供します。実用的なCat APIとステップバイステップのチェックを使用して、根本原因を迅速に特定し、是正措置を実装します。

1. Elasticsearchクラスターのヘルスステータスを理解する

トラブルシューティングの前に、各クラスターのヘルスカラーが何を意味するかを理解することが不可欠です。ヘルスステータスは、クラスターノード全体でのプライマリシャードとレプリカシャードの割り当て状態によって決定されます。

ステータス	意味	影響
Green	すべてのプライマリシャードとレプリカシャードが正常に割り当てられています。	クラスターは完全に運用可能で、耐障害性があります。
Yellow	すべてのプライマリシャードは割り当てられていますが、1つ以上のレプリカシャードが割り当てられていません。	データは利用可能ですが、クラスターはノード障害に対する完全な耐障害性を欠いています。
Red	少なくとも1つのプライマリシャードが割り当てられていません（したがって、利用できません）。	失敗したシャードを含むインデックスのデータ損失またはアクセス不可。クリティカルなアクションが必要です。

2. 初期診断：クラスターのヘルスチェック

あらゆるトラブルシューティングプロセスの最初のステップは、現在のステータスを確認し、クラスターヘルスAPIとノードAPIを使用して基本的なメトリクスを収集することです。

ステップ2.1：クラスターのヘルスチェック

_cat/health APIを使用して、概要を把握します。?vパラメータは、ノード数や総シャード数を含む詳細な出力を提供します。

GET /_cat/health?v

出力例（Yellowステータス）：

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

ステータスがYellowまたはRedの場合、unassignの値に注意してください。

ステップ2.2：ノードステータスとメモリのチェック

期待されるすべてのノードが接続され、正しく動作していることを確認します。また、ヒープ使用率（パフォーマンスと安定性に不可欠）をチェックします。

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

このリストにノードが見つからない場合は、接続の問題またはサービス停止の可能性があります。

3. Redクラスター状態の解決（プライマリシャード障害）

Redステータスは、データが即座にアクセスできないことを意味します。目標は、プライマリシャードをできるだけ早くオンラインに戻すことです。

ステップ3.1：割り当てられていないプライマリシャードの特定

_cat/shards APIを使用して、問題の原因となっている正確なインデックスとシャードを特定します。特にUNASSIGNEDとマークされ、p（プライマリ）ロールを持つエントリを探します。

GET /_cat/shards?v | grep UNASSIGNED

出力例：

index_logs 0 p UNASSIGNED

ステップ3.2：割り当ての説明の確認

これは最も重要な診断ステップです。Allocation Explain APIは、特定のシャード（または割り当てられていないシャード）がなぜ割り当てられないのかを説明します。

GET /_cluster/allocation/explain

Redステータスの一般的な原因：

ノード障害： プライマリシャードを保持していたノードがクラッシュしたか、クラスターから削除されました。失敗したノードが他のノードに十分なレプリカを持っている場合、プライマリシャードは自動的にレプリカを昇格させるはずです。もしすべてのコピー（プライマリとレプリカ）が失敗したノードにあった場合、ノードが復旧しない限りシャードは失われます。
データ破損： ディスク上のプライマリシャードファイルが破損し、ノードがそれらを初期化できなくなりました。

ステップ3.3：Redステータスのアクションプラン

シナリオA：ノードオフライン（推奨）
- プライマリシャードを保持していたノードが単にオフラインの場合、ノードサービスを復元します（例：Elasticsearchを再起動するか、ネットワーク問題を修正します）。ノードがクラスターに再参加すると、プライマリシャードは復旧するはずです。
シナリオB：プライマリシャードの損失（最終手段）
- ノードが恒久的に失われ、レプリカが存在しない場合、データは失われます。allocate_empty_primaryコマンドを使用して、手動でリカバリをスキップする必要があります。警告：これにより、ブランドニューで空のプライマリシャードが作成され、インデックスのそのセグメントの永続的なデータ損失が発生します。

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

ベストプラクティス： allocate_empty_primaryに頼る前に、インデックスのスナップショットまたはバックアップが存在しないことを常に確認してください。

4. Yellowクラスター状態の解決（レプリカシャード障害）

Yellowステータスは、クラスターが運用可能であるが脆弱であることを意味します。主な目的は、不足しているレプリカを割り当てることです。

ステップ4.1：割り当て説明の使用

ステータスがYellowの場合、_cluster/allocation/explain API（セクション3.2）を使用して、レプリカが割り当てられない理由を理解します。レプリカの説明は通常、より直接的です。

Yellowステータスの一般的な原因：

原因コード	説明	修正
`NO_AVAILABLE_NODES`	クラスターサイズが小さすぎる（例：レプリカ数は2だが、ノードは2つしかない）。	データノードを追加するか、`number_of_replicas`を減らしてください。
`NOT_ENOUGH_DISK_SPACE`	ノードが低または高ウォーターマークしきい値に達した。	古いインデックスを削除し、ディスクスペースを解放するか、ディスクウォーターマークを調整してください。
`ALLOCATION_DISABLED`	シャード割り当てがクラスター設定によって明示的に無効にされた。	`PUT /_cluster/settings`を使用してルーティングを再有効化してください。
`PRIMARY_NOT_ACTIVE`	プライマリシャードがまだ初期化中またはリカバリ中である。	プライマリがアクティブ（Green）になるまで待ってください。

ステップ4.2：ノード要件と制約のチェック

クラスターがレプリカ割り当ての基本要件を満たしていることを確認します。

ノード数： N個のレプリカの場合、プライマリとレプリカが同じノードに配置されないようにするには、少なくともN+1個のデータノードが必要です。
ディスクウォーターマーク： ディスク使用率がハイウォーターマーク（デフォルト90%）を超えると、Elasticsearchはノードへのシャード割り当てを停止します。

# ディスク割り当て設定のチェック
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# 例：ハイウォーターマークを95%に設定（一時的！）
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

ステップ4.3：手動再ルーティング（割り当てロジックが失敗した場合）

まれに、十分なリソースがあるにもかかわらず標準の割り当てプロセスが停止しているように見える場合、allocate_replicaコマンドを使用して、特定の正常なノードにレプリカの手動割り当てを強制できます。

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. 高度なトラブルシューティングと一般的な落とし穴

RedまたはYellowステータスが続く場合、根本原因は標準のシャード割り当てロジック外にある可能性があります。

5.1 ネットワーク接続とスプリットブレイン

分散システムでは、パーティショニング（スプリットブレイン）が深刻な問題を引き起こす可能性があります。マスター候補ノードが通信できない場合、クラスターは安定したマスターを選出できず、割り当てられていないシャードにつながる可能性があります。

アクション： すべてのノード間、特にマスター候補ノード間のネットワーク接続を確認します。
設定チェック： discovery.seed_hostsリストが正確であり、クラスターブートストラップ中にcluster.initial_master_nodes設定が正しく使用されたことを確認します。

5.2 高いJVMメモリプレッシャー

過剰なヒープ使用率（75%以上が多い）は、頻繁で長時間のガベージコレクション（GC）一時停止につながります。これらの一時停止中に、ノードは応答しないように見え、マスターノードがそれをドロップさせ、割り当てられていないシャードにつながる可能性があります。

アクション： ヒープ使用率（_cat/nodes?h=heap.percent）を監視します。一貫して高い場合は、ノードメモリのスケールアップ、インデックス作成プロセスの最適化、またはインデックスライフサイクル管理（ILM）の実装を検討してください。

5.3 シャード割り当てフィルタリング

割り当てフィルター（タグやIDなどのノード属性を使用）の意図しない適用は、シャードが本来割り当て可能であるはずのノードに割り当てられるのを防ぐ可能性があります。

# インデックスレベルの割り当てルールのチェック
GET /[index-name]/_settings
# 以下を探す：index.routing.allocation.require.*

# インデックス割り当てルールのリセット（必要に応じて）
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

クイックリカバリのためのサマリーチェックリスト

ステータス	主要な診断ツール	主要なアクションステップ
Yellow	`GET /_cluster/allocation/explain`	1. ディスクスペースをチェックします。 2. ノード数とレプリカ数の関係を確認します。 3. 割り当てフィルタリングルールを探します。 4. プライマリリカバリを待ちます。
Red	`GET /_cat/shards?v \| grep UNASSIGNED`	1. 以前ホストしていたノードのログを確認します。 2. 失敗したノードを再起動してみてください。 3. プライマリが失われたと確認され、バックアップが存在しない場合は、`allocate_empty_primary`を使用します（データ損失のリスクあり）。

_cat APIとクリティカルな_cluster/allocation/explainエンドポイントを体系的に利用することで、クラスターのヘルス低下の原因を迅速に特定し、クラスターを安定したGreenステータスに復元するために必要な是正ステップを実装できます。