REST APIs —— Cluster APIs —— Cluster reroute API

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/cluster-reroute.html#cluster-reroute

Changes the allocation of shards in a cluster.

更改集群中分片的分配。

1、Request（请求）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/cluster-reroute.html#cluster-reroute-api-request

        POST /_cluster/reroute?metric=none
    

2、Prerequisites（先决条件）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/cluster-reroute.html#cluster-reroute-api-prereqs

If the Elasticsearch security features are enabled, you must have the manage cluster privilege to use this API.

如果启用了 Elasticsearch 安全特性，则必须拥有管理集群特权才能使用此 API。

3、Description（描述）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/cluster-reroute.html#cluster-reroute-api-desc

The reroute command allows for manual changes to the allocation of individual shards in the cluster. For example, a shard can be moved from one node to another explicitly, an allocation can be cancelled, and an unassigned shard can be explicitly allocated to a specific node.

reroute 命令允许手动更改群集中单个分片的分配。例如，可以显式地将一个分片从一个节点移动到另一个节点，可以取消分配，也可以将未分配的分片显式分配给特定的节点。

It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as cluster.routing.rebalance.enable) in order to remain in a balanced state. For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.

需要注意的是，在处理任何 reroute 命令后，Elasticsearch 将像平衡状态一样执行再平衡（尊重 cluster.routing.rebalance.enable 等设置的值）。例如，如果所请求的分配包括将分片从 node1 移动到 node2，则这可能导致从 node2 移动一个分片回到 node1 以平衡状态。

The cluster can be set to disable allocations using the cluster.routing.allocation.enable setting. If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.

集群可以设置为禁用分配，使用 cluster.routing.allocation.enable 设置。如果禁用分配，则执行的唯一分配是使用 reroute 命令给出的显式分配以及由于再平衡而导致的分配。

It is possible to run reroute commands in "dry run" mode by using the ?dry_run URI query parameter, or by passing "dry_run": true in the request body. This will calculate the result of applying the commands to the current cluster state, and return the resulting cluster state after the commands (and re-balancing) has been applied, but will not actually perform the requested changes.

可以通过使用 ?dry_run URI 查询参数或在请求体中传递 "dry_run": true 来以“dry_run”模式运行 reroute 命令。这将在应用命令（和再平衡）之后计算将命令应用于当前集群状态的结果，并返回结果集群状态，但实际上不会执行请求的更改。

If the ?explain URI query parameter is included then a detailed explanation of why the commands could or could not be executed is included in the response.

如果包括 ?explain URI 查询参数，则响应中包括关于为什么可以或无法执行命令的详细说明。

The cluster will attempt to allocate a shard a maximum of index.allocation.max_retries times in a row (defaults to 5), before giving up and leaving the shard unallocated. This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.

集群将尝试将分片分配最多 index.allocation.max_retries 次（默认为 5）连续次数，然后放弃并使分片未分配。这种情况可以由结构性问题引起，例如具有引用不存在于所有节点上的停用词文件的分析器。

Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.

一旦问题得到纠正，就可以通过在 reroute API 中调用 ?retry_failed URI 查询参数来手动重试分配这些分片，它将为这些分片尝试一个重试轮。

1、Examples（例子）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/cluster-reroute.html#cluster-reroute-api-example

This is a short example of a simple reroute API call:

这是一个简单的重路由 API 调用的简短示例:

        curl -X POST "localhost:9200/_cluster/reroute?metric=none&pretty" -H 'Content-Type: application/json' -d'
        {
          "commands": [
            {
              "move": {
                "index": "test", "shard": 0,
                "from_node": "node1", "to_node": "node2"
              }
            },
            {
              "allocate_replica": {
                "index": "test", "shard": 1,
                "node": "node3"
              }
            }
          ]
        }'