diff --git a/docs/reference/indices/resolve-cluster.asciidoc b/docs/reference/indices/resolve-cluster.asciidoc index f7d21e8c0b8ea..195cbb997adb1 100644 --- a/docs/reference/indices/resolve-cluster.asciidoc +++ b/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 <> 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 <> 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 <> 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 <> 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