Cluster Reroute

The reroute command allows to explicitly execute a cluster reroute allocation command including specific commands. For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, or an unassigned shard can be explicitly allocated on a specific node.

Here is a short example of how a simple reroute API call:

curl -XPOST 'localhost:9200/_cluster/reroute' -d '{
    "commands" : [ {
        "move" :
            {
              "index" : "test", "shard" : 0,
              "from_node" : "node1", "to_node" : "node2"
            }
        },
        {
          "allocate_replica" : {
              "index" : "test", "shard" : 1, "node" : "node3"
          }
        }
    ]
}'

An important aspect to remember is the fact that once when an allocation occurs, the cluster will aim at re-balancing its state back to an even state. For example, if the allocation includes moving a shard from node1 to node2, in an even state, then another shard will be moved from node2 to node1 to even things out.

The cluster can be set to disable allocations, which means that only the explicitly allocations will be performed. Obviously, only once all commands has been applied, the cluster will aim to be re-balance its state.

Another option is to run the commands in dry_run (as a URI flag, or in the request body). This will cause the commands to apply to the current cluster state, and return the resulting cluster after the commands (and re-balancing) has been applied.

If the explain parameter is specified, a detailed explanation of why the commands could or could not be executed is returned.

The commands supported are:

Two more commands are available that allow the allocation of a primary shard to a node. These commands should however be used with extreme care, as primary shard allocation is usually fully automatically handled by Elasticsearch. Reasons why a primary shard cannot be automatically allocated include the following:

As a manual override, two commands to forcefully allocate primary shards are available:

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.

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