--- type: api title: Reroute the cluster description: Manually change the allocation of individual shards in the cluster. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-cluster-reroute resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-cluster-reroute products: - Elasticsearch --- # Reroute the cluster Availability: 5.0+ ## Paths - `POST` `/_cluster/reroute` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) ## Description 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 String Parameters - `dry_run` (boolean · default: false) If true, then the request simulates the operation. It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes. - `explain` (boolean · default: false) If true, then the response contains an explanation of why the commands can or cannot run. - `metric` (Metrics · default: all) Limits the information returned to the specified metrics. - `retry_failed` (boolean · default: false) If true, then retries allocation of shards that are blocked due to too many subsequent allocation failures. - `master_timeout` (string Duration · default: 30s) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. - `timeout` (string Duration · default: 30s) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. ## Request Body `application/json` - `commands` ([] Command) — optional Defines the commands to perform. - `cancel` ({} CommandCancelAction) — optional Cancel allocation of a shard (or recovery). Accepts index and shard for index name and shard number, and node for the node to cancel the shard allocation on. This can be used to force resynchronization of existing replicas from the primary shard by cancelling them and allowing them to be reinitialized through the standard recovery process. By default only replica shard allocations can be cancelled. If it is necessary to cancel the allocation of a primary shard then the allow_primary flag must also be included in the request. - `index` (string IndexName) — required - `shard` (number) — required - `node` (string) — required - `allow_primary` (boolean) — optional - `move` ({} CommandMoveAction) — optional Move a started shard from one node to another node. Accepts index and shard for index name and shard number, from_node for the node to move the shard from, and to_node for the node to move the shard to. - `index` (string IndexName) — required - `shard` (number) — required - `from_node` (string) — required The node to move the shard from - `to_node` (string) — required The node to move the shard to - `allocate_replica` ({} CommandAllocateReplicaAction) — optional Allocate an unassigned replica shard to a node. Accepts index and shard for index name and shard number, and node to allocate the shard to. Takes allocation deciders into account. - `index` (string IndexName) — required - `shard` (number) — required - `node` (string) — required - `allocate_stale_primary` ({} CommandAllocatePrimaryAction) — optional Allocate a primary shard to a node that holds a stale copy. Accepts the index and shard for index name and shard number, and node to allocate the shard to. Using this command may lead to data loss for the provided shard id. If a node which has the good copy of the data rejoins the cluster later on, that data will be deleted or overwritten with the data of the stale copy that was forcefully allocated with this command. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true. - `index` (string IndexName) — required - `shard` (number) — required - `node` (string) — required - `accept_data_loss` (boolean) — required If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true - `allocate_empty_primary` ({} CommandAllocatePrimaryAction) — optional Allocate an empty primary shard to a node. Accepts the index and shard for index name and shard number, and node to allocate the shard to. Using this command leads to a complete loss of all data that was indexed into this shard, if it was previously started. If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true. - `index` (string IndexName) — required - `shard` (number) — required - `node` (string) — required - `accept_data_loss` (boolean) — required If a node which has a copy of the data rejoins the cluster later on, that data will be deleted. To ensure that these implications are well-understood, this command requires the flag accept_data_loss to be explicitly set to true ## Response `application/json` - `acknowledged` (boolean) - `explanations` ([] RerouteExplanation) - `command` (string) - `decisions` ([] RerouteDecision) - `decider` (string) - `decision` (string) - `explanation` (string) - `parameters` ({} RerouteParameters) - `allow_primary` (boolean) - `index` (string IndexName) - `node` (string) - `shard` (number) - `from_node` (string) - `to_node` (string) - `state` (object) There aren't any guarantees on the output/structure of the raw cluster state. Here you will find the internal representation of the cluster, which can differ from the external representation. ## Code Examples #### Console ```console 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 ```javascript 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 ```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" } } ], ) ``` #### curl ```curl 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" } } ] }' ``` #### PHP ```php $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 ```ruby 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" } } ] } ) ```