Clarify the behavior of remote/info and resolve/cluster for connected status of remotes #118993
Conversation
|
Documentation preview: |
quux00
added
auto-backport
quux00
force-pushed
the
docs/remote-info
branch
from
85b0b03 to
4e08de4
Compare
quux00
added
:Distributed Indexing/Distributed
elasticsearchmachine
added
Team:Docs
|
Pinging @elastic/es-docs (Team:Docs) |
|
Pinging @elastic/es-search-foundations (Team:Search Foundations) |
|
Pinging @elastic/es-distributed-indexing (Team:Distributed Indexing) |
quux00
requested review from
smalyshev,
DaveCTurner,
naj-h and
pawankartik-elastic
| @@ -44,7 +44,7 @@ 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 | |||
| NOTE: When querying older clusters that do not support the `_resolve/cluster` endpoint | |||
There was a problem hiding this comment.
Can we please add the exact version? For example we could say that this is introduced on 8.18
There was a problem hiding this comment.
Good idea. Added in next push.
There was a problem hiding this comment.
Actually this PR needs to backport to 8.17.2 so this note doesn't belong here in this PR. I'll pull it out into a separate PR, since I need to do some docs changes for the new timeout param as well that also only goes back to 8.18.
| @@ -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 | |||
There was a problem hiding this comment.
Nit: can we change "the cluster you are querying" and "querying cluster" by "local cluster"? just to respect the usual terminology and keep things clear
|
Hi! This is a drive-by comment to make sure folks are aware that these API docs will not be carried forward to V9, so if the changes in this PR are applicable to that version, please ensure they occur in the following locations:
That's how we'll be generating API documentation going forward (e.g. https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster and https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cluster-info). If you need any more info, lmk! |
This reverts commit d5fd9bb.
…2. Will add those back in follow on PR
|
@lcawl I don't think I understand the scope of what you are saying. These existing docs have a lot more info than just documenting the API request and response fields. Where is that information in the new docs system? For example, in the new docs, where is the equivalent of this page: https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html |
| 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. | ||
|
|
There was a problem hiding this comment.
These deleted sections will be added back in another PR that doesn't target 8.17.2.
quux00
dismissed
DaveCTurner’s stale review
Concerns have been addressed and need to merge ASAP
… status of remotes (elastic#118993)
💔 Backport failed
You can use sqren/backport to manually backport by running UPDATE: Manual backport to 8.17.2: #121203 |
… status of remotes (elastic#118993)
|
Manual backport to 8.17.2: #121203 |
We've chatted outside the PR but just in case other folks follow, I've created elastic/elasticsearch-specification#3654 to add content from this PR into the specification so it'll be included in the generated docs. Pages like https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html will continue to exist in the regular docs and can continue to contain the bigger-picture explanations and longer-form examples. |
Relates to elastic/elasticsearch#118993 This PR updates the remote info and resolve cluster specifications to (1) copy some missing descriptions from the docs (https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-remote-info.html and https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-resolve-cluster-api.html) and (2) incorporate the changes from elastic/elasticsearch#118993 Co-authored by @lcawl
Relates to elastic/elasticsearch#118993 This PR updates the remote info and resolve cluster specifications to (1) copy some missing descriptions from the docs (https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-remote-info.html and https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-resolve-cluster-api.html) and (2) incorporate the changes from elastic/elasticsearch#118993 Co-authored by @lcawl (cherry picked from commit 5b17efd)
End user docs improvements to clarify the behavior of remote/info and resolve/cluster
for connected status of remotes