Add documentation for Java API health API

Closes #10818.

docs/java-api/admin/cluster/health.asciidoc

@@ -0,0 +1,76 @@
+[[java-admin-cluster-health]]
+==== Cluster Health
+
+[[java-admin-cluster-health-health]]
+===== Health
+
+The cluster health API allows to get a very simple status on the health of the cluster and also can give you
+some technical information about the cluster status per index:
+
+[source,java]
+--------------------------------------------------
+ClusterHealthResponse healths = client.admin().cluster().prepareHealth().get(); <1>
+String clusterName = healths.getClusterName();              <2>
+int numberOfDataNodes = healths.getNumberOfDataNodes();     <3>
+int numberOfNodes = healths.getNumberOfNodes();             <4>
+
+for (ClusterIndexHealth health : healths) {                 <5>
+    String index = health.getIndex();                       <6>
+    int numberOfShards = health.getNumberOfShards();        <7>
+    int numberOfReplicas = health.getNumberOfReplicas();    <8>
+    ClusterHealthStatus status = health.getStatus();        <9>
+}
+--------------------------------------------------
+<1> Get information for all indices
+<2> Access the cluster name
+<3> Get the total number of data nodes
+<4> Get the total number of nodes
+<5> Iterate over all indices
+<6> Index name
+<7> Number of shards
+<8> Number of replicas
+<9> Index status
+
+[[java-admin-cluster-health-wait-status]]
+===== Wait for status
+
+You can use the cluster health API to wait for a specific status for the whole cluster or for a given index:
+
+[source,java]
+--------------------------------------------------
+client.admin().cluster().prepareHealth()            <1>
+        .setWaitForYellowStatus()                   <2>
+        .get();
+client.admin().cluster().prepareHealth("company")   <3>
+        .setWaitForGreenStatus()                    <4>
+        .get();
+
+client.admin().cluster().prepareHealth("employee")  <5>
+        .setWaitForGreenStatus()                    <6>
+        .setTimeout(TimeValue.timeValueSeconds(2))  <7>
+        .get();
+--------------------------------------------------
+<1> Prepare a health request
+<2> Wait for the cluster being yellow
+<3> Prepare the health request for index `company`
+<4> Wait for the index being green
+<5> Prepare the health request for index `employee`
+<6> Wait for the index being green
+<7> Wait at most for 2 seconds
+
+If the index does not have the expected status and you want to fail in that case, you need
+to explicitly interpret the result:
+
+[source,java]
+--------------------------------------------------
+ClusterHealthResponse response = client.admin().cluster().prepareHealth("company")
+        .setWaitForGreenStatus()    <1>
+        .get();
+
+ClusterHealthStatus status = response.getIndices().get("company").getStatus();
+if (!status.equals(ClusterHealthStatus.GREEN)) {
+    throw new RuntimeException("Index is in " + status + " state"); <2>
+}
+--------------------------------------------------
+<1> Wait for the index being green
+<2> Throw an exception if not `GREEN`

docs/java-api/admin/cluster/index.asciidoc

@@ -5,6 +5,11 @@ To access cluster Java API, you need to call `cluster()` method from an <<java-a
 
 [source,java]
 --------------------------------------------------
-ClusterAdminClient clusterAdminClient = adminClient.cluster();
+ClusterAdminClient clusterAdminClient = client.admin().cluster();
 --------------------------------------------------
 
+[NOTE]
+In the rest of this guide, we will use `client.admin().cluster()`.
+
+include::health.asciidoc[]
+