Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 29, 2025
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 50 additions & 8 deletions docs/reference/indices/resolve-cluster.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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)
Expand All @@ -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]
--------------------------------
Expand Down Expand Up @@ -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-*
Expand Down Expand Up @@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention the setting that influences this timeout?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is it and is it something the user can configure?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

transport.connect_timeout. It may or may not exist—if it doesn't, handshake defaults to 30s. On a second thought, maybe let's not mention it. If we unintentionally lead users to this setting and they modify it, it has an effect outside this API's scope—something that could be undesired.

+

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.
Expand All @@ -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]]
Expand All @@ -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.

Expand Down Expand Up @@ -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:*//]
Expand Down Expand Up @@ -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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not for this patch, but I wonder if it'd help if the error message included the actual timeout value. So the user would know whether the cluster failed to respond in 1s (maybe the timeout too low?) or in 300s (definitely it's dead and also maybe timeout too long).

},
"oldcluster": { <5>
"connected": true,
"skip_unavailable": false,
"matching_indices": true
Expand All @@ -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
Expand Down