reroute.asciidoc 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210
  1. [[cluster-reroute]]
  2. === Cluster reroute API
  3. ++++
  4. <titleabbrev>Cluster reroute</titleabbrev>
  5. ++++
  6. Changes the allocation of shards in a cluster.
  7. [[cluster-reroute-api-request]]
  8. ==== {api-request-title}
  9. `POST /_cluster/reroute`
  10. [[cluster-reroute-api-prereqs]]
  11. ==== {api-prereq-title}
  12. * If the {es} {security-features} are enabled, you must have the `manage`
  13. <<privileges-list-cluster,cluster privilege>> to use this API.
  14. [[cluster-reroute-api-desc]]
  15. ==== {api-description-title}
  16. The reroute command allows for manual changes to the allocation of individual
  17. shards in the cluster. For example, a shard can be moved from one node to
  18. another explicitly, an allocation can be cancelled, and an unassigned shard can
  19. be explicitly allocated to a specific node.
  20. It is important to note that after processing any reroute commands {es} will
  21. perform rebalancing as normal (respecting the values of settings such as
  22. `cluster.routing.rebalance.enable`) in order to remain in a balanced state. For
  23. example, if the requested allocation includes moving a shard from `node1` to
  24. `node2` then this may cause a shard to be moved from `node2` back to `node1` to
  25. even things out.
  26. The cluster can be set to disable allocations using the
  27. `cluster.routing.allocation.enable` setting. If allocations are disabled then
  28. the only allocations that will be performed are explicit ones given using the
  29. `reroute` command, and consequent allocations due to rebalancing.
  30. It is possible to run `reroute` commands in "dry run" mode by using the
  31. `?dry_run` URI query parameter, or by passing `"dry_run": true` in the request
  32. body. This will calculate the result of applying the commands to the current
  33. cluster state, and return the resulting cluster state after the commands (and
  34. re-balancing) has been applied, but will not actually perform the requested
  35. changes.
  36. If the `?explain` URI query parameter is included then a detailed explanation
  37. of why the commands could or could not be executed is included in the response.
  38. The cluster will attempt to allocate a shard a maximum of
  39. `index.allocation.max_retries` times in a row (defaults to `5`), before giving
  40. up and leaving the shard unallocated. This scenario can be caused by
  41. structural problems such as having an analyzer which refers to a stopwords
  42. file which doesn't exist on all nodes.
  43. Once the problem has been corrected, allocation can be manually retried by
  44. calling the `reroute` API with the `?retry_failed` URI
  45. query parameter, which will attempt a single retry round for these shards.
  46. [[cluster-reroute-api-query-params]]
  47. [role="child_attributes"]
  48. ==== {api-query-parms-title}
  49. `dry_run`::
  50. (Optional, Boolean) If `true`, then the request simulates the operation only
  51. and returns the resulting state.
  52. `explain`::
  53. (Optional, Boolean) If `true`, then the response contains an explanation of
  54. why the commands can or cannot be executed.
  55. `metric`::
  56. (Optional, string) Limits the information returned to the specified metrics.
  57. Defaults to all but metadata The following options are available:
  58. +
  59. .Options for `metric`
  60. [%collapsible%open]
  61. ======
  62. `_all`::
  63. Shows all metrics.
  64. `blocks`::
  65. Shows the `blocks` part of the response.
  66. `master_node`::
  67. Shows the elected `master_node` part of the response.
  68. `metadata`::
  69. Shows the `metadata` part of the response. If you supply a comma separated
  70. list of indices, the returned output will only contain metadata for these
  71. indices.
  72. `nodes`::
  73. Shows the `nodes` part of the response.
  74. `routing_table`::
  75. Shows the `routing_table` part of the response.
  76. `version`::
  77. Shows the cluster state version.
  78. ======
  79. `retry_failed`::
  80. (Optional, Boolean) If `true`, then retries allocation of shards that are
  81. blocked due to too many subsequent allocation failures.
  82. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
  83. [role="child_attributes"]
  84. [[cluster-reroute-api-request-body]]
  85. ==== {api-request-body-title}
  86. `commands`::
  87. (Required, array of objects) Defines the commands to perform. Supported commands are:
  88. +
  89. .Properties of `commands`
  90. [%collapsible%open]
  91. ======
  92. `move`::
  93. Move a started shard from one node to another node. Accepts `index` and
  94. `shard` for index name and shard number, `from_node` for the node to move
  95. the shard from, and `to_node` for the node to move the shard to.
  96. `cancel`::
  97. Cancel allocation of a shard (or recovery). Accepts `index` and `shard` for
  98. index name and shard number, and `node` for the node to cancel the shard
  99. allocation on. This can be used to force resynchronization of existing
  100. replicas from the primary shard by cancelling them and allowing them to be
  101. reinitialized through the standard recovery process. By default only
  102. replica shard allocations can be cancelled. If it is necessary to cancel
  103. the allocation of a primary shard then the `allow_primary` flag must also
  104. be included in the request.
  105. `allocate_replica`::
  106. Allocate an unassigned replica shard to a node. Accepts `index` and `shard`
  107. for index name and shard number, and `node` to allocate the shard to. Takes
  108. <<modules-cluster,allocation deciders>> into account.
  109. Two more commands are available that allow the allocation of a primary shard to
  110. a node. These commands should however be used with extreme care, as primary
  111. shard allocation is usually fully automatically handled by {es}. Reasons why a
  112. primary shard cannot be automatically allocated include the
  113. following:
  114. - A new index was created but there is no node which satisfies the allocation
  115. deciders.
  116. - An up-to-date shard copy of the data cannot be found on the current data
  117. nodes in the cluster. To prevent data loss, the system does not automatically
  118. promote a stale shard copy to primary.
  119. The following two commands are dangerous and may result in data loss. They are
  120. meant to be used in cases where the original data can not be recovered and the
  121. cluster administrator accepts the loss. If you have suffered a temporary issue
  122. that can be fixed, please see the `retry_failed` flag described above. To
  123. emphasise: if these commands are performed and then a node joins the cluster
  124. that holds a copy of the affected shard then the copy on the newly-joined node
  125. will be deleted or overwritten.
  126. `allocate_stale_primary`::
  127. Allocate a primary shard to a node that holds a stale copy. Accepts the
  128. `index` and `shard` for index name and shard number, and `node` to allocate
  129. the shard to. Using this command may lead to data loss for the provided
  130. shard id. If a node which has the good copy of the data rejoins the cluster
  131. later on, that data will be deleted or overwritten with the data of the
  132. stale copy that was forcefully allocated with this command. To ensure that
  133. these implications are well-understood, this command requires the flag
  134. `accept_data_loss` to be explicitly set to `true`.
  135. `allocate_empty_primary`::
  136. Allocate an empty primary shard to a node. Accepts the `index` and `shard`
  137. for index name and shard number, and `node` to allocate the shard to. Using
  138. this command leads to a complete loss of all data that was indexed into
  139. this shard, if it was previously started. If a node which has a copy of the
  140. data rejoins the cluster later on, that data will be deleted. To ensure
  141. that these implications are well-understood, this command requires the flag
  142. `accept_data_loss` to be explicitly set to `true`.
  143. ======
  144. [[cluster-reroute-api-example]]
  145. ==== {api-examples-title}
  146. This is a short example of a simple reroute API call:
  147. [source,console]
  148. --------------------------------------------------
  149. POST /_cluster/reroute
  150. {
  151. "commands": [
  152. {
  153. "move": {
  154. "index": "test", "shard": 0,
  155. "from_node": "node1", "to_node": "node2"
  156. }
  157. },
  158. {
  159. "allocate_replica": {
  160. "index": "test", "shard": 1,
  161. "node": "node3"
  162. }
  163. }
  164. ]
  165. }
  166. --------------------------------------------------
  167. // TEST[skip:doc tests run with only a single node]