Skip to content

Adjust docs for voting config exclusions API #55006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 20, 2020
Merged

Adjust docs for voting config exclusions API #55006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8fda24d
Adjust docs for voting config exclusions API
DaveCTurner Apr 9, 2020
728377b
Fix other reference to node filters
DaveCTurner Apr 9, 2020
4ffd419
Merge branch 'master' into 2020-04-09-voting-config-exclusions-docs
DaveCTurner Apr 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 29 additions & 23 deletions docs/reference/cluster/voting-exclusions.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<node_name>` +
`POST _cluster/voting_config_exclusions?node_names=<node_names>` +

`POST _cluster/voting_config_exclusions?node_ids=<node_ids>` +

`DELETE _cluster/voting_config_exclusions`

Expand Down Expand Up @@ -42,39 +44,43 @@ master-eligible nodes.

For more information, see <<modules-discovery-removing-nodes>>.


[[voting-config-exclusions-api-path-params]]
==== {api-path-parms-title}

`<node_name>`::
A <<cluster-nodes,node filter>> 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`.

`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_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`.

`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, <<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`.

`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:

Expand Down
22 changes: 11 additions & 11 deletions docs/reference/modules/discovery/adding-removing-nodes.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<<cluster-nodes,node filters>> 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
Expand Down Expand Up @@ -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]
--------------------------------------------------
Expand Down