diff --git a/docs/reference/cluster/voting-exclusions.asciidoc b/docs/reference/cluster/voting-exclusions.asciidoc index a2689cb5703..761b73b923e 100644 --- a/docs/reference/cluster/voting-exclusions.asciidoc +++ b/docs/reference/cluster/voting-exclusions.asciidoc @@ -11,7 +11,9 @@ Adds or removes master-eligible nodes from the [[voting-config-exclusions-api-request]] ==== {api-request-title} -`POST _cluster/voting_config_exclusions/` + +`POST _cluster/voting_config_exclusions?node_names=` + + +`POST _cluster/voting_config_exclusions?node_ids=` + `DELETE _cluster/voting_config_exclusions` @@ -42,39 +44,43 @@ master-eligible nodes. For more information, see <>. - -[[voting-config-exclusions-api-path-params]] -==== {api-path-parms-title} - -``:: - A <> that identifies {es} nodes. - - [[voting-config-exclusions-api-query-params]] ==== {api-query-parms-title} -`cluster.auto_shrink_voting_configuration`:: - (Optional, boolean) If `false`, you must use this API to maintain the voting - configuration. Defaults to `true`. +`node_names`:: +A comma-separated list of the names of the nodes to exclude from the voting +configuration. If specified, you may not also specify `?node_ids`. -`cluster.max_voting_config_exclusions`:: - (Optional, integer) Limits the size of the voting configuration exclusion - list. The default value is `10`. Since voting configuration exclusions are - persistent and limited in number, you must clear the voting config - exclusions list once the exclusions are no longer required. +`node_ids`:: +A comma-separated list of the persistent ids of the nodes to exclude from the +voting configuration. If specified, you may not also specify `?node_names`. +`timeout`:: +(Optional, <>) When adding a voting configuration +exclusion, the API waits for the specified nodes to be excluded from the voting +configuration before returning. The period of time to wait is specified by the +`?timeout` query parameter. If the timeout expires before the appropriate +condition is satisfied, the request fails and returns an error. Defaults to +`30s`. + +`wait_for_removal`:: +(Optional, boolean) Specifies whether to wait for all excluded nodes to be +removed from the cluster before clearing the voting configuration exclusions +list. Defaults to `true`, meaning that all excluded nodes must be removed from +the cluster before this API takes any action. If set to `false` then the voting +configuration exclusions list is cleared even if some excluded nodes are still +in the cluster. [[voting-config-exclusions-api-example]] ==== {api-examples-title} -Add `nodeId1` to the voting configuration exclusions list: +Adds nodes named `nodeName1` and `nodeName2` to the voting configuration +exclusions list: [source,console] -------------------------------------------------- -POST /_cluster/voting_config_exclusions/nodeId1 +POST /_cluster/voting_config_exclusions?node_names=nodeName1,nodeName2 -------------------------------------------------- -// TEST[catch:bad_request] - Remove all exclusions from the list: diff --git a/docs/reference/modules/discovery/adding-removing-nodes.asciidoc b/docs/reference/modules/discovery/adding-removing-nodes.asciidoc index 9e316294497..dae5060accf 100644 --- a/docs/reference/modules/discovery/adding-removing-nodes.asciidoc +++ b/docs/reference/modules/discovery/adding-removing-nodes.asciidoc @@ -65,22 +65,22 @@ to the voting configuration exclusion list using the # Add node to voting configuration exclusions list and wait for the system # to auto-reconfigure the node out of the voting configuration up to the # default timeout of 30 seconds -POST /_cluster/voting_config_exclusions/node_name +POST /_cluster/voting_config_exclusions?node_names=node_name # Add node to voting configuration exclusions list and wait for # auto-reconfiguration up to one minute -POST /_cluster/voting_config_exclusions/node_name?timeout=1m +POST /_cluster/voting_config_exclusions?node_names=node_name&timeout=1m -------------------------------------------------- // TEST[skip:this would break the test cluster if executed] -The node that should be added to the exclusions list is specified using -<> in place of `node_name` here. If a call to the -voting configuration exclusions API fails, you can safely retry it. Only a -successful response guarantees that the node has actually been removed from the -voting configuration and will not be reinstated. If it's the active master that -was removed from the voting configuration, then it will abdicate to another -master-eligible node that's still in the voting configuration, if such a node -is available. +The nodes that should be added to the exclusions list are specified by name +using the `?node_names` query parameter, or by their persistent node IDs using +the `?node_ids` query parameter. If a call to the voting configuration +exclusions API fails, you can safely retry it. Only a successful response +guarantees that the node has actually been removed from the voting configuration +and will not be reinstated. If the elected master node is excluded from the +voting configuration then it will abdicate to another master-eligible node that +is still in the voting configuration if such a node is available. Although the voting configuration exclusions API is most useful for down-scaling a two-node to a one-node cluster, it is also possible to use it to remove @@ -119,7 +119,7 @@ operation. If a node is excluded from the voting configuration because it is to be shut down permanently, its exclusion can be removed after it is shut down and removed from the cluster. Exclusions can also be cleared if they were created in error -or were only required temporarily: +or were only required temporarily by specifying `?wait_for_removal=false`. [source,console] --------------------------------------------------