Browse Source

Clarify status of response to voting config API (#115714) (#115732)

These APIs return no body, just a status code. This commit clarifies
that in the docs.

Closes #115462
David Turner 11 months ago
parent
commit
7e02a7cd36
1 changed files with 13 additions and 9 deletions
  1. 13 9
      docs/reference/cluster/voting-exclusions.asciidoc

+ 13 - 9
docs/reference/cluster/voting-exclusions.asciidoc

@@ -7,7 +7,6 @@
 Adds or removes master-eligible nodes from the
 <<modules-discovery-voting,voting configuration exclusion list>>.
 
-
 [[voting-config-exclusions-api-request]]
 ==== {api-request-title}
 
@@ -28,7 +27,7 @@ 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
@@ -50,14 +49,19 @@ 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.
 
-If the API fails, you can safely retry it. Only a successful response
-guarantees that the node has been removed from the voting configuration and
-will not be reinstated.
+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 fewer than half of the
-master-eligible nodes.
+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>>.
 
@@ -94,7 +98,7 @@ 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}
 
@@ -102,7 +106,7 @@ Adds nodes named `nodeName1` and `nodeName2` to the voting configuration
 exclusions list:
 
 [source,console]
--------------------------------------------------- 
+--------------------------------------------------
 POST /_cluster/voting_config_exclusions?node_names=nodeName1,nodeName2
 --------------------------------------------------