diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 63d5e0c27c..fdf63d3274 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -4334,7 +4334,10 @@ "cluster" ], "summary": "Get remote cluster information", - "description": "Get all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> 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.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html" + }, "operationId": "cluster-remote-info", "responses": { "200": { @@ -15135,80 +15138,70 @@ "x-state": "Added in 7.3.0" } }, - "/_resolve/cluster/{name}": { + "/_resolve/cluster": { "get": { "tags": [ "indices" ], "summary": "Resolve the cluster", - "description": "Resolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Note on backwards compatibility\nThe ability to query without an index expression was added in version 8.18, so when\nquerying remote clusters older than that, the local cluster will send the index\nexpression `dummy*` to those remote clusters. Thus, if an errors occur, you may see a reference\nto that index expression even though you didn't request it. If it causes a problem, you can\ninstead include an index expression like `*:*` to bypass the issue.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` 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.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "operationId": "indices-resolve-cluster", "parameters": [ { - "in": "path", - "name": "name", - "description": "Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", - "required": true, - "deprecated": false, - "schema": { - "$ref": "#/components/schemas/_types:Names" - }, - "style": "simple" + "$ref": "#/components/parameters/indices.resolve_cluster#allow_no_indices" }, { - "in": "query", - "name": "allow_no_indices", - "description": "If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.", - "deprecated": false, - "schema": { - "type": "boolean" - }, - "style": "form" + "$ref": "#/components/parameters/indices.resolve_cluster#expand_wildcards" }, { - "in": "query", - "name": "expand_wildcards", - "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.\nValid values are: `all`, `open`, `closed`, `hidden`, `none`.", - "deprecated": false, - "schema": { - "$ref": "#/components/schemas/_types:ExpandWildcards" - }, - "style": "form" + "$ref": "#/components/parameters/indices.resolve_cluster#ignore_throttled" }, { - "in": "query", - "name": "ignore_throttled", - "description": "If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.", - "deprecated": false, - "schema": { - "type": "boolean" - }, - "style": "form" + "$ref": "#/components/parameters/indices.resolve_cluster#ignore_unavailable" }, { - "in": "query", - "name": "ignore_unavailable", - "description": "If false, the request returns an error if it targets a missing or closed index. Defaults to false.", - "deprecated": false, - "schema": { - "type": "boolean" - }, - "style": "form" + "$ref": "#/components/parameters/indices.resolve_cluster#timeout" } ], "responses": { "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "additionalProperties": { - "$ref": "#/components/schemas/indices.resolve_cluster:ResolveClusterInfo" - } - } - } - } + "$ref": "#/components/responses/indices.resolve_cluster#200" + } + }, + "x-state": "Added in 8.13.0" + } + }, + "/_resolve/cluster/{name}": { + "get": { + "tags": [ + "indices" + ], + "summary": "Resolve the cluster", + "description": "Resolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Note on backwards compatibility\nThe ability to query without an index expression was added in version 8.18, so when\nquerying remote clusters older than that, the local cluster will send the index\nexpression `dummy*` to those remote clusters. Thus, if an errors occur, you may see a reference\nto that index expression even though you didn't request it. If it causes a problem, you can\ninstead include an index expression like `*:*` to bypass the issue.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` 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.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", + "operationId": "indices-resolve-cluster-1", + "parameters": [ + { + "$ref": "#/components/parameters/indices.resolve_cluster#name" + }, + { + "$ref": "#/components/parameters/indices.resolve_cluster#allow_no_indices" + }, + { + "$ref": "#/components/parameters/indices.resolve_cluster#expand_wildcards" + }, + { + "$ref": "#/components/parameters/indices.resolve_cluster#ignore_throttled" + }, + { + "$ref": "#/components/parameters/indices.resolve_cluster#ignore_unavailable" + }, + { + "$ref": "#/components/parameters/indices.resolve_cluster#timeout" + } + ], + "responses": { + "200": { + "$ref": "#/components/responses/indices.resolve_cluster#200" } }, "x-state": "Added in 8.13.0" @@ -66034,27 +66027,33 @@ "type": "object", "properties": { "mode": { + "description": "The connection mode for the remote cluster.", "type": "string", "enum": [ "sniff" ] }, "connected": { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "type": "boolean" }, "max_connections_per_cluster": { + "description": "The maximum number of connections maintained for the remote cluster when sniff mode is configured.", "type": "number" }, "num_nodes_connected": { + "description": "The number of connected nodes in the remote cluster when sniff mode is configured.", "type": "number" }, "initial_connect_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", "type": "boolean" }, "seeds": { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "type": "array", "items": { "type": "string" @@ -66075,31 +66074,41 @@ "type": "object", "properties": { "mode": { + "description": "The connection mode for the remote cluster.", "type": "string", "enum": [ "proxy" ] }, "connected": { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "type": "boolean" }, "initial_connect_timeout": { "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", "type": "boolean" }, "proxy_address": { + "description": "The address for remote connections when proxy mode is configured.", "type": "string" }, "server_name": { "type": "string" }, "num_proxy_sockets_connected": { + "description": "The number of open socket connections to the remote cluster when proxy mode is configured.", "type": "number" }, "max_proxy_socket_connections": { + "description": "The maximum number of socket connections to the remote cluster when proxy mode is configured.", "type": "number" + }, + "cluster_credentials": { + "description": "This field presents and has value of ::es_redacted:: only when the remote cluster is configured with the API key based model. Otherwise, the field is not present.", + "type": "string" } }, "required": [ @@ -95418,6 +95427,19 @@ } } }, + "indices.resolve_cluster#200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/indices.resolve_cluster:ResolveClusterInfo" + } + } + } + } + }, "indices.rollover#200": { "description": "", "content": { @@ -102542,6 +102564,67 @@ }, "style": "form" }, + "indices.resolve_cluster#name": { + "in": "path", + "name": "name", + "description": "A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.\nIndex and cluster exclusions (e.g., `-cluster1:*`) are also supported.\nIf no index expression is specified, information about all remote clusters configured on the local cluster\nis returned without doing any index matching", + "required": true, + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Names" + }, + "style": "simple" + }, + "indices.resolve_cluster#allow_no_indices": { + "in": "query", + "name": "allow_no_indices", + "description": "If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + "indices.resolve_cluster#expand_wildcards": { + "in": "query", + "name": "expand_wildcards", + "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.\nValid values are: `all`, `open`, `closed`, `hidden`, `none`.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:ExpandWildcards" + }, + "style": "form" + }, + "indices.resolve_cluster#ignore_throttled": { + "in": "query", + "name": "ignore_throttled", + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", + "deprecated": true, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + "indices.resolve_cluster#ignore_unavailable": { + "in": "query", + "name": "ignore_unavailable", + "description": "If false, the request returns an error if it targets a missing or closed index.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + }, + "indices.resolve_cluster#timeout": { + "in": "query", + "name": "timeout", + "description": "The maximum time to wait for remote clusters to respond.\nIf a remote cluster does not respond within this timeout period, the API response\nwill show the cluster as not connected and include an error message that the\nrequest timed out.\n\nThe default timeout is unset and the query can take\nas long as the networking layer is configured to wait for remote clusters that are\nnot responding (typically 30 seconds).", + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Duration" + }, + "style": "form" + }, "indices.rollover#alias": { "in": "path", "name": "alias", diff --git a/output/schema/schema-serverless.json b/output/schema/schema-serverless.json index 23670a0b17..bd87db996d 100644 --- a/output/schema/schema-serverless.json +++ b/output/schema/schema-serverless.json @@ -93798,6 +93798,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -93806,6 +93807,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -93817,6 +93819,7 @@ } }, { + "description": "The maximum number of connections maintained for the remote cluster when sniff mode is configured.", "name": "max_connections_per_cluster", "required": true, "type": { @@ -93828,6 +93831,7 @@ } }, { + "description": "The number of connected nodes in the remote cluster when sniff mode is configured.", "name": "num_nodes_connected", "required": true, "type": { @@ -93839,6 +93843,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -93850,6 +93855,8 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", "name": "skip_unavailable", "required": true, "type": { @@ -93861,6 +93868,7 @@ } }, { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "name": "seeds", "required": true, "type": { @@ -93875,7 +93883,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L40" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L56" }, { "kind": "interface", @@ -93885,6 +93893,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -93893,6 +93902,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -93904,6 +93914,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -93915,6 +93926,8 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", "name": "skip_unavailable", "required": true, "type": { @@ -93926,6 +93939,7 @@ } }, { + "description": "The address for remote connections when proxy mode is configured.", "name": "proxy_address", "required": true, "type": { @@ -93948,6 +93962,7 @@ } }, { + "description": "The number of open socket connections to the remote cluster when proxy mode is configured.", "name": "num_proxy_sockets_connected", "required": true, "type": { @@ -93959,6 +93974,7 @@ } }, { + "description": "The maximum number of socket connections to the remote cluster when proxy mode is configured.", "name": "max_proxy_socket_connections", "required": true, "type": { @@ -93968,9 +93984,21 @@ "namespace": "_types" } } + }, + { + "description": "This field presents and has value of ::es_redacted:: only when the remote cluster is configured with the API key based model. Otherwise, the field is not present.", + "name": "cluster_credentials", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L42-L51" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L58-L83" }, { "kind": "type_alias", diff --git a/output/schema/schema.json b/output/schema/schema.json index 35e95ade29..760e6abff1 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2750,10 +2750,17 @@ "stability": "stable" } }, - "description": "Get remote cluster information.\nGet all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get remote cluster information.\n\nGet information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> 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.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", "docId": "cluster-remote-info", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-remote-info.html", + "extDocId": "modules-cross-cluster-search", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html", "name": "cluster.remote_info", + "privileges": { + "cluster": [ + "monitor" + ] + }, "request": { "name": "Request", "namespace": "cluster.remote_info" @@ -8437,7 +8444,7 @@ "stability": "stable" } }, - "description": "Resolve the cluster.\nResolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the cluster.\n\nResolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Note on backwards compatibility\nThe ability to query without an index expression was added in version 8.18, so when\nquerying remote clusters older than that, the local cluster will send the index\nexpression `dummy*` to those remote clusters. Thus, if an errors occur, you may see a reference\nto that index expression even though you didn't request it. If it causes a problem, you can\ninstead include an index expression like `*:*` to bypass the issue.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` 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.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "docId": "indices-resolve-cluster-api", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-resolve-cluster-api.html", "name": "indices.resolve_cluster", @@ -8459,6 +8466,12 @@ "application/json" ], "urls": [ + { + "methods": [ + "GET" + ], + "path": "/_resolve/cluster" + }, { "methods": [ "GET" @@ -111506,6 +111519,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111514,6 +111528,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -111525,6 +111540,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111536,6 +111552,8 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", "name": "skip_unavailable", "required": true, "type": { @@ -111547,6 +111565,7 @@ } }, { + "description": "The address for remote connections when proxy mode is configured.", "name": "proxy_address", "required": true, "type": { @@ -111569,6 +111588,7 @@ } }, { + "description": "The number of open socket connections to the remote cluster when proxy mode is configured.", "name": "num_proxy_sockets_connected", "required": true, "type": { @@ -111580,6 +111600,7 @@ } }, { + "description": "The maximum number of socket connections to the remote cluster when proxy mode is configured.", "name": "max_proxy_socket_connections", "required": true, "type": { @@ -111589,9 +111610,21 @@ "namespace": "_types" } } + }, + { + "description": "This field presents and has value of ::es_redacted:: only when the remote cluster is configured with the API key based model. Otherwise, the field is not present.", + "name": "cluster_credentials", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "string", + "namespace": "_builtins" + } + } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L42-L51" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L58-L83" }, { "kind": "interface", @@ -111601,6 +111634,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111609,6 +111643,7 @@ } }, { + "description": "If it is `true`, there is at least one open connection to the remote cluster.\nIf it is `false`, it means that the cluster no longer has an open connection to the remote cluster.\nIt does not necessarily mean that the remote cluster is down or unavailable, just that at some point a connection was lost.", "name": "connected", "required": true, "type": { @@ -111620,6 +111655,7 @@ } }, { + "description": "The maximum number of connections maintained for the remote cluster when sniff mode is configured.", "name": "max_connections_per_cluster", "required": true, "type": { @@ -111631,6 +111667,7 @@ } }, { + "description": "The number of connected nodes in the remote cluster when sniff mode is configured.", "name": "num_nodes_connected", "required": true, "type": { @@ -111642,6 +111679,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111653,6 +111691,8 @@ } }, { + "description": "If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster.", + "extDocId": "modules-cross-cluster-optional", "name": "skip_unavailable", "required": true, "type": { @@ -111664,6 +111704,7 @@ } }, { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "name": "seeds", "required": true, "type": { @@ -111678,7 +111719,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L40" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L56" }, { "kind": "request", @@ -111688,7 +111729,7 @@ "body": { "kind": "no_body" }, - "description": "Get remote cluster information.\nGet all of the configured remote cluster information.\nThis API returns connection and endpoint information keyed by the configured remote cluster alias.", + "description": "Get remote cluster information.\n\nGet information about configured remote clusters.\nThe API returns connection and endpoint information keyed by the configured remote cluster alias.\n\n> info\n> This API returns information that reflects current state on the local cluster.\n> 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.\n> Elasticsearch does not spontaneously try to reconnect to a disconnected remote cluster.\n> To trigger a reconnection, attempt a cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster).", "inherits": { "type": { "name": "RequestBase", @@ -111701,7 +111742,7 @@ }, "path": [], "query": [], - "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L37" + "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L46" }, { "kind": "response", @@ -140843,7 +140884,7 @@ "body": { "kind": "no_body" }, - "description": "Resolve the cluster.\nResolve the specified index expressions to return information about each cluster, including the local cluster, if included.\nMultiple patterns and remote clusters are supported.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster in the index expression scope.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n**Advantages of using this endpoint before a cross-cluster search**\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.", + "description": "Resolve the cluster.\n\nResolve the specified index expressions to return information about each cluster, including the local \"querying\" cluster, if included.\nIf no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.\n\nThis endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.\n\nYou use the same index expression with this endpoint as you would for cross-cluster search.\nIndex and cluster exclusions are also supported with this endpoint.\n\nFor each cluster in the index expression, information is returned about:\n\n* Whether the querying (\"local\") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint.\n* Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`.\n* Whether there are any indices, aliases, or data streams on that cluster that match the index expression.\n* Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).\n* Cluster version information, including the Elasticsearch server version.\n\nFor example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`.\nEach cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`.\n\n## Note on backwards compatibility\nThe ability to query without an index expression was added in version 8.18, so when\nquerying remote clusters older than that, the local cluster will send the index\nexpression `dummy*` to those remote clusters. Thus, if an errors occur, you may see a reference\nto that index expression even though you didn't request it. If it causes a problem, you can\ninstead include an index expression like `*:*` to bypass the issue.\n\n## Advantages of using this endpoint before a cross-cluster search\n\nYou may want to exclude a cluster or index from a search when:\n\n* A remote cluster is not currently connected and is configured with `skip_unavailable=false`. Running a cross-cluster search under those conditions will cause the entire search to fail.\n* A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.\n* The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the \"error\" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.)\n* A remote cluster is an older version that does not support the feature you want to use in your search.\n\n## Test availability of remote clusters\n\nThe `remote/info` 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.\nThe remote cluster may be available, while the local cluster is not currently connected to it.\n\nYou can use the `_resolve/cluster` API to attempt to reconnect to remote clusters.\nFor example with `GET _resolve/cluster` or `GET _resolve/cluster/*:*`.\nThe `connected` field in the response will indicate whether it was successful.\nIf a connection was (re-)established, this will also cause the `remote/info` endpoint to now indicate a connected status.", "inherits": { "type": { "name": "RequestBase", @@ -140856,9 +140897,9 @@ }, "path": [ { - "description": "Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.", + "description": "A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve.\nResources on remote clusters can be specified using the ``:`` syntax.\nIndex and cluster exclusions (e.g., `-cluster1:*`) are also supported.\nIf no index expression is specified, information about all remote clusters configured on the local cluster\nis returned without doing any index matching", "name": "name", - "required": true, + "required": false, "type": { "kind": "instance_of", "type": { @@ -140870,9 +140911,10 @@ ], "query": [ { - "description": "If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.", + "description": "If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing\nor closed indices. This behavior applies even if the request targets other open indices. For example, a request\ntargeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", "name": "allow_no_indices", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -140882,7 +140924,7 @@ } }, { - "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.\nValid values are: `all`, `open`, `closed`, `hidden`, `none`.", + "description": "Type of index that wildcard patterns can match.\nIf the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.\nSupports comma-separated values, such as `open,hidden`.\nValid values are: `all`, `open`, `closed`, `hidden`, `none`.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", "name": "expand_wildcards", "required": false, "serverDefault": "open", @@ -140895,9 +140937,14 @@ } }, { - "description": "If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.", + "deprecation": { + "description": "", + "version": "7.16.0" + }, + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", "name": "ignore_throttled", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140907,9 +140954,10 @@ } }, { - "description": "If false, the request returns an error if it targets a missing or closed index. Defaults to false.", + "description": "If false, the request returns an error if it targets a missing or closed index.\nNOTE: This option is only supported when specifying an index expression. You will get an error if you specify index\noptions to the `_resolve/cluster` API endpoint that takes no index expression.", "name": "ignore_unavailable", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140917,9 +140965,21 @@ "namespace": "_builtins" } } + }, + { + "description": "The maximum time to wait for remote clusters to respond.\nIf a remote cluster does not respond within this timeout period, the API response\nwill show the cluster as not connected and include an error message that the\nrequest timed out.\n\nThe default timeout is unset and the query can take\nas long as the networking layer is configured to wait for remote clusters that are\nnot responding (typically 30 seconds).", + "name": "timeout", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "Duration", + "namespace": "_types" + } + } } ], - "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L23-L95" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L144" }, { "kind": "interface", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 95f88d6827..dda32baf36 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -9366,6 +9366,7 @@ export interface ClusterRemoteInfoClusterRemoteProxyInfo { server_name: string num_proxy_sockets_connected: integer max_proxy_socket_connections: integer + cluster_credentials?: string } export interface ClusterRemoteInfoClusterRemoteSniffInfo { @@ -12482,11 +12483,12 @@ export interface IndicesReloadSearchAnalyzersRequest extends RequestBase { export type IndicesReloadSearchAnalyzersResponse = IndicesReloadSearchAnalyzersReloadResult export interface IndicesResolveClusterRequest extends RequestBase { - name: Names + name?: Names allow_no_indices?: boolean expand_wildcards?: ExpandWildcards ignore_throttled?: boolean ignore_unavailable?: boolean + timeout?: Duration } export interface IndicesResolveClusterResolveClusterInfo { diff --git a/package-lock.json b/package-lock.json index fbecd1fbac..014101b1e1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -214,7 +214,6 @@ "version": "6.14.2", "resolved": "https://registry.npmjs.org/@stoplight/spectral-cli/-/spectral-cli-6.14.2.tgz", "integrity": "sha512-yn49Tkin/Zzjwt39CbQvj3NZVolvXrjO3OLNn+Yd+LhQE5C96QNsULuE4q98e7+WRcLu4gK+Z0l5CxYNtsoPtw==", - "license": "Apache-2.0", "dependencies": { "@stoplight/json": "~3.21.0", "@stoplight/path": "1.3.2", diff --git a/specification/_json_spec/indices.resolve_cluster.json b/specification/_json_spec/indices.resolve_cluster.json index fddbc513a0..0469c903fa 100644 --- a/specification/_json_spec/indices.resolve_cluster.json +++ b/specification/_json_spec/indices.resolve_cluster.json @@ -2,7 +2,7 @@ "indices.resolve_cluster": { "documentation": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-resolve-cluster-api.html", - "description": "Resolves the specified index expressions to return information about each cluster, including the local cluster, if included." + "description": "Resolves the specified index expressions to return information about each cluster. If no index expression is provided, this endpoint will return information about all the remote clusters that are configured on the local cluster." }, "stability": "stable", "visibility": "public", @@ -11,6 +11,10 @@ }, "url": { "paths": [ + { + "path": "/_resolve/cluster", + "methods": ["GET"] + }, { "path": "/_resolve/cluster/{name}", "methods": ["GET"], @@ -26,21 +30,25 @@ "params": { "ignore_unavailable": { "type": "boolean", - "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed)" + "description": "Whether specified concrete indices should be ignored when unavailable (missing or closed). Only allowed when providing an index expression." }, "ignore_throttled": { "type": "boolean", - "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled" + "description": "Whether specified concrete, expanded or aliased indices should be ignored when throttled. Only allowed when providing an index expression." }, "allow_no_indices": { "type": "boolean", - "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)" + "description": "Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified). Only allowed when providing an index expression." }, "expand_wildcards": { "type": "enum", "options": ["open", "closed", "hidden", "none", "all"], "default": "open", - "description": "Whether wildcard expressions should get expanded to open or closed indices (default: open)" + "description": "Whether wildcard expressions should get expanded to open or closed indices (default: open). Only allowed when providing an index expression." + }, + "timeout": { + "type": "time", + "description": "The maximum time to wait for remote clusters to respond" } } } diff --git a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts index 5452d497b4..bce879205d 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts @@ -21,11 +21,20 @@ import { RequestBase } from '@_types/Base' /** * Get remote cluster information. - * Get all of the configured remote cluster information. - * This API returns connection and endpoint information keyed by the configured remote cluster alias. + * + * Get information about configured remote clusters. + * The API returns connection and endpoint information keyed by the configured remote cluster alias. + * + * > info + * > 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 cross-cluster search, ES|QL cross-cluster search, or try the [resolve cluster endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-resolve-cluster). * @rest_spec_name cluster.remote_info * @availability stack since=6.1.0 stability=stable + * @cluster_privileges monitor * @doc_id cluster-remote-info + * @ext_doc_id modules-cross-cluster-search */ export interface Request extends RequestBase { urls: [ diff --git a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts index 583dc6c499..3afe6d055b 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts @@ -30,22 +30,54 @@ export class Response { export type ClusterRemoteInfo = ClusterRemoteSniffInfo | ClusterRemoteProxyInfo export class ClusterRemoteSniffInfo { + /** The connection mode for the remote cluster. */ mode: 'sniff' + /** + * If it is `true`, there is at least one open connection to the remote cluster. + * If it is `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. + */ connected: boolean + /** The maximum number of connections maintained for the remote cluster when sniff mode is configured. */ max_connections_per_cluster: integer + /** The number of connected nodes in the remote cluster when sniff mode is configured. */ num_nodes_connected: long + /** The initial connect timeout for remote cluster connections. */ initial_connect_timeout: Duration + /** + * If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster. + * @ext_doc_id modules-cross-cluster-optional + */ skip_unavailable: boolean + /** + * The initial seed transport addresses of the remote cluster when sniff mode is configured. + */ seeds: string[] } export class ClusterRemoteProxyInfo { + /** The connection mode for the remote cluster. */ mode: 'proxy' + /** + * If it is `true`, there is at least one open connection to the remote cluster. + * If it is `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. + */ connected: boolean + /** The initial connect timeout for remote cluster connections. */ initial_connect_timeout: Duration + /** + * If `true`, cross-cluster search skips the remote cluster when its nodes are unavailable during the search and ignores errors returned by the remote cluster. + * @ext_doc_id modules-cross-cluster-optional + */ skip_unavailable: boolean + /** The address for remote connections when proxy mode is configured. */ proxy_address: string server_name: string + /** The number of open socket connections to the remote cluster when proxy mode is configured. */ num_proxy_sockets_connected: integer + /** The maximum number of socket connections to the remote cluster when proxy mode is configured. */ max_proxy_socket_connections: integer + /** This field presents and has value of ::es_redacted:: only when the remote cluster is configured with the API key based model. Otherwise, the field is not present. */ + cluster_credentials?: string } diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 235b7a8321..8378bd67d7 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -19,11 +19,13 @@ import { RequestBase } from '@_types/Base' import { ExpandWildcards, Names } from '@_types/common' +import { Duration } from '@_types/Time' /** * Resolve the cluster. - * Resolve the specified index expressions to return information about each cluster, including the local cluster, if included. - * Multiple patterns and remote clusters are supported. + * + * Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. + * If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster. * * This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search. * @@ -32,7 +34,7 @@ import { ExpandWildcards, Names } from '@_types/common' * * For each cluster in the index expression, information is returned about: * - * * Whether the querying ("local") cluster is currently connected to each remote cluster in the index expression scope. + * * Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the `remote/info` endpoint. * * Whether each remote cluster is configured with `skip_unavailable` as `true` or `false`. * * Whether there are any indices, aliases, or data streams on that cluster that match the index expression. * * Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index). @@ -41,7 +43,14 @@ import { ExpandWildcards, Names } from '@_types/common' * For example, `GET /_resolve/cluster/my-index-*,cluster*:my-index-*` returns information about the local cluster and all remotely configured clusters that start with the alias `cluster*`. * Each cluster returns information about whether it has any indices, aliases or data streams that match `my-index-*`. * - * **Advantages of using this endpoint before a cross-cluster search** + * ## Note on backwards compatibility + * The ability to query without an index expression was added in version 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. + * + * ## Advantages of using this endpoint before a cross-cluster search * * You may want to exclude a cluster or index from a search when: * @@ -49,6 +58,16 @@ import { ExpandWildcards, Names } from '@_types/common' * * A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is `logs*,remote1:logs*` and the remote1 cluster has no indices, aliases or data streams that match `logs*`. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search. * * The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the `_resolve/cluster` response will be present. (This is also where security/permission errors will be shown.) * * A remote cluster is an older version that does not support the feature you want to use in your search. + * + * ## Test availability of remote clusters + * + * The `remote/info` 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` 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 `remote/info` endpoint to now indicate a connected status. * @rest_spec_name indices.resolve_cluster * @availability stack since=8.13.0 stability=stable * @doc_id indices-resolve-cluster-api @@ -56,6 +75,10 @@ import { ExpandWildcards, Names } from '@_types/common' */ export interface Request extends RequestBase { urls: [ + { + path: '/_resolve/cluster' + methods: ['GET'] + }, { path: '/_resolve/cluster/{name}' methods: ['GET'] @@ -63,33 +86,59 @@ export interface Request extends RequestBase { ] path_parts: { /** - * Comma-separated name(s) or index pattern(s) of the indices, aliases, and data streams to resolve. + * A comma-separated list of names or index patterns for the indices, aliases, and data streams to resolve. * Resources on remote clusters can be specified using the ``:`` syntax. + * Index and cluster exclusions (e.g., `-cluster1:*`) are also supported. + * If no index expression is specified, information about all remote clusters configured on the local cluster + * is returned without doing any index matching */ - name: Names + name?: Names } query_parameters: { /** - * If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing + * If false, the request returns an error if any wildcard expression, index alias, or `_all` value targets only missing * or closed indices. This behavior applies even if the request targets other open indices. For example, a request - * targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar. + * targeting `foo*,bar*` returns an error if an index starts with `foo` but no index starts with `bar`. + * NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index + * options to the `_resolve/cluster` API endpoint that takes no index expression. + * @server_default true */ - allow_no_indices?: boolean // default: true + allow_no_indices?: boolean /** * Type of index that wildcard patterns can match. * If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. * Supports comma-separated values, such as `open,hidden`. * Valid values are: `all`, `open`, `closed`, `hidden`, `none`. + * NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index + * options to the `_resolve/cluster` API endpoint that takes no index expression. * @server_default open */ expand_wildcards?: ExpandWildcards /** - * If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false. + * If true, concrete, expanded, or aliased indices are ignored when frozen. + * NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index + * options to the `_resolve/cluster` API endpoint that takes no index expression. + * @server_default false + * @deprecated 7.16.0 + */ + ignore_throttled?: boolean + /** + * If false, the request returns an error if it targets a missing or closed index. + * NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index + * options to the `_resolve/cluster` API endpoint that takes no index expression. + * @server_default false */ - ignore_throttled?: boolean // default: false + ignore_unavailable?: boolean /** - * If false, the request returns an error if it targets a missing or closed index. Defaults to false. + * The maximum time to wait 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). */ - ignore_unavailable?: boolean // default: false + timeout?: Duration } } diff --git a/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml b/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml index 2315196289..3ed5da8424 100644 --- a/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml +++ b/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml @@ -1,25 +1,47 @@ summary: Identify search problems # indices/resolve-cluster.asciidoc:213 description: > - A successful response from `GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false`. + A successful response from `GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false&timeout=5s`. This type of request can be used to identify potential problems with your cross-cluster search. + Note also that a `timeout` of 5 seconds is sent, which sets the maximum time the query will wait for remote clusters to respond. The local cluster has no index called `not_present`. Searching with `ignore_unavailable=false` would return a "no such index" error. The `cluster_one` remote cluster has no indices that match the pattern `my-index*`. There may be no indices that match the pattern or the index could be closed. The `cluster_two` remote cluster is not connected (the attempt to connect 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. + 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. 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, so you may want to exclude it from your cross-cluster search. # type: response # response_code: 200 -value: - "{\n \"(local)\": {\n \"connected\": true,\n \"skip_unavailable\": false,\n\ - \ \"error\": \"no such index [not_present]\"\n },\n \"cluster_one\": {\n \ - \ \"connected\": true,\n \"skip_unavailable\": true,\n \"matching_indices\"\ - : false,\n \"version\": {\n \"number\": \"8.13.0\",\n \"build_flavor\"\ - : \"default\",\n \"minimum_wire_compatibility_version\": \"7.17.0\",\n \ - \ \"minimum_index_compatibility_version\": \"7.0.0\"\n }\n },\n \"cluster_two\"\ - : {\n \"connected\": false,\n \"skip_unavailable\": false,\n \"matching_indices\"\ - : true,\n \"version\": {\n \"number\": \"8.13.0\",\n \"build_flavor\"\ - : \"default\",\n \"minimum_wire_compatibility_version\": \"7.17.0\",\n \ - \ \"minimum_index_compatibility_version\": \"7.0.0\"\n }\n },\n \"oldcluster\"\ - : {\n \"connected\": true,\n \"skip_unavailable\": false,\n \"matching_indices\"\ - : true\n }\n}" +value: |- + { + "(local)": { + "connected": true, + "skip_unavailable": false, + "error": "no such index [not_present]" + }, + "cluster_one": { + "connected": true, + "skip_unavailable": true, + "matching_indices": false, + "version": { + "number": "8.13.0", + "build_flavor": "default", + "minimum_wire_compatibility_version": "7.17.0", + "minimum_index_compatibility_version": "7.0.0" + } + }, + "cluster_two": { + "connected": false, + "skip_unavailable": false + }, + "cluster_three": { + "connected": false, + "skip_unavailable": false, + "error": "Request timed out before receiving a response from the remote cluster" + }, + "oldcluster": { + "connected": true, + "skip_unavailable": false, + "matching_indices": true + } + }