From 85b0b03788cf0dd5cdb7392a593a4942f30f2403 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 18 Dec 2024 12:17:12 -0500 Subject: [PATCH] Clarify the behavior of remote/info and resolve/cluster for connected status of remotes --- docs/reference/cluster/remote-info.asciidoc | 14 ++++++++++++- .../indices/resolve-cluster.asciidoc | 21 +++++++++++++++---- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/reference/cluster/remote-info.asciidoc b/docs/reference/cluster/remote-info.asciidoc index 8f2923846df0e..08b48407b830c 100644 --- a/docs/reference/cluster/remote-info.asciidoc +++ b/docs/reference/cluster/remote-info.asciidoc @@ -25,6 +25,15 @@ The cluster remote info API allows you to retrieve all of the configured remote cluster information. It returns connection and endpoint information keyed by the configured remote cluster alias. +TIP: This endpoint returns the information that reflects state on the cluster +you are querying. The `connected` field reports whether the querying cluster is +currently connected to the remote cluster. It does not necessarily reflect whether +the 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} @@ -34,7 +43,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 48e6bfac4af10..193b10bd3c60d 100644 --- a/docs/reference/indices/resolve-cluster.asciidoc +++ b/docs/reference/indices/resolve-cluster.asciidoc @@ -16,8 +16,9 @@ with this endpoint. For each cluster in the index expression, information is returned about: -1. whether the querying ("local") cluster is currently connected to each remote cluster - in the index expression scope +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 @@ -110,8 +111,21 @@ ignored when frozen. Defaults to `false`. deprecated:[7.16.0] -[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 this API to force a reconnection (for example with `GET _resolve/cluster/*:*`) and +examine the `connected` field in the response for each remote. This will also cause the +<> endpoint to now reflect the fact that a connection has +been (re-)established. + + === Advantages of using this endpoint before a {ccs} You may want to exclude a cluster or index from a search when: @@ -195,7 +209,6 @@ The API returns the following response: <5> The Elasticsearch server version. -[discrete] [[resolve-cluster-api-error-example]] ==== Identifying potential problems with your {ccs}