From 6d267ec77a455accb62c2c427a380a3385208db0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Thu, 8 Aug 2019 14:11:06 +0200 Subject: [PATCH] [DOCS] Reformats cluster reroute API. --- docs/reference/cluster/reroute.asciidoc | 174 ++++++++++++++++-------- 1 file changed, 119 insertions(+), 55 deletions(-) diff --git a/docs/reference/cluster/reroute.asciidoc b/docs/reference/cluster/reroute.asciidoc index 7ff608834075f..62a2afbe94266 100644 --- a/docs/reference/cluster/reroute.asciidoc +++ b/docs/reference/cluster/reroute.asciidoc @@ -1,45 +1,32 @@ [[cluster-reroute]] === Cluster Reroute +Changes the allocation of shards in a cluster. + + +[[cluster-reroute-api-request]] +==== {api-request-title} + +`POST /_cluster/reroute` + + +[[cluster-reroute-api-desc]] +==== {api-description-title} + 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. -Here is a short example of a simple reroute API call: - -[source,js] --------------------------------------------------- -POST /_cluster/reroute -{ - "commands" : [ - { - "move" : { - "index" : "test", "shard" : 0, - "from_node" : "node1", "to_node" : "node2" - } - }, - { - "allocate_replica" : { - "index" : "test", "shard" : 1, - "node" : "node3" - } - } - ] -} --------------------------------------------------- -// CONSOLE -// TEST[skip:doc tests run with only a single 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. +It is important to note that after processing any reroute commands {es} 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 +`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. @@ -53,13 +40,77 @@ changes. 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. -The commands supported are: +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. + + +[[cluster-reroute-api-query-params]] +==== {api-query-parms-title} + +`dry_run`:: + (Optional, boolean) If `true`, then the request simulates the operation only + and returns the resulting state. + +`explain`:: + (Optional, boolean) If `true`, then the response contains an explanation of + why the commands can or cannot be executed. + +`metric`:: + (Optional, string) Limits the information returned to the specified metrics. + Defaults to all but metadata The following options are available: + ++ +-- +`_all`:: + Shows all metrics. + +`blocks`:: + Shows the `blocks` part of the response. + +`master_node`:: + Shows the elected `master_node` part of the response. + +`metadata`:: + Shows the `metadata` part of the response. If you supply a comma separated + list of indices, the returned output will only contain metadata for these + indices. +`nodes`:: + Shows the `nodes` part of the response. + +`routing_table`:: + Shows the `routing_table` part of the response. + +`version`:: + Shows the cluster state version. +-- + +`retry_failed`:: + (Optional, boolean) If `true`, then retries allocation of shards that are + blocked due to too many subsequent allocation failures. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[cluster-reroute-api-request-body]] +==== {api-request-body-title} + +`commands`:: + (Required, object) Defines the commands to perform. Supported commands are: + ++ +-- `move`:: - 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. + 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. `cancel`:: Cancel allocation of a shard (or recovery). Accepts `index` and `shard` for @@ -75,27 +126,12 @@ The commands supported are: 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 <> into account. - -[float] -==== Retrying failed allocations - -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 <> API with the `?retry_failed` URI -query parameter, which will attempt a single retry round for these shards. - -[float] -==== Forced allocation on unrecoverable errors +-- 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 +shard allocation is usually fully automatically handled by {es}. Reasons why a +primary shard cannot be automatically allocated include the following: - A new index was created but there is no node which satisfies the allocation @@ -131,3 +167,31 @@ will be deleted or overwritten. that these implications are well-understood, this command requires the flag `accept_data_loss` to be explicitly set to `true`. + +[[cluster-reroute-api-example]] +==== {api-examples-title} + +This is a short example of a simple reroute API call: + +[source,js] +-------------------------------------------------- +POST /_cluster/reroute +{ + "commands" : [ + { + "move" : { + "index" : "test", "shard" : 0, + "from_node" : "node1", "to_node" : "node2" + } + }, + { + "allocate_replica" : { + "index" : "test", "shard" : 1, + "node" : "node3" + } + } + ] +} +-------------------------------------------------- +// CONSOLE +// TEST[skip:doc tests run with only a single node]