From 9cbdc64ffd946067837c858c4545ef332b3ddf15 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Luk=C3=A1=C5=A1=20Vl=C4=8Dek?= <lukas.vlcek@aiven.io>
Date: Wed, 4 May 2022 16:22:45 +0200
Subject: [PATCH] Document missing wait_for_nodes param in Cluster health
 Reference REST API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Additional improvements:

- The master_timeout is marked as deprecated and cluster_manager_timeout is suggested instead
- A required permissions is also documented
- The JSON example response is completed

Closes: #552
Signed-off-by: Lukáš Vlček <lukas.vlcek@aiven.io>
---
 _opensearch/rest-api/cluster-health.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/_opensearch/rest-api/cluster-health.md b/_opensearch/rest-api/cluster-health.md
index 64c7a909da..33cac6500e 100644
--- a/_opensearch/rest-api/cluster-health.md
+++ b/_opensearch/rest-api/cluster-health.md
@@ -39,13 +39,14 @@ Parameter | Type | Description
 expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
 level | Enum | The level of detail for returned health information. Supported values are `cluster`, `indices`, and `shards`. Default is `cluster`.
 local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
-master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
+cluster_manager_timeout<br>(deprecated `master_timeout`) | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
 timeout | Time | The amount of time to wait for a response. If the timeout expires, the request fails. Default is 30 seconds.
 wait_for_active_shards | String | Wait until the specified number of shards is active before returning a response. `all` for all shards. Default is `0`.
+wait_for_nodes | String | Wait for N number of nodes. Use `12` for exact match, `>12` and `<12` for range.
 wait_for_events | Enum | Wait until all currently queued events with the given priority are processed. Supported values are `immediate`, `urgent`, `high`, `normal`, `low`, and `languid`.
 wait_for_no_relocating_shards | Boolean | Whether to wait until there are no relocating shards in the cluster. Default is false.
 wait_for_no_initializing_shards | Boolean | Whether to wait until there are no initializing shards in the cluster. Default is false.
-wait_for_status | Enum | Wait until the cluster is in a specific state or better. Supported values are `green`, `yellow`, and `red`.
+wait_for_status | Enum | Wait until the cluster health reaches specific status or better. Supported values are `green`, `yellow`, and `red`.
 
 <!-- wait_for_nodes | string | Wait until the specified number of nodes is available. Also supports operators <=, >=, <, and >
 # Not working properly when tested -->
@@ -59,6 +60,7 @@ wait_for_status | Enum | Wait until the cluster is in a specific state or better
   "timed_out" : false,
   "number_of_nodes" : 2,
   "number_of_data_nodes" : 2,
+  "discovered_master" : true,
   "active_primary_shards" : 6,
   "active_shards" : 12,
   "relocating_shards" : 0,
@@ -71,3 +73,9 @@ wait_for_status | Enum | Wait until the cluster is in a specific state or better
   "active_shards_percent_as_number" : 100.0
 }
 ```
+
+## Required permissions
+
+If you use the security plugin, make sure you have the appropriate permissions:
+`cluster:monitor/health`
+{: .note }
\ No newline at end of file