クラスターAPI - クラスターの再ルーティング（Cluster reroute）

クラスタ再ルーティングAPI
リクエスト
前提条件
説明
クエリパラメータ
リクエストボディ
例

クラスタ再ルーティングAPI

クラスタ内のシャードの割り当てを変更します。

リクエスト

POST /_cluster/reroute?metric=none

前提条件

Elasticsearchのセキュリティ機能が有効になっている場合、このAPIを使用するにはmanage クラスタ特権を持っている必要があります。

説明

再ルーティングコマンドは、クラスタ内の個々のシャードの割り当てを手動で変更することを可能にします。たとえば、シャードを明示的に1つのノードから別のノードに移動したり、割り当てをキャンセルしたり、未割り当てのシャードを特定のノードに明示的に割り当てたりできます。

再ルーティングコマンドを処理した後、Elasticsearchは通常通り再バランスを行い（cluster.routing.rebalance.enableなどの設定値を尊重し）、バランスの取れた状態を維持します。たとえば、要求された割り当てにnode1からnode2へのシャードの移動が含まれている場合、node2からnode1へのシャードの移動が発生し、バランスを取ることがあります。

クラスタは、cluster.routing.allocation.enable設定を使用して割り当てを無効にすることができます。割り当てが無効になっている場合、実行されるのはrerouteコマンドを使用して与えられた明示的な割り当てのみであり、再バランスによる結果の割り当ては行われません。

rerouteコマンドを「ドライラン」モードで実行することが可能で、?dry_run URIクエリパラメータを使用するか、リクエストボディに"dry_run": trueを渡すことで実現できます。これにより、コマンドを現在のクラスタ状態に適用した結果を計算し、コマンド（および再バランス）が適用された後の結果のクラスタ状態を返しますが、実際には要求された変更は行われません。

?explain URIクエリパラメータが含まれている場合、コマンドが実行できた理由またはできなかった理由の詳細な説明がレスポンスに含まれます。

クラスタは、シャードを最大index.allocation.max_retries回連続して割り当てようとします（デフォルトは5）、それでも割り当てに失敗した場合は、シャードを未割り当てのままにします。このシナリオは、すべてのノードに存在しないストップワードファイルを参照するアナライザーを持つなどの構造的な問題によって引き起こされる可能性があります。

問題が修正された後、reroute APIを?retry_failed URIクエリパラメータを使用して呼び出すことで、割り当てを手動で再試行できます。これにより、これらのシャードのための単一の再試行ラウンドが試みられます。

クエリパラメータ

dry_run
（オプション、ブール値）trueの場合、リクエストは操作をシミュレートするだけで、結果の状態を返します。
explain
（オプション、ブール値）trueの場合、レスポンスにはコマンドが実行できる理由またはできない理由の説明が含まれます。
metric
（オプション、文字列）返される情報を指定されたメトリクスに制限します。noneを除くすべてのオプションは非推奨であり、このパラメータには避けるべきです。デフォルトはメタデータを除くすべてです。以下のオプションが利用可能です：
```
-   `````_all
```
- すべてのメトリクスを表示します。
- blocks
- レスポンスのblocks部分を表示します。
- master_node
- レスポンスの選択されたmaster_node部分を表示します。
- metadata
- レスポンスのmetadata部分を表示します。インデックスのカンマ区切りリストを提供すると、返される出力にはこれらのインデックスのメタデータのみが含まれます。
- nodes
- レスポンスのnodes部分を表示します。
- none
- レスポンスからstateフィールド全体を除外します。
- routing_table
- レスポンスのrouting_table部分を表示します。
- version
- クラスタ状態のバージョンを表示します。
retry_failed
（オプション、ブール値）trueの場合、次の割り当て失敗が多すぎてブロックされているシャードの割り当てを再試行します。
master_timeout
（オプション、時間単位）マスターノードを待つ期間。タイムアウトが切れる前にマスターノードが利用できない場合、リクエストは失敗し、エラーを返します。デフォルトは30sです。リクエストがタイムアウトしないことを示すために-1に設定することもできます。
timeout
（オプション、時間単位）クラスタメタデータを更新した後、関連するすべてのノードからの応答を待つ期間。タイムアウトが切れる前に応答が受信されない場合、クラスタメタデータの更新は適用されますが、応答は完全に承認されなかったことを示します。デフォルトは30sです。リクエストがタイムアウトしないことを示すために-1に設定することもできます。

リクエストボディ

commands
（必須、オブジェクトの配列）実行するコマンドを定義します。サポートされているコマンドは次のとおりです：
```
-   `````move
```
- 開始されたシャードを1つのノードから別のノードに移動します。インデックス名とシャード番号にはindexとshardを、シャードを移動するノードにはfrom_nodeを、シャードを移動するノードにはto_nodeを受け入れます。
- cancel
- シャード（またはリカバリ）の割り当てをキャンセルします。インデックス名とシャード番号にはindexとshardを、シャードの割り当てをキャンセルするノードにはnodeを受け入れます。これにより、既存のレプリカをプライマリシャードから強制的に再同期させるために、キャンセルして標準のリカバリプロセスを通じて再初期化できるようになります。デフォルトでは、レプリカシャードの割り当てのみがキャンセルできます。プライマリシャードの割り当てをキャンセルする必要がある場合は、allow_primaryフラグもリクエストに含める必要があります。
- allocate_replica
- 未割り当てのレプリカシャードをノードに割り当てます。インデックス名とシャード番号にはindexとshardを、シャードを割り当てるノードにはnodeを受け入れます。割り当て決定者を考慮します。
  プライマリシャードをノードに割り当てることを許可する2つのコマンドもあります。ただし、プライマリシャードの割り当ては通常Elasticsearchによって完全に自動的に処理されるため、これらのコマンドは極めて注意して使用する必要があります。プライマリシャードが自動的に割り当てられない理由には、次のようなものがあります：
- 新しいインデックスが作成されましたが、割り当て決定者を満たすノードがありません。
- 現在のデータノードにデータの最新のシャードコピーが見つかりません。データ損失を防ぐために、システムは古いシャードコピーをプライマリに昇格させません。
  次の2つのコマンドは危険であり、データ損失を引き起こす可能性があります。これらは、元のデータを回復できない場合に使用されることを意図しています。クラスタ管理者が損失を受け入れる場合です。修正可能な一時的な問題が発生した場合は、上記のretry_failedフラグを参照してください。強調するために：これらのコマンドが実行され、その後影響を受けたシャードのコピーを持つノードがクラスタに参加すると、新しく参加したノードのコピーは削除または上書きされます。
- allocate_stale_primary
- 古いコピーを保持するノードにプライマリシャードを割り当てます。インデックス名とシャード番号にはindexとshardを、シャードを割り当てるノードにはnodeを受け入れます。このコマンドを使用すると、提供されたシャードIDのデータ損失が発生する可能性があります。データの良好なコピーを持つノードが後でクラスタに再参加すると、そのデータは削除されるか、強制的に割り当てられた古いコピーのデータで上書きされます。これらの影響が十分に理解されていることを確認するために、このコマンドはフラグaccept_data_lossをtrueに明示的に設定する必要があります。
- allocate_empty_primary
- 空のプライマリシャードをノードに割り当てます。インデックス名とシャード番号にはindexとshardを、シャードを割り当てるノードにはnodeを受け入れます。このコマンドを使用すると、以前に開始された場合、このシャードにインデックスされたすべてのデータが完全に失われます。データのコピーを持つノードが後でクラスタに再参加すると、そのデータは削除されます。これらの影響が十分に理解されていることを確認するために、このコマンドはフラグaccept_data_lossをtrueに明示的に設定する必要があります。

例

これは、シンプルな再ルーティングAPI呼び出しの短い例です：

Python

resp = client.cluster.reroute(
   metric="none",
   commands=[
   {
   "move": {
   "index": "test",
   "shard": 0,
   "from_node": "node1",
   "to_node": "node2"
   }
   },
   {
   "allocate_replica": {
   "index": "test",
   "shard": 1,
   "node": "node3"
   }
   }
   ],
)
print(resp)

Js

const response = await client.cluster.reroute({
  metric: "none",
  commands: [
   {
   move: {
   index: "test",
   shard: 0,
   from_node: "node1",
   to_node: "node2",
   },
   },
   {
   allocate_replica: {
   index: "test",
   shard: 1,
   node: "node3",
   },
   },
  ],
});
console.log(response);

コンソール

POST /_cluster/reroute?metric=none
{
  "commands": [
   {
   "move": {
   "index": "test", "shard": 0,
   "from_node": "node1", "to_node": "node2"
   }
   },
   {
   "allocate_replica": {
   "index": "test", "shard": 1,
   "node": "node3"
   }
   }
  ]
}