Reroute the cluster

POST /_cluster/reroute

Manually change 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 canceled, and an unassigned shard can be explicitly allocated to a specific node.

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.

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.

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 the ?retry_failed URI query parameter, which will attempt a single retry round for these shards.

Query Parameters

Request

commands [] Command: Defines the commands to perform.

Response

application/json

Examples

Run POST /_cluster/reroute?metric=none to changes the allocation of shards in a cluster.

Request Console 1 / 7 languages

Console Kibana Dev Tools

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"
      }
    }
  ]
}

JavaScript Elasticsearch JavaScript Client

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",
      },
    },
  ],
});

Python Elasticsearch Python Client

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"
            }
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_cluster/reroute?metric=none" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -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"
        }
      }
    ]
  }'

Java Elasticsearch Java Client

client.cluster().reroute(r -> r
    .commands(List.of(Command.of(c -> c
            .move(m -> m
                .index("test")
                .shard(0)
                .fromNode("node1")
                .toNode("node2")
            )
        ),Command.of(c -> c
            .allocateReplica(a -> a
                .index("test")
                .shard(1)
                .node("node3")
            )
        )))
    .metric("none")
);

PHP Elasticsearch PHP Client

$resp = $client->cluster()->reroute([
    "metric" => "none",
    "body" => [
        "commands" => array(
            [
                "move" => [
                    "index" => "test",
                    "shard" => 0,
                    "from_node" => "node1",
                    "to_node" => "node2",
                ],
            ],
            [
                "allocate_replica" => [
                    "index" => "test",
                    "shard" => 1,
                    "node" => "node3",
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

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

Response

No example

Query Parameters { dry_run , explain , metric , retry_failed , master_timeout , timeout , }

Request

Response

Query Parameters