mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
124 lines
5.2 KiB
Text
124 lines
5.2 KiB
Text
[[voting-config-exclusions]]
|
|
=== Voting configuration exclusions API
|
|
++++
|
|
<titleabbrev>Voting configuration exclusions</titleabbrev>
|
|
++++
|
|
|
|
..New API reference
|
|
[sidebar]
|
|
--
|
|
For the most up-to-date API details, refer to {api-es}/group/endpoint-cluster[Cluster APIs].
|
|
--
|
|
|
|
Adds or removes master-eligible nodes from the
|
|
<<modules-discovery-voting,voting configuration exclusion list>>.
|
|
|
|
[[voting-config-exclusions-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_cluster/voting_config_exclusions?node_names=<node_names>` +
|
|
|
|
`POST /_cluster/voting_config_exclusions?node_ids=<node_ids>` +
|
|
|
|
`DELETE /_cluster/voting_config_exclusions`
|
|
|
|
[[voting-config-exclusions-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the `manage`
|
|
<<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
* If the <<operator-privileges,{operator-feature}>> is enabled, only operator
|
|
users can use this API.
|
|
|
|
[[voting-config-exclusions-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
By default, if there are more than three master-eligible nodes in the cluster
|
|
and you remove fewer than half of the master-eligible nodes in the cluster at
|
|
once, the <<modules-discovery-voting,voting configuration>> automatically
|
|
shrinks.
|
|
|
|
If you want to shrink the voting configuration to contain fewer than three
|
|
nodes or to remove half or more of the master-eligible nodes in the cluster at
|
|
once, use this API to remove departing nodes from the voting configuration
|
|
manually. The API adds an entry for each specified node to the cluster's voting
|
|
configuration exclusions list. It then waits until the cluster has reconfigured
|
|
its voting configuration to exclude the specified nodes.
|
|
|
|
Clusters should have no voting configuration exclusions in normal operation.
|
|
Once the excluded nodes have stopped, clear the voting configuration exclusions
|
|
with `DELETE /_cluster/voting_config_exclusions`. This API waits for the nodes
|
|
to be fully removed from the cluster before it returns. If your cluster has
|
|
voting configuration exclusions for nodes that you no longer intend to remove,
|
|
use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear
|
|
the voting configuration exclusions without waiting for the nodes to leave the
|
|
cluster.
|
|
|
|
A response to `POST /_cluster/voting_config_exclusions` with an HTTP status
|
|
code of `200 OK` guarantees that the node has been removed from the voting
|
|
configuration and will not be reinstated until the voting configuration
|
|
exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.
|
|
If the call to `POST /_cluster/voting_config_exclusions` fails or returns a
|
|
response with an HTTP status code other than `200 OK` then the node may not
|
|
have been removed from the voting configuration. In that case, you may safely
|
|
retry the call.
|
|
|
|
NOTE: Voting exclusions are required only when you remove at least half of the
|
|
master-eligible nodes from a cluster in a short time period. They are not
|
|
required when removing master-ineligible nodes or when removing fewer than half
|
|
of the master-eligible nodes.
|
|
|
|
For more information, see <<modules-discovery-removing-nodes>>.
|
|
|
|
[[voting-config-exclusions-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`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`. Only applies
|
|
to the `POST` form of this API.
|
|
|
|
`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`.
|
|
Only applies to the `POST` form of this API.
|
|
|
|
`timeout`::
|
|
(Optional, <<time-units, time units>>) 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`. Only applies to the `POST` form of this API.
|
|
|
|
`master_timeout`::
|
|
(Optional, <<time-units, time units>>) Defines how long to wait while trying to
|
|
route the request to the current master node in the cluster. Defaults to `30s`.
|
|
Applies to both `POST` and `DELETE` forms of this API.
|
|
|
|
`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. Only applies to the `DELETE` form of this API.
|
|
|
|
[[voting-config-exclusions-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
Adds nodes named `nodeName1` and `nodeName2` to the voting configuration
|
|
exclusions list:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
POST /_cluster/voting_config_exclusions?node_names=nodeName1,nodeName2
|
|
--------------------------------------------------
|
|
|
|
Remove all exclusions from the list:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
DELETE /_cluster/voting_config_exclusions
|
|
--------------------------------------------------
|