DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ DevOpsツールとベストプラクティスの習得 - DevOpsナレッジハブ

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

黄色または赤色のElasticsearchクラスターに直面していますか？未割り当てシャード、ディスク圧力、ノード喪失、安全な復旧オプションを診断します。

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

黄色または赤色のElasticsearchクラスターは謎の状態ではありません。通常、Elasticsearchが1つ以上のシャードを配置したい場所に配置できないことを意味します。作業は、どのシャードがスタックしているか、なぜ割り当てがブロックされているか、適切な修正が待つこと、リソースを解放すること、ノードを復帰させること、スナップショットから復元すること、または意図的にデータ損失を受け入れることであるかを特定することです。

私はクラスターヘルスをトリアージ信号として扱い、診断そのものとしては扱いません。グリーンはすべてのプライマリシャードとレプリカシャードが割り当てられていることを意味します。イエローはすべてのプライマリシャードが割り当てられているため、検索と書き込みは通常継続できますが、少なくとも1つのレプリカが欠落しています。レッドは少なくとも1つのプライマリシャードが未割り当てであるため、少なくとも1つのインデックスの一部が利用不可です。レッドはアプリケーションの読み取りまたは書き込みを即座に壊す可能性があるものです。

まずはシンプルなビューを取得します：

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シャードはプライマリです。レッドクラスターには常に少なくとも1つの未割り当てプライマリがあります。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の1ノード開発クラスターです。Elasticsearchはレプリカをプライマリと同じノードに配置できないため、レプリカは永久に未割り当てのままです。ラップトップ環境では緊急事態ではありません。設定の不一致です。

レプリカ数を確認します：

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

シングルノードの非本番クラスターの場合、レプリカをゼロに設定します：

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

本番環境では、意図的に冗長性を減らすことを受け入れない限り、レプリカを減らして問題を隠さないでください。インデックスに1つのレプリカがあるべき場合、少なくとも2つの適格なデータノードが必要です。2つのレプリカがある場合、少なくとも3つの適格なデータノードが必要です。階層化によりこれがわかりにくくなることがあります：ウォームインデックスのレプリカは、割り当てルールがウォームノードを必要とする場合、ホット専用ノードに割り当てられません。

ディスク圧力は次に一般的なイエローの原因です。ノードのディスク使用量を確認します：

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は一般的に、ヒープがファイルシステムキャッシュに十分なメモリを残すときに最適に動作します。過大な集計、大量のフィールドデータ使用、シャードが多すぎる、積極的なインデックス作成、またはより良いマッピングを必要とするクエリを探します。

シャード数は多くのヘルス問題の静かな原因である可能性があります。多数の小さなシャードを持つクラスターは、メタデータの追跡とシャードの移動に多くの労力を費やします。以下を使用します：

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保持が間違っていたり、シャード数が多すぎたり、ノードが小さすぎたり、デプロイメントプロセスがノード属性を変更し続けたりすると、同じインシデントが戻ってきます。

クラスターヘルスのトラブルシューティングは、1つの魔法のコマンドを暗記することよりも、推測を拒否することにあります。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が回復に必要とするシャードコピーが削除される可能性があります。再起動が必要な場合は、一度に1ノードずつ行い、各ステップの間にクラスターが安定するのを待ちます。

割り当てを無効にして忘れないでください。メンテナンス中の一時的な割り当て変更は一般的ですが、忘れられた設定はメンテナンスウィンドウが終了した後も長くレプリカを未割り当てのままにすることがあります。常に永続設定と一時設定の両方を確認します：

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

サイズのみに基づいてインデックスを削除しないでください。大きなインデックスはビジネスクリティカルである可能性があります。小さなインデックスは削除しても安全かもしれません。クリーンアップを保持ポリシー、スナップショット、アプリケーション所有権に結び付けます。実際の障害では、最も速い安全なクリーンアップは通常、既知の期限切れのログまたはメトリクスインデックスを削除することであり、ソートされたサイズリストから推測することではありません。

KibanaとElasticsearchが問題に対して同じ言語を使用していると仮定しないでください。Kibanaは広範なレッドステータスを表示する一方、Elasticsearch APIは正確な未割り当てシャードを示すことがあります。可視性にはUIを使用しますが、決定にはAPIを使用します。