From 51cb0c5c7b550695cc2a5e6f72c4a4ceea85bdec Mon Sep 17 00:00:00 2001 From: Vishal Patel <38330754+patelvp@users.noreply.github.com> Date: Thu, 9 Apr 2020 14:56:37 -0400 Subject: [PATCH] [DOCS] Collapse nested objects in cluster reroute docs (#54851) --- docs/reference/cluster/reroute.asciidoc | 55 ++++++++++++++----------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/reference/cluster/reroute.asciidoc b/docs/reference/cluster/reroute.asciidoc index 94e2367b96e..32851c0a16b 100644 --- a/docs/reference/cluster/reroute.asciidoc +++ b/docs/reference/cluster/reroute.asciidoc @@ -12,7 +12,6 @@ Changes the allocation of shards in a cluster. `POST /_cluster/reroute` - [[cluster-reroute-api-desc]] ==== {api-description-title} @@ -21,15 +20,15 @@ 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. -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 +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. @@ -55,31 +54,34 @@ query parameter, which will attempt a single retry round for these shards. [[cluster-reroute-api-query-params]] +[role="child_attributes"] ==== {api-query-parms-title} `dry_run`:: - (Optional, boolean) If `true`, then the request simulates the operation only + (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 + (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. + (Optional, string) Limits the information returned to the specified metrics. Defaults to all but metadata The following options are available: + --- +.Options for `metric` +[%collapsible%open] +====== `_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 @@ -90,29 +92,33 @@ query parameter, which will attempt a single retry round for these shards. `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 + (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] - +[role="child_attributes"] [[cluster-reroute-api-request-body]] ==== {api-request-body-title} `commands`:: - (Required, object) Defines the commands to perform. Supported commands are: + (Required, array of objects) Defines the commands to perform. Supported commands are: + --- +.Properties of `commands` +[%collapsible%open] +====== + `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 + 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`:: @@ -129,11 +135,10 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] 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. --- 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 {es}. Reasons why a +shard allocation is usually fully automatically handled by {es}. Reasons why a primary shard cannot be automatically allocated include the following: @@ -169,7 +174,7 @@ will be deleted or overwritten. 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`. - +====== [[cluster-reroute-api-example]] ==== {api-examples-title}