From f808fae4d265a50aa231e9e67995e399a48b1ba9 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 10:08:25 -0500 Subject: [PATCH] Clarify the behavior of remote/info and resolve/cluster for connected status of remotes (#118993) --- docs/reference/cluster/remote-info.asciidoc | 17 +++++- .../indices/resolve-cluster.asciidoc | 56 +++++++------------ 2 files changed, 35 insertions(+), 38 deletions(-) diff --git a/docs/reference/cluster/remote-info.asciidoc b/docs/reference/cluster/remote-info.asciidoc index 691acafd8ddbe..e91ccc4d8f4a1 100644 --- a/docs/reference/cluster/remote-info.asciidoc +++ b/docs/reference/cluster/remote-info.asciidoc @@ -26,10 +26,18 @@ Returns configured remote cluster information. [[cluster-remote-info-api-desc]] ==== {api-description-title} -The cluster remote info API allows you to retrieve all of the configured -remote cluster information. It returns connection and endpoint information keyed +The cluster remote info API allows you to retrieve information about configured +remote clusters. It returns connection and endpoint information keyed by the configured remote cluster alias. +TIP: This API returns information that reflects current state on the local cluster. +The `connected` field does not necessarily reflect whether a remote cluster is +down or unavailable, only whether there is currently an open connection to it. +Elasticsearch does not spontaneously try to reconnect to a disconnected remote +cluster. To trigger a reconnection, attempt a <>, +<>, or try the +<> endpoint. + [[cluster-remote-info-api-response-body]] ==== {api-response-body-title} @@ -39,7 +47,10 @@ by the configured remote cluster alias. `proxy`. `connected`:: - True if there is at least one connection to the remote cluster. + True if there is at least one open connection to the remote cluster. When + false, it means that the cluster no longer has an open connection to the + remote cluster. It does not necessarily mean that the remote cluster is + down or unavailable, just that at some point a connection was lost. `initial_connect_timeout`:: The initial connect timeout for remote cluster connections. diff --git a/docs/reference/indices/resolve-cluster.asciidoc b/docs/reference/indices/resolve-cluster.asciidoc index b1d379e50557c..f7d21e8c0b8ea 100644 --- a/docs/reference/indices/resolve-cluster.asciidoc +++ b/docs/reference/indices/resolve-cluster.asciidoc @@ -11,9 +11,7 @@ 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. If no index expression -is provided, this endpoint will return information about all the remote -clusters that are configured on the querying cluster. +each cluster, including the local "querying" cluster, if included. This endpoint is useful before doing a <> in order to determine which remote clusters should be included in a search. @@ -24,10 +22,12 @@ with this endpoint. For each cluster in scope, information is returned about: -1. whether the querying ("local") cluster is currently connected to it +1. whether the querying ("local") cluster was able to connect to each remote cluster + specified in the index expression. Note that this endpoint actively attempts to + 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 (if one provided) + the index expression 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,12 +42,6 @@ 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: When querying older clusters that do not support the _resolve/cluster endpoint -without an index expression, the local cluster will send the index expression `dummy*` -to those remote clusters, so 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 this endpoint to bypass the issue. - //// [source,console] -------------------------------- @@ -77,14 +71,6 @@ 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. - [source,console] ---- GET /_resolve/cluster/my-index-*,cluster*:my-index-* @@ -140,21 +126,28 @@ 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]] +=== Test availability of remote clusters + +The <> endpoint is commonly used to test whether the "local" +cluster (the cluster being queried) is connected to its remote clusters, but it does not +necessarily reflect whether the remote cluster is available or not. The remote cluster may +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. +If a connection was (re-)established, this will also cause the +<> endpoint to now indicate a connected status. + + === Advantages of using this endpoint before a {ccs} You may want to exclude a cluster or index from a search when: -1. A remote cluster is not currently connected and is configured with `skip_unavailable`=`false`. +1. A remote cluster could not be connected to and is configured with `skip_unavailable`=`false`. Executing a {ccs} under those conditions will cause <>. @@ -268,14 +261,7 @@ GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailab }, "cluster_two": { "connected": false, <3> - "skip_unavailable": false, - "matching_indices": true, - "version": { - "number": "8.13.0", - "build_flavor": "default", - "minimum_wire_compatibility_version": "7.17.0", - "minimum_index_compatibility_version": "7.0.0" - } + "skip_unavailable": false }, "oldcluster": { <4> "connected": true,