From e2556348823a12a6aba6a732b41f947dfa7c6e92 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 14:39:58 -0500 Subject: [PATCH 1/9] Update API specs for _remote/info and _resolve/cluster --- output/openapi/elasticsearch-openapi.json | 35 +++++++++--- output/schema/schema.json | 56 +++++++++++++++---- package-lock.json | 1 - specification/_doc_ids/table.csv | 1 + .../remote_info/ClusterRemoteInfoRequest.ts | 13 ++++- .../remote_info/ClusterRemoteInfoResponse.ts | 30 ++++++++++ .../resolve_cluster/ResolveClusterRequest.ts | 33 ++++++++--- 7 files changed, 138 insertions(+), 31 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 7d5dc3a2ad..7557f6b314 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": { @@ -15141,13 +15144,13 @@ "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## 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.", + "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.", "required": true, "deprecated": false, "schema": { @@ -15158,7 +15161,7 @@ { "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.", + "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" @@ -15178,8 +15181,8 @@ { "in": "query", "name": "ignore_throttled", - "description": "If true, concrete, expanded or aliased indices are ignored when frozen. Defaults to false.", - "deprecated": false, + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.", + "deprecated": true, "schema": { "type": "boolean" }, @@ -15188,7 +15191,7 @@ { "in": "query", "name": "ignore_unavailable", - "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.", "deprecated": false, "schema": { "type": "boolean" @@ -66034,27 +66037,36 @@ "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": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" + }, + "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,30 +66087,39 @@ "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": { + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" + }, + "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" } }, diff --git a/output/schema/schema.json b/output/schema/schema.json index 716ca0d374..acc31b3f00 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/{branch}/cluster-remote-info.html", + "extDocId": "modules-cross-cluster-search", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/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## 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/{branch}/indices-resolve-cluster-api.html", "name": "indices.resolve_cluster", @@ -111506,6 +111513,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111514,6 +111522,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 +111534,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111536,6 +111546,9 @@ } }, { + "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", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters", "name": "skip_unavailable", "required": true, "type": { @@ -111547,6 +111560,7 @@ } }, { + "description": "The address for remote connections when proxy mode is configured.", "name": "proxy_address", "required": true, "type": { @@ -111569,6 +111583,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 +111595,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": { @@ -111591,7 +111607,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L42-L51" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L58-L81" }, { "kind": "interface", @@ -111601,6 +111617,7 @@ }, "properties": [ { + "description": "The connection mode for the remote cluster.", "name": "mode", "required": true, "type": { @@ -111609,6 +111626,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 +111638,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 +111650,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 +111662,7 @@ } }, { + "description": "The initial connect timeout for remote cluster connections.", "name": "initial_connect_timeout", "required": true, "type": { @@ -111653,6 +111674,9 @@ } }, { + "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", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters", "name": "skip_unavailable", "required": true, "type": { @@ -111664,6 +111688,7 @@ } }, { + "description": "The initial seed transport addresses of the remote cluster when sniff mode is configured.", "name": "seeds", "required": true, "type": { @@ -111678,7 +111703,7 @@ } } ], - "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L40" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L32-L56" }, { "kind": "request", @@ -111688,7 +111713,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 +111726,7 @@ }, "path": [], "query": [], - "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L37" + "specLocation": "cluster/remote_info/ClusterRemoteInfoRequest.ts#L22-L46" }, { "kind": "response", @@ -140843,7 +140868,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## 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,7 +140881,7 @@ }, "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.", "name": "name", "required": true, "type": { @@ -140870,9 +140895,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`.", "name": "allow_no_indices", "required": false, + "serverDefault": true, "type": { "kind": "instance_of", "type": { @@ -140895,9 +140921,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.", "name": "ignore_throttled", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140907,9 +140938,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.", "name": "ignore_unavailable", "required": false, + "serverDefault": false, "type": { "kind": "instance_of", "type": { @@ -140919,7 +140951,7 @@ } } ], - "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L23-L95" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L23-L110" }, { "kind": "interface", 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/_doc_ids/table.csv b/specification/_doc_ids/table.csv index ab78c8a79b..428f3aef8b 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -413,6 +413,7 @@ ml-update-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{bran ml-upgrade-job-model-snapshot,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/ml-upgrade-job-model-snapshot.html modules-cluster,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cluster.html modules-cross-cluster-search,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html +modules-cross-cluster-optional,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-cross-cluster-search.html#skip-unavailable-clusters modules-discovery-hosts-providers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-discovery-hosts-providers.html modules-fielddata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-fielddata.html modules-gateway-dangling-indices,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-gateway-dangling-indices.html 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..74d4e3510e 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts @@ -30,22 +30,52 @@ 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 } diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 235b7a8321..e4426e3c53 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -22,8 +22,9 @@ import { ExpandWildcards, Names } from '@_types/common' /** * 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 +33,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 +42,7 @@ 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** + * ## 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 +50,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 @@ -63,16 +74,17 @@ 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. */ 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`. + * @server_default true */ allow_no_indices?: boolean // default: true /** @@ -84,11 +96,14 @@ export interface Request extends RequestBase { */ 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. + * @server_default false + * @deprecated 7.16.0 */ ignore_throttled?: boolean // default: false /** - * If false, the request returns an error if it targets a missing or closed index. Defaults to false. + * If false, the request returns an error if it targets a missing or closed index. + * @server_default false */ ignore_unavailable?: boolean // default: false } From ece1d168261a9372323acf07b02e9fb2714a9a09 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 16:48:08 -0500 Subject: [PATCH 2/9] Added info on timeout param and the no index expr endpoint --- output/schema/schema.json | 36 +++++++++---- output/schema/validation-errors.json | 8 +++ output/typescript/types.ts | 3 +- .../resolve_cluster/ResolveClusterRequest.ts | 36 ++++++++++++- .../ResolveClusterResponseExample2.yaml | 50 +++++++++++++------ 5 files changed, 108 insertions(+), 25 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index acc31b3f00..3547ecc853 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -8444,7 +8444,7 @@ "stability": "stable" } }, - "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## 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.", + "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/{branch}/indices-resolve-cluster-api.html", "name": "indices.resolve_cluster", @@ -8466,6 +8466,12 @@ "application/json" ], "urls": [ + { + "methods": [ + "GET" + ], + "path": "/_resolve/cluster" + }, { "methods": [ "GET" @@ -140868,7 +140874,7 @@ "body": { "kind": "no_body" }, - "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## 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.", + "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", @@ -140881,9 +140887,9 @@ }, "path": [ { - "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.", + "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": { @@ -140895,7 +140901,7 @@ ], "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: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", "name": "allow_no_indices", "required": false, "serverDefault": true, @@ -140908,7 +140914,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: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", "name": "expand_wildcards", "required": false, "serverDefault": "open", @@ -140925,7 +140931,7 @@ "description": "", "version": "7.16.0" }, - "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.", + "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", "name": "ignore_throttled", "required": false, "serverDefault": false, @@ -140938,7 +140944,7 @@ } }, { - "description": "If false, the request returns an error if it targets a missing or closed index.", + "description": "If false, the request returns an error if it targets a missing or closed index.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", "name": "ignore_unavailable", "required": false, "serverDefault": false, @@ -140949,9 +140955,21 @@ "namespace": "_builtins" } } + }, + { + "description": "Specify a max wait time 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-L110" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L144" }, { "kind": "interface", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 7b481fb259..c4c9c6d6fa 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -236,6 +236,14 @@ ], "response": [] }, + "indices.resolve_cluster": { + "request": [ + "Request: different number of urls in the json spec", + "Request: path parameter 'name' is required in the json spec", + "Request: query parameter 'timeout' does not exist in the json spec" + ], + "response": [] + }, "indices.rollover": { "request": [ "Request: missing json spec query parameter 'lazy'" diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 18d968c855..1537b89e9f 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -12482,11 +12482,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/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index e4426e3c53..c8b1d0868d 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -18,6 +18,7 @@ */ import { RequestBase } from '@_types/Base' +import { Duration } from '@_types/Time' import { ExpandWildcards, Names } from '@_types/common' /** @@ -42,6 +43,13 @@ 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-*`. * + * ## 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: @@ -67,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'] @@ -76,14 +88,19 @@ export interface Request extends RequestBase { /** * 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 * 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`. + * Note: 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 @@ -92,19 +109,36 @@ export interface Request extends RequestBase { * 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: 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. + * Note: 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 // default: false /** * If false, the request returns an error if it targets a missing or closed index. + * Note: 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_unavailable?: boolean // default: false + /** + * 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). + */ + timeout?: Duration // default: unset } } diff --git a/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml b/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml index 2315196289..09c48a5f39 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" (4) + }, + "oldcluster": { + "connected": true, + "skip_unavailable": false, + "matching_indices": true + } + } From 679718a6a9c59fd0f72cd3810b07c4865d867745 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 16:59:21 -0500 Subject: [PATCH 3/9] Added cluster_credentials to the _remote/info response --- output/schema/schema.json | 16 ++++++++++++++-- output/typescript/types.ts | 1 + .../remote_info/ClusterRemoteInfoResponse.ts | 2 ++ 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index 3547ecc853..e91b5a5eea 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -111611,9 +111611,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#L58-L81" + "specLocation": "cluster/remote_info/ClusterRemoteInfoResponse.ts#L58-L83" }, { "kind": "interface", @@ -140957,7 +140969,7 @@ } }, { - "description": "Specify a max wait time 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).", + "description": "Specify a max wait time 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": { diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 1537b89e9f..5861614dba 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 { diff --git a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts index 74d4e3510e..3afe6d055b 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoResponse.ts @@ -78,4 +78,6 @@ export class ClusterRemoteProxyInfo { 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 } From 289fcf42c8ab4d4942f25e1269e27a29addb3c76 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 17:05:45 -0500 Subject: [PATCH 4/9] Removed extra number pointer from ResolveClusterResponseExample2.yaml JSON --- .../examples/200_response/ResolveClusterResponseExample2.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml b/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml index 09c48a5f39..3ed5da8424 100644 --- a/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml +++ b/specification/indices/resolve_cluster/examples/200_response/ResolveClusterResponseExample2.yaml @@ -37,7 +37,7 @@ value: |- "cluster_three": { "connected": false, "skip_unavailable": false, - "error": "Request timed out before receiving a response from the remote cluster" (4) + "error": "Request timed out before receiving a response from the remote cluster" }, "oldcluster": { "connected": true, From 46e78fb2d237a9f86a58f84951029cbdb27dc3d4 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Wed, 29 Jan 2025 17:12:13 -0500 Subject: [PATCH 5/9] Fix from running npm run format:fix --prefix compiler --- specification/indices/resolve_cluster/ResolveClusterRequest.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index c8b1d0868d..9e93a4e379 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -18,8 +18,8 @@ */ import { RequestBase } from '@_types/Base' -import { Duration } from '@_types/Time' import { ExpandWildcards, Names } from '@_types/common' +import { Duration } from '@_types/Time' /** * Resolve the cluster. From 7526dd1597e1d991dc2fd5c12fa9fdd9a7c54717 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Thu, 30 Jan 2025 10:26:00 -0500 Subject: [PATCH 6/9] Addressed PR feedback changes and also updated indices.resolve_cluster.json to match the new spec --- .../_json_spec/indices.resolve_cluster.json | 18 +++++++++++----- .../resolve_cluster/ResolveClusterRequest.ts | 21 +++++++++---------- 2 files changed, 23 insertions(+), 16 deletions(-) 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/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 9e93a4e379..6b1c6e1025 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -99,8 +99,8 @@ export interface Request extends RequestBase { * 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`. - * Note: 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. + * 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 @@ -109,28 +109,28 @@ export interface Request extends RequestBase { * 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: 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. + * 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. - * Note: 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. + * 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 // default: false /** * If false, the request returns an error if it targets a missing or closed index. - * Note: 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. + * 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_unavailable?: boolean // default: false /** - * Specify a max wait time for remote clusters to respond. + * 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. @@ -139,6 +139,5 @@ export interface Request extends RequestBase { * as long as the networking layer is configured to wait for remote clusters that are * not responding (typically 30 seconds). */ - timeout?: Duration // default: unset - } + timeout?: Duration } From 58081d1b0357593ee529c08a7335497f9a94d2e6 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Thu, 30 Jan 2025 10:28:58 -0500 Subject: [PATCH 7/9] Ran make generate --- output/schema/schema.json | 12 ++++++------ output/schema/validation-errors.json | 8 -------- 2 files changed, 6 insertions(+), 14 deletions(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index e91b5a5eea..ec392c4db1 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -140913,7 +140913,7 @@ ], "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`.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", + "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, @@ -140926,7 +140926,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`.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", + "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", @@ -140943,7 +140943,7 @@ "description": "", "version": "7.16.0" }, - "description": "If true, concrete, expanded, or aliased indices are ignored when frozen.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", + "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, @@ -140956,7 +140956,7 @@ } }, { - "description": "If false, the request returns an error if it targets a missing or closed index.\nNote: only supported when specifying an index expression. You will get an error if you specify index options to the\n_resolve/cluster API endpoint that takes no index expression.", + "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, @@ -140969,7 +140969,7 @@ } }, { - "description": "Specify a max wait time 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).", + "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": { @@ -140981,7 +140981,7 @@ } } ], - "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L144" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L143" }, { "kind": "interface", diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index c4c9c6d6fa..7b481fb259 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -236,14 +236,6 @@ ], "response": [] }, - "indices.resolve_cluster": { - "request": [ - "Request: different number of urls in the json spec", - "Request: path parameter 'name' is required in the json spec", - "Request: query parameter 'timeout' does not exist in the json spec" - ], - "response": [] - }, "indices.rollover": { "request": [ "Request: missing json spec query parameter 'lazy'" From 4fb20a36504e014b11f267fc7a6fc8eb49198401 Mon Sep 17 00:00:00 2001 From: Michael Peterson Date: Thu, 30 Jan 2025 11:00:32 -0500 Subject: [PATCH 8/9] Fixed syntax error in ResolveClusterRequest.ts --- output/schema/schema.json | 2 +- specification/indices/resolve_cluster/ResolveClusterRequest.ts | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/output/schema/schema.json b/output/schema/schema.json index ec392c4db1..18146324ce 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -140981,7 +140981,7 @@ } } ], - "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L143" + "specLocation": "indices/resolve_cluster/ResolveClusterRequest.ts#L24-L144" }, { "kind": "interface", diff --git a/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 6b1c6e1025..39b80b9ff2 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -140,4 +140,5 @@ export interface Request extends RequestBase { * not responding (typically 30 seconds). */ timeout?: Duration + } } From bad5e89be83a932ef2fc71b970105c09bc28457d Mon Sep 17 00:00:00 2001 From: lcawl Date: Thu, 30 Jan 2025 08:57:43 -0800 Subject: [PATCH 9/9] Remove extra comments --- output/openapi/elasticsearch-openapi.json | 182 ++++++++++++------ output/schema/schema-serverless.json | 32 ++- .../resolve_cluster/ResolveClusterRequest.ts | 6 +- 3 files changed, 155 insertions(+), 65 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index ba2a6938eb..fdf63d3274 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -15138,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 \"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## 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.", + "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": "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.", - "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.", - "deprecated": true, - "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.", - "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" @@ -66059,9 +66049,6 @@ "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { - "externalDocs": { - "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" - }, "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" }, @@ -66101,9 +66088,6 @@ "$ref": "#/components/schemas/_types:Duration" }, "skip_unavailable": { - "externalDocs": { - "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-cross-cluster-search.html#skip-unavailable-clusters" - }, "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" }, @@ -66121,6 +66105,10 @@ "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": [ @@ -95439,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": { @@ -102563,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/specification/indices/resolve_cluster/ResolveClusterRequest.ts b/specification/indices/resolve_cluster/ResolveClusterRequest.ts index 39b80b9ff2..8378bd67d7 100644 --- a/specification/indices/resolve_cluster/ResolveClusterRequest.ts +++ b/specification/indices/resolve_cluster/ResolveClusterRequest.ts @@ -103,7 +103,7 @@ export interface Request extends RequestBase { * 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. @@ -121,14 +121,14 @@ export interface Request extends RequestBase { * @server_default false * @deprecated 7.16.0 */ - ignore_throttled?: boolean // default: false + 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_unavailable?: boolean // default: false + ignore_unavailable?: boolean /** * The maximum time to wait for remote clusters to respond. * If a remote cluster does not respond within this timeout period, the API response