Updated resolve/cluster end user docs with information about the timeout flag and no index expression endpoint (#121199)

Author: quux00

docs/reference/indices/resolve-cluster.asciidoc

@@ -11,7 +11,9 @@ For the most up-to-date API details, refer to {api-es}/group/endpoint-indices[In
 --
 
 Resolves the specified index expressions to return information about
-each cluster, including the local "querying" cluster, if included.
+each cluster, including the local "querying" cluster, if included. If no index expression
+is provided, this endpoint will return information about all the remote
+clusters that are configured on the querying cluster.
 
 This endpoint is useful before doing a <<modules-cross-cluster-search,{ccs}>> in
 order to determine which remote clusters should be included in a search.
@@ -27,7 +29,7 @@ For each cluster in scope, information is returned about:
    contact the remote clusters, unlike the <<cluster-remote-info,remote/info>> endpoint.
 2. whether each remote cluster is configured with `skip_unavailable` as `true` or `false`
 3. whether there are any indices, aliases or data streams on that cluster that match
-   the index expression
+   the index expression (if one provided)
 4. whether the search is likely to have errors returned when you do a {ccs} (including any
    authorization errors if your user does not have permission to query a remote cluster or
    the indices on that cluster)
@@ -42,6 +44,12 @@ Once the proper security permissions are obtained, then you can rely on the `con
 in the response to determine whether the remote cluster is available and ready for querying.
 ====
 
+NOTE: The ability to query without an index expression was added in 8.18, so when
+querying remote clusters older than that, the local cluster will send the index
+expression `dummy*` to those remote clusters. Thus, if an errors occur, you may see a reference
+to that index expression even though you didn't request it. If it causes a problem, you can
+instead include an index expression like `*:*` to bypass the issue.
+
 ////
 [source,console]
 --------------------------------
@@ -71,6 +79,15 @@ PUT _cluster/settings
 // TEST[s/35.238.149.\d+:930\d+/\${transport_host}/]
 ////
 
+[source,console]
+----
+GET /_resolve/cluster
+----
+// TEST[continued]
+
+Returns information about all remote clusters configured on the local cluster
+without doing any index matching.
+
 [source,console]
 ----
 GET /_resolve/cluster/my-index-*,cluster*:my-index-*
@@ -108,6 +125,15 @@ Resources on <<remote-clusters,remote clusters>> can be specified using the
 [[resolve-cluster-api-query-params]]
 ==== {api-query-parms-title}
 
+`timeout`::
+(Optional, TimeValue) Specify a max wait time for remote clusters to respond.
+If a remote cluster does not respond within this timeout period, the API response
+will show the cluster as not connected and include an error message that the
+request timed out. The default timeout is unset and the query can take
+as long as the networking layer is configured to wait for remote clusters that are
+not responding (typically 30 seconds).
++
+
 include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
 +
 Defaults to `open`.
@@ -126,6 +152,13 @@ ignored when frozen. Defaults to `false`.
 +
 deprecated:[7.16.0]
 
+[TIP]
+====
+The index options above are only allowed when specifying an index expression.
+You will get an error if you specify index options to the _resolve/cluster API
+that takes no index expression.
+====
+
 
 [discrete]
 [[usecases-for-resolve-cluster]]
@@ -137,8 +170,8 @@ necessarily reflect whether the remote cluster is available or not. The remote c
 be available, while the local cluster is not currently connected to it.
 
 You can use the resolve-cluster API to attempt to reconnect to remote clusters
-(for example with `GET _resolve/cluster/*:*`) and
-the `connected` field in the response will indicate whether it was successful or not.
+(for example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*` ).
+The `connected` field in the response will indicate whether it was successful.
 If a connection was (re-)established, this will also cause the
 <<cluster-remote-info,remote/info>> endpoint to now indicate a connected status.
 
@@ -231,11 +264,12 @@ The API returns the following response:
 ==== Identifying potential problems with your {ccs}
 
 The following request shows several examples of how modifying your query can
-prevent search failures.
+prevent search failures. Note also that a `timeout` of 5 seconds is sent, which
+sets the maximum time the query will wait for remote clusters to respond.
 
 [source,console]
 --------------------------------------------------
-GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false
+GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false&timeout=5s
 --------------------------------------------------
 // TEST[continued]
 // TEST[s/,oldcluster:*//]
@@ -263,7 +297,12 @@ GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailab
     "connected": false,           <3>
     "skip_unavailable": false
   },
-  "oldcluster": {         <4>
+  "cluster_three": {
+    "connected": false,
+    "skip_unavailable": false,
+    "error": "Request timed out before receiving a response from the remote cluster"  <4>
+  },
+  "oldcluster": {         <5>
     "connected": true,
     "skip_unavailable": false,
     "matching_indices": true
@@ -285,7 +324,10 @@ could be closed. (You can check this by using the
 failed). Since this cluster is marked as `skip_unavailable=false`, you should
 probably exclude this cluster from the search by adding `-cluster_two:*` to the
 search index expression.
-<4> The `oldcluster` remote cluster shows that it has matching indices, but no
+<4> For `cluster_three`, the error message indicates that this remote cluster did
+not respond within the 5-second timeout window specified, so it is also marked as
+not connected.
+<5> The `oldcluster` remote cluster shows that it has matching indices, but no
 version information is included. This indicates that the cluster version predates
 the introduction of the `_resolve/cluster` API in 8.13.0., so you may want to
 exclude it from your {ccs}. (Note: the endpoint was able to tell there were