diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index ab0d99f3ff..90ab9893f6 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -3113,7 +3113,8 @@ "tags": [ "cluster" ], - "summary": "Provides explanations for shard allocations in the cluster", + "summary": "Explain the shard allocations", + "description": "Get explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.", "operationId": "cluster-allocation-explain", "parameters": [ { @@ -3137,7 +3138,8 @@ "tags": [ "cluster" ], - "summary": "Provides explanations for shard allocations in the cluster", + "summary": "Explain the shard allocations", + "description": "Get explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.", "operationId": "cluster-allocation-explain-1", "parameters": [ { @@ -3356,7 +3358,11 @@ "tags": [ "cluster" ], - "summary": "Updates the cluster voting config exclusions by node ids or node names", + "summary": "Update voting configuration exclusions", + "description": "Update the cluster voting config exclusions by node IDs or node names.\nBy default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks.\nIf you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually.\nThe API adds an entry for each specified node to the cluster’s voting configuration exclusions list.\nIt then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.\n\nClusters should have no voting configuration exclusions in normal operation.\nOnce the excluded nodes have stopped, clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`.\nThis API waits for the nodes to be fully removed from the cluster before it returns.\nIf your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.\n\nA response to `POST /_cluster/voting_config_exclusions` with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.\nIf the call to `POST /_cluster/voting_config_exclusions` fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration.\nIn that case, you may safely retry the call.\n\nNOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period.\nThey are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/add-elasticsearch-nodes.html" + }, "operationId": "cluster-post-voting-config-exclusions", "parameters": [ { @@ -3404,7 +3410,11 @@ "tags": [ "cluster" ], - "summary": "Clears cluster voting config exclusions", + "summary": "Clear cluster voting config exclusions", + "description": "Remove master-eligible nodes from the voting configuration exclusion list.", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/add-elasticsearch-nodes.html" + }, "operationId": "cluster-delete-voting-config-exclusions", "parameters": [ { @@ -3464,7 +3474,7 @@ "tags": [ "cluster" ], - "summary": "Returns cluster-wide settings", + "summary": "Get cluster-wide settings", "description": "By default, it returns only settings that have been explicitly defined.", "operationId": "cluster-get-settings", "parameters": [ @@ -3550,7 +3560,8 @@ "tags": [ "cluster" ], - "summary": "Updates the cluster settings", + "summary": "Update the cluster settings", + "description": "Configure and update dynamic settings on a running cluster.\nYou can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.\n\nUpdates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.\nYou can also reset transient or persistent settings by assigning them a null value.\n\nIf you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.\nFor example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.\nHowever, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.\n\nTIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.\nIf you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.\nOnly use `elasticsearch.yml` for static cluster settings and node settings.\nThe API doesn’t require a restart and ensures a setting’s value is the same on all nodes.\n\nWARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.\nIf a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.", "operationId": "cluster-put-settings", "parameters": [ { @@ -3649,8 +3660,8 @@ "tags": [ "cluster" ], - "summary": "The cluster health API returns a simple status on the health of the cluster", - "description": "You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.\nThe cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster, yellow means that the primary shard is allocated but replicas are not, and green means that all shards are allocated. The index level status is controlled by the worst shard status. The cluster status is controlled by the worst index status.", + "summary": "Get the cluster health status", + "description": "You can also use the API to get the health status of only specified data streams and indices.\nFor data streams, the API retrieves the health status of the stream’s backing indices.\n\nThe cluster health status is: green, yellow or red.\nOn the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.\nThe index level status is controlled by the worst shard status.\n\nOne of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.\nThe cluster status is controlled by the worst index status.", "operationId": "cluster-health", "parameters": [ { @@ -3700,8 +3711,8 @@ "tags": [ "cluster" ], - "summary": "The cluster health API returns a simple status on the health of the cluster", - "description": "You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.\nThe cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster, yellow means that the primary shard is allocated but replicas are not, and green means that all shards are allocated. The index level status is controlled by the worst shard status. The cluster status is controlled by the worst index status.", + "summary": "Get the cluster health status", + "description": "You can also use the API to get the health status of only specified data streams and indices.\nFor data streams, the API retrieves the health status of the stream’s backing indices.\n\nThe cluster health status is: green, yellow or red.\nOn the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.\nThe index level status is controlled by the worst shard status.\n\nOne of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.\nThe cluster status is controlled by the worst index status.", "operationId": "cluster-health-1", "parameters": [ { @@ -3813,8 +3824,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet been executed", - "description": "NOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the Task Management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", + "summary": "Get the pending cluster tasks", + "description": "Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.\n\nNOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", "operationId": "cluster-pending-tasks", "parameters": [ { @@ -3868,8 +3879,8 @@ "tags": [ "cluster" ], - "summary": "The cluster remote info API allows you to retrieve all of the configured\n", - "description": "remote cluster information. It returns connection and endpoint information\nkeyed by the configured remote cluster alias.", + "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.", "operationId": "cluster-remote-info", "responses": { "200": { @@ -3894,13 +3905,14 @@ "tags": [ "cluster" ], - "summary": "Allows to manually change the allocation of individual shards in the cluster", + "summary": "Reroute the cluster", + "description": "Manually change the allocation of individual shards in the cluster.\nFor example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.\n\nIt is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as `cluster.routing.rebalance.enable`) in order to remain in a balanced state.\nFor example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.\n\nThe cluster can be set to disable allocations using the `cluster.routing.allocation.enable` setting.\nIf allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.\n\nThe cluster will attempt to allocate a shard a maximum of `index.allocation.max_retries` times in a row (defaults to `5`), before giving up and leaving the shard unallocated.\nThis scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.\n\nOnce the problem has been corrected, allocation can be manually retried by calling the reroute API with the `?retry_failed` URI query parameter, which will attempt a single retry round for these shards.", "operationId": "cluster-reroute", "parameters": [ { "in": "query", "name": "dry_run", - "description": "If true, then the request simulates the operation only and returns the resulting state.", + "description": "If true, then the request simulates the operation.\nIt will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.", "deprecated": false, "schema": { "type": "boolean" @@ -3910,7 +3922,7 @@ { "in": "query", "name": "explain", - "description": "If true, then the response contains an explanation of why the commands can or cannot be executed.", + "description": "If true, then the response contains an explanation of why the commands can or cannot run.", "deprecated": false, "schema": { "type": "boolean" @@ -4014,7 +4026,8 @@ "tags": [ "cluster" ], - "summary": "Returns a comprehensive information about the state of the cluster", + "summary": "Get the cluster state", + "description": "Get comprehensive information about the state of the cluster.\n\nThe cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.\n\nThe elected master node ensures that every node in the cluster has a copy of the same cluster state.\nThis API lets you retrieve a representation of this internal state for debugging or diagnostic purposes.\nYou may need to consult the Elasticsearch source code to determine the precise meaning of the response.\n\nBy default the API will route requests to the elected master node since this node is the authoritative source of cluster states.\nYou can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter.\n\nElasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data.\nIf you use this API repeatedly, your cluster may become unstable.\n\nWARNING: The response is a representation of an internal data structure.\nIts format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version.\nDo not query this API using external monitoring tools.\nInstead, obtain the information you require using other more stable cluster APIs.", "operationId": "cluster-state", "parameters": [ { @@ -4055,7 +4068,8 @@ "tags": [ "cluster" ], - "summary": "Returns a comprehensive information about the state of the cluster", + "summary": "Get the cluster state", + "description": "Get comprehensive information about the state of the cluster.\n\nThe cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.\n\nThe elected master node ensures that every node in the cluster has a copy of the same cluster state.\nThis API lets you retrieve a representation of this internal state for debugging or diagnostic purposes.\nYou may need to consult the Elasticsearch source code to determine the precise meaning of the response.\n\nBy default the API will route requests to the elected master node since this node is the authoritative source of cluster states.\nYou can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter.\n\nElasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data.\nIf you use this API repeatedly, your cluster may become unstable.\n\nWARNING: The response is a representation of an internal data structure.\nIts format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version.\nDo not query this API using external monitoring tools.\nInstead, obtain the information you require using other more stable cluster APIs.", "operationId": "cluster-state-1", "parameters": [ { @@ -4099,7 +4113,8 @@ "tags": [ "cluster" ], - "summary": "Returns a comprehensive information about the state of the cluster", + "summary": "Get the cluster state", + "description": "Get comprehensive information about the state of the cluster.\n\nThe cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.\n\nThe elected master node ensures that every node in the cluster has a copy of the same cluster state.\nThis API lets you retrieve a representation of this internal state for debugging or diagnostic purposes.\nYou may need to consult the Elasticsearch source code to determine the precise meaning of the response.\n\nBy default the API will route requests to the elected master node since this node is the authoritative source of cluster states.\nYou can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter.\n\nElasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data.\nIf you use this API repeatedly, your cluster may become unstable.\n\nWARNING: The response is a representation of an internal data structure.\nIts format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version.\nDo not query this API using external monitoring tools.\nInstead, obtain the information you require using other more stable cluster APIs.", "operationId": "cluster-state-2", "parameters": [ { @@ -4146,8 +4161,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster statistics", - "description": "It returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", + "summary": "Get cluster statistics", + "description": "Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", "operationId": "cluster-stats", "parameters": [ { @@ -4170,8 +4185,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster statistics", - "description": "It returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", + "summary": "Get cluster statistics", + "description": "Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", "operationId": "cluster-stats-1", "parameters": [ { @@ -9358,7 +9373,8 @@ "tags": [ "health_report" ], - "summary": "Returns the health of the cluster", + "summary": "Get the cluster health", + "description": "Get a report with the health status of an Elasticsearch cluster.\nThe report contains a list of indicators that compose Elasticsearch functionality.\n\nEach indicator has a health status of: green, unknown, yellow or red.\nThe indicator will provide an explanation and metadata describing the reason for its current health status.\n\nThe cluster’s status is controlled by the worst indicator status.\n\nIn the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue.\nEach impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.\n\nSome health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system.\nThe root cause and remediation steps are encapsulated in a diagnosis.\nA diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.\n\nNOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently.\nWhen setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.", "operationId": "health-report", "parameters": [ { @@ -9384,7 +9400,8 @@ "tags": [ "health_report" ], - "summary": "Returns the health of the cluster", + "summary": "Get the cluster health", + "description": "Get a report with the health status of an Elasticsearch cluster.\nThe report contains a list of indicators that compose Elasticsearch functionality.\n\nEach indicator has a health status of: green, unknown, yellow or red.\nThe indicator will provide an explanation and metadata describing the reason for its current health status.\n\nThe cluster’s status is controlled by the worst indicator status.\n\nIn the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue.\nEach impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.\n\nSome health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system.\nThe root cause and remediation steps are encapsulated in a diagnosis.\nA diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.\n\nNOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently.\nWhen setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.", "operationId": "health-report-1", "parameters": [ { @@ -15089,7 +15106,7 @@ "cluster" ], "summary": "Ping the cluster", - "description": "Returns whether the cluster is running.", + "description": "Get information about whether the cluster is running.", "operationId": "ping", "responses": { "200": { @@ -23153,7 +23170,8 @@ "tags": [ "cluster" ], - "summary": "You can use this API to clear the archived repositories metering information in the cluster", + "summary": "Clear the archived repositories metering", + "description": "Clear the archived repositories metering information in the cluster.", "operationId": "nodes-clear-repositories-metering-archive", "parameters": [ { @@ -23199,8 +23217,8 @@ "tags": [ "cluster" ], - "summary": "You can use the cluster repositories metering API to retrieve repositories metering information in a cluster", - "description": "This API exposes monotonically non-decreasing counters and it’s expected that clients would durably store the\ninformation needed to compute aggregations over a period of time. Additionally, the information exposed by this\nAPI is volatile, meaning that it won’t be present after node restarts.", + "summary": "Get cluster repositories metering", + "description": "Get repositories metering information for a cluster.\nThis API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time.\nAdditionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.", "operationId": "nodes-get-repositories-metering-info", "parameters": [ { @@ -23235,8 +23253,8 @@ "tags": [ "cluster" ], - "summary": "This API yields a breakdown of the hot threads on each selected node in the cluster", - "description": "The output is plain text with a breakdown of each node’s top hot threads.", + "summary": "Get the hot threads for nodes", + "description": "Get a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of the top hot threads for each node.", "operationId": "nodes-hot-threads", "parameters": [ { @@ -23276,8 +23294,8 @@ "tags": [ "cluster" ], - "summary": "This API yields a breakdown of the hot threads on each selected node in the cluster", - "description": "The output is plain text with a breakdown of each node’s top hot threads.", + "summary": "Get the hot threads for nodes", + "description": "Get a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of the top hot threads for each node.", "operationId": "nodes-hot-threads-1", "parameters": [ { @@ -23320,7 +23338,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes information", + "summary": "Get node information", + "description": "By default, the API returns all attributes and core settings for cluster nodes.", "operationId": "nodes-info", "parameters": [ { @@ -23346,7 +23365,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes information", + "summary": "Get node information", + "description": "By default, the API returns all attributes and core settings for cluster nodes.", "operationId": "nodes-info-1", "parameters": [ { @@ -23375,7 +23395,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes information", + "summary": "Get node information", + "description": "By default, the API returns all attributes and core settings for cluster nodes.", "operationId": "nodes-info-2", "parameters": [ { @@ -23404,7 +23425,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes information", + "summary": "Get node information", + "description": "By default, the API returns all attributes and core settings for cluster nodes.", "operationId": "nodes-info-3", "parameters": [ { @@ -23436,7 +23458,8 @@ "tags": [ "cluster" ], - "summary": "Reloads the keystore on nodes in the cluster", + "summary": "Reload the keystore on nodes in the cluster", + "description": "Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable.\nThat is, you can change them on disk and reload them without restarting any nodes in the cluster.\nWhen you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.\n\nWhen the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings.\nReloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted.\nAlternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.", "operationId": "nodes-reload-secure-settings", "parameters": [ { @@ -23459,7 +23482,8 @@ "tags": [ "cluster" ], - "summary": "Reloads the keystore on nodes in the cluster", + "summary": "Reload the keystore on nodes in the cluster", + "description": "Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable.\nThat is, you can change them on disk and reload them without restarting any nodes in the cluster.\nWhen you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.\n\nWhen the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings.\nReloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted.\nAlternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.", "operationId": "nodes-reload-secure-settings-1", "parameters": [ { @@ -23485,7 +23509,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats", "parameters": [ { @@ -23531,7 +23556,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats-1", "parameters": [ { @@ -23580,7 +23606,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats-2", "parameters": [ { @@ -23629,7 +23656,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats-3", "parameters": [ { @@ -23681,7 +23709,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats-4", "parameters": [ { @@ -23733,7 +23762,8 @@ "tags": [ "cluster" ], - "summary": "Returns cluster nodes statistics", + "summary": "Get node statistics", + "description": "Get statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "operationId": "nodes-stats-5", "parameters": [ { @@ -23788,7 +23818,7 @@ "tags": [ "cluster" ], - "summary": "Returns information on the usage of features", + "summary": "Get feature usage information", "operationId": "nodes-usage", "parameters": [ { @@ -23808,7 +23838,7 @@ "tags": [ "cluster" ], - "summary": "Returns information on the usage of features", + "summary": "Get feature usage information", "operationId": "nodes-usage-1", "parameters": [ { @@ -23831,7 +23861,7 @@ "tags": [ "cluster" ], - "summary": "Returns information on the usage of features", + "summary": "Get feature usage information", "operationId": "nodes-usage-2", "parameters": [ { @@ -23854,7 +23884,7 @@ "tags": [ "cluster" ], - "summary": "Returns information on the usage of features", + "summary": "Get feature usage information", "operationId": "nodes-usage-3", "parameters": [ { diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json index 8052f4f298..46afd0b901 100644 --- a/output/openapi/elasticsearch-serverless-openapi.json +++ b/output/openapi/elasticsearch-serverless-openapi.json @@ -8786,7 +8786,7 @@ "cluster" ], "summary": "Ping the cluster", - "description": "Returns whether the cluster is running.", + "description": "Get information about whether the cluster is running.", "operationId": "ping", "responses": { "200": { diff --git a/output/schema/schema.json b/output/schema/schema.json index 6da5b86c01..c9e74c01de 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -2246,7 +2246,7 @@ "stability": "stable" } }, - "description": "Provides explanations for shard allocations in the cluster.", + "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.", "docId": "cluster-allocation-explain", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-allocation-explain.html", "name": "cluster.allocation_explain", @@ -2324,9 +2324,11 @@ "stability": "stable" } }, - "description": "Clears cluster voting config exclusions.", + "description": "Clear cluster voting config exclusions.\nRemove master-eligible nodes from the voting configuration exclusion list.", "docId": "voting-config-exclusions", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html", + "extDocId": "add-nodes", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/add-elasticsearch-nodes.html", "name": "cluster.delete_voting_config_exclusions", "request": { "name": "Request", @@ -2444,7 +2446,7 @@ "stability": "stable" } }, - "description": "Returns cluster-wide settings.\nBy default, it returns only settings that have been explicitly defined.", + "description": "Get cluster-wide settings.\nBy default, it returns only settings that have been explicitly defined.", "docId": "cluster-get-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-get-settings.html", "name": "cluster.get_settings", @@ -2485,7 +2487,7 @@ "stability": "stable" } }, - "description": "The cluster health API returns a simple status on the health of the cluster. You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.\nThe cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster, yellow means that the primary shard is allocated but replicas are not, and green means that all shards are allocated. The index level status is controlled by the worst shard status. The cluster status is controlled by the worst index status.", + "description": "Get the cluster health status.\nYou can also use the API to get the health status of only specified data streams and indices.\nFor data streams, the API retrieves the health status of the stream’s backing indices.\n\nThe cluster health status is: green, yellow or red.\nOn the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.\nThe index level status is controlled by the worst shard status.\n\nOne of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.\nThe cluster status is controlled by the worst index status.", "docId": "cluster-health", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-health.html", @@ -2569,7 +2571,7 @@ "stability": "stable" } }, - "description": "Returns cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet been executed.\nNOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the Task Management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", + "description": "Get the pending cluster tasks.\nGet information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.\n\nNOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", "docId": "cluster-pending", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-pending.html", "name": "cluster.pending_tasks", @@ -2606,9 +2608,11 @@ "stability": "stable" } }, - "description": "Updates the cluster voting config exclusions by node ids or node names.", + "description": "Update voting configuration exclusions.\nUpdate the cluster voting config exclusions by node IDs or node names.\nBy default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks.\nIf you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually.\nThe API adds an entry for each specified node to the cluster’s voting configuration exclusions list.\nIt then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.\n\nClusters should have no voting configuration exclusions in normal operation.\nOnce the excluded nodes have stopped, clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`.\nThis API waits for the nodes to be fully removed from the cluster before it returns.\nIf your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.\n\nA response to `POST /_cluster/voting_config_exclusions` with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.\nIf the call to `POST /_cluster/voting_config_exclusions` fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration.\nIn that case, you may safely retry the call.\n\nNOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period.\nThey are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.", "docId": "voting-config-exclusions", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/voting-config-exclusions.html", + "extDocId": "add-nodes", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/add-elasticsearch-nodes.html", "name": "cluster.post_voting_config_exclusions", "request": { "name": "Request", @@ -2687,7 +2691,7 @@ "stability": "stable" } }, - "description": "Updates the cluster settings.", + "description": "Update the cluster settings.\nConfigure and update dynamic settings on a running cluster.\nYou can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.\n\nUpdates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.\nYou can also reset transient or persistent settings by assigning them a null value.\n\nIf you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.\nFor example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.\nHowever, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.\n\nTIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.\nIf you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.\nOnly use `elasticsearch.yml` for static cluster settings and node settings.\nThe API doesn’t require a restart and ensures a setting’s value is the same on all nodes.\n\nWARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.\nIf a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.", "docId": "cluster-update-settings", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-update-settings.html", "name": "cluster.put_settings", @@ -2722,7 +2726,7 @@ "stability": "stable" } }, - "description": "The cluster remote info API allows you to retrieve all of the configured\nremote cluster information. It returns connection and endpoint information\nkeyed by the configured remote cluster alias.", + "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.", "docId": "cluster-remote-info", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-remote-info.html", "name": "cluster.remote_info", @@ -2758,7 +2762,7 @@ "stability": "stable" } }, - "description": "Allows to manually change the allocation of individual shards in the cluster.", + "description": "Reroute the cluster.\nManually change the allocation of individual shards in the cluster.\nFor example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.\n\nIt is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as `cluster.routing.rebalance.enable`) in order to remain in a balanced state.\nFor example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.\n\nThe cluster can be set to disable allocations using the `cluster.routing.allocation.enable` setting.\nIf allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.\n\nThe cluster will attempt to allocate a shard a maximum of `index.allocation.max_retries` times in a row (defaults to `5`), before giving up and leaving the shard unallocated.\nThis scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.\n\nOnce the problem has been corrected, allocation can be manually retried by calling the reroute API with the `?retry_failed` URI query parameter, which will attempt a single retry round for these shards.", "docId": "cluster-reroute", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-reroute.html", "name": "cluster.reroute", @@ -2797,7 +2801,7 @@ "stability": "stable" } }, - "description": "Returns a comprehensive information about the state of the cluster.", + "description": "Get the cluster state.\nGet comprehensive information about the state of the cluster.\n\nThe cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.\n\nThe elected master node ensures that every node in the cluster has a copy of the same cluster state.\nThis API lets you retrieve a representation of this internal state for debugging or diagnostic purposes.\nYou may need to consult the Elasticsearch source code to determine the precise meaning of the response.\n\nBy default the API will route requests to the elected master node since this node is the authoritative source of cluster states.\nYou can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter.\n\nElasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data.\nIf you use this API repeatedly, your cluster may become unstable.\n\nWARNING: The response is a representation of an internal data structure.\nIts format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version.\nDo not query this API using external monitoring tools.\nInstead, obtain the information you require using other more stable cluster APIs.", "docId": "cluster-state", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-state.html", "name": "cluster.state", @@ -2851,7 +2855,7 @@ "stability": "stable" } }, - "description": "Returns cluster statistics.\nIt returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", + "description": "Get cluster statistics.\nGet basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", "docId": "cluster-stats", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-stats.html", "name": "cluster.stats", @@ -5490,7 +5494,7 @@ "stability": "stable" } }, - "description": "Returns the health of the cluster.", + "description": "Get the cluster health.\nGet a report with the health status of an Elasticsearch cluster.\nThe report contains a list of indicators that compose Elasticsearch functionality.\n\nEach indicator has a health status of: green, unknown, yellow or red.\nThe indicator will provide an explanation and metadata describing the reason for its current health status.\n\nThe cluster’s status is controlled by the worst indicator status.\n\nIn the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue.\nEach impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.\n\nSome health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system.\nThe root cause and remediation steps are encapsulated in a diagnosis.\nA diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.\n\nNOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently.\nWhen setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/health-api.html", "name": "health_report", "request": { @@ -13029,7 +13033,7 @@ "stability": "experimental" } }, - "description": "You can use this API to clear the archived repositories metering information in the cluster.", + "description": "Clear the archived repositories metering.\nClear the archived repositories metering information in the cluster.", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/clear-repositories-metering-archive-api.html", "name": "nodes.clear_repositories_metering_archive", @@ -13071,7 +13075,7 @@ "stability": "experimental" } }, - "description": "You can use the cluster repositories metering API to retrieve repositories metering information in a cluster.\nThis API exposes monotonically non-decreasing counters and it’s expected that clients would durably store the\ninformation needed to compute aggregations over a period of time. Additionally, the information exposed by this\nAPI is volatile, meaning that it won’t be present after node restarts.", + "description": "Get cluster repositories metering.\nGet repositories metering information for a cluster.\nThis API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time.\nAdditionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/get-repositories-metering-api.html", "name": "nodes.get_repositories_metering_info", @@ -13112,7 +13116,7 @@ "stability": "stable" } }, - "description": "This API yields a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of each node’s top hot threads.", + "description": "Get the hot threads for nodes.\nGet a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of the top hot threads for each node.", "docId": "cluster-nodes-hot-threads", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-nodes-hot-threads.html", @@ -13161,7 +13165,7 @@ "stability": "stable" } }, - "description": "Returns cluster nodes information.", + "description": "Get node information.\nBy default, the API returns all attributes and core settings for cluster nodes.", "docId": "cluster-nodes-info", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-nodes-info.html", @@ -13212,7 +13216,7 @@ "stability": "stable" } }, - "description": "Reloads the keystore on nodes in the cluster.", + "description": "Reload the keystore on nodes in the cluster.\n\nSecure settings are stored in an on-disk keystore. Certain of these settings are reloadable.\nThat is, you can change them on disk and reload them without restarting any nodes in the cluster.\nWhen you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.\n\nWhen the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings.\nReloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted.\nAlternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/master/secure-settings.html#reloadable-secure-settings", "name": "nodes.reload_secure_settings", @@ -13256,7 +13260,7 @@ "stability": "stable" } }, - "description": "Returns cluster nodes statistics.", + "description": "Get node statistics.\nGet statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "docId": "cluster-nodes-stats", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-nodes-stats.html", @@ -13329,7 +13333,7 @@ "stability": "stable" } }, - "description": "Returns information on the usage of features.", + "description": "Get feature usage information.", "docId": "cluster-nodes-usage", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/cluster-nodes-usage.html", @@ -13434,7 +13438,7 @@ "stability": "stable" } }, - "description": "Ping the cluster.\nReturns whether the cluster is running.", + "description": "Ping the cluster.\nGet information about whether the cluster is running.", "docTag": "cluster", "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html", "name": "ping", @@ -26192,7 +26196,7 @@ "body": { "kind": "no_body" }, - "description": "Returns the health of the cluster.", + "description": "Get the cluster health.\nGet a report with the health status of an Elasticsearch cluster.\nThe report contains a list of indicators that compose Elasticsearch functionality.\n\nEach indicator has a health status of: green, unknown, yellow or red.\nThe indicator will provide an explanation and metadata describing the reason for its current health status.\n\nThe cluster’s status is controlled by the worst indicator status.\n\nIn the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue.\nEach impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system.\n\nSome health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system.\nThe root cause and remediation steps are encapsulated in a diagnosis.\nA diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem.\n\nNOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently.\nWhen setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic.", "inherits": { "type": { "name": "RequestBase", @@ -26272,7 +26276,7 @@ } } ], - "specLocation": "_global/health_report/Request.ts#L24-L52" + "specLocation": "_global/health_report/Request.ts#L24-L70" }, { "kind": "response", @@ -29715,7 +29719,7 @@ "body": { "kind": "no_body" }, - "description": "Ping the cluster.\nReturns whether the cluster is running.", + "description": "Ping the cluster.\nGet information about whether the cluster is running.", "inherits": { "type": { "name": "RequestBase", @@ -106060,7 +106064,7 @@ } ] }, - "description": "Provides explanations for shard allocations in the cluster.", + "description": "Explain the shard allocations.\nGet explanations for shard allocations in the cluster.\nFor unassigned shards, it provides an explanation for why the shard is unassigned.\nFor assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node.\nThis API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.", "inherits": { "type": { "name": "RequestBase", @@ -106100,7 +106104,7 @@ } } ], - "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L24-L61" + "specLocation": "cluster/allocation_explain/ClusterAllocationExplainRequest.ts#L24-L66" }, { "kind": "interface", @@ -106720,7 +106724,7 @@ "body": { "kind": "no_body" }, - "description": "Clears cluster voting config exclusions.", + "description": "Clear cluster voting config exclusions.\nRemove master-eligible nodes from the voting configuration exclusion list.", "inherits": { "type": { "name": "RequestBase", @@ -106747,7 +106751,7 @@ } } ], - "specLocation": "cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts#L22-L40" + "specLocation": "cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts#L22-L43" }, { "kind": "response", @@ -106967,7 +106971,7 @@ "body": { "kind": "no_body" }, - "description": "Returns cluster-wide settings.\nBy default, it returns only settings that have been explicitly defined.", + "description": "Get cluster-wide settings.\nBy default, it returns only settings that have been explicitly defined.", "inherits": { "type": { "name": "RequestBase", @@ -107485,7 +107489,7 @@ "body": { "kind": "no_body" }, - "description": "The cluster health API returns a simple status on the health of the cluster. You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.\nThe cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster, yellow means that the primary shard is allocated but replicas are not, and green means that all shards are allocated. The index level status is controlled by the worst shard status. The cluster status is controlled by the worst index status.", + "description": "Get the cluster health status.\nYou can also use the API to get the health status of only specified data streams and indices.\nFor data streams, the API retrieves the health status of the stream’s backing indices.\n\nThe cluster health status is: green, yellow or red.\nOn the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated.\nThe index level status is controlled by the worst shard status.\n\nOne of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level.\nThe cluster status is controlled by the worst index status.", "inherits": { "type": { "name": "RequestBase", @@ -107663,7 +107667,7 @@ } } ], - "specLocation": "cluster/health/ClusterHealthRequest.ts#L32-L99" + "specLocation": "cluster/health/ClusterHealthRequest.ts#L32-L107" }, { "kind": "response", @@ -108001,7 +108005,7 @@ "body": { "kind": "no_body" }, - "description": "Returns cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet been executed.\nNOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the Task Management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", + "description": "Get the pending cluster tasks.\nGet information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.\n\nNOTE: This API returns a list of any pending updates to the cluster state.\nThese are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests.\nHowever, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.", "inherits": { "type": { "name": "RequestBase", @@ -108041,7 +108045,7 @@ } } ], - "specLocation": "cluster/pending_tasks/ClusterPendingTasksRequest.ts#L23-L48" + "specLocation": "cluster/pending_tasks/ClusterPendingTasksRequest.ts#L23-L50" }, { "kind": "response", @@ -108078,7 +108082,7 @@ "body": { "kind": "no_body" }, - "description": "Updates the cluster voting config exclusions by node ids or node names.", + "description": "Update voting configuration exclusions.\nUpdate the cluster voting config exclusions by node IDs or node names.\nBy default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks.\nIf you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually.\nThe API adds an entry for each specified node to the cluster’s voting configuration exclusions list.\nIt then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes.\n\nClusters should have no voting configuration exclusions in normal operation.\nOnce the excluded nodes have stopped, clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`.\nThis API waits for the nodes to be fully removed from the cluster before it returns.\nIf your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear the voting configuration exclusions without waiting for the nodes to leave the cluster.\n\nA response to `POST /_cluster/voting_config_exclusions` with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`.\nIf the call to `POST /_cluster/voting_config_exclusions` fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration.\nIn that case, you may safely retry the call.\n\nNOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period.\nThey are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes.", "inherits": { "type": { "name": "RequestBase", @@ -108129,7 +108133,7 @@ } } ], - "specLocation": "cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts#L24-L50" + "specLocation": "cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts#L24-L69" }, { "kind": "response", @@ -108319,7 +108323,7 @@ } ] }, - "description": "Updates the cluster settings.", + "description": "Update the cluster settings.\nConfigure and update dynamic settings on a running cluster.\nYou can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`.\n\nUpdates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart.\nYou can also reset transient or persistent settings by assigning them a null value.\n\nIf you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value.\nFor example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting.\nHowever, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting.\n\nTIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster.\nIf you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings.\nOnly use `elasticsearch.yml` for static cluster settings and node settings.\nThe API doesn’t require a restart and ensures a setting’s value is the same on all nodes.\n\nWARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead.\nIf a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.", "inherits": { "type": { "name": "RequestBase", @@ -108371,7 +108375,7 @@ } } ], - "specLocation": "cluster/put_settings/ClusterPutSettingsRequest.ts#L25-L43" + "specLocation": "cluster/put_settings/ClusterPutSettingsRequest.ts#L25-L61" }, { "kind": "response", @@ -108654,7 +108658,7 @@ "body": { "kind": "no_body" }, - "description": "The cluster remote info API allows you to retrieve all of the configured\nremote cluster information. It returns connection and endpoint information\nkeyed by the configured remote cluster alias.", + "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.", "inherits": { "type": { "name": "RequestBase", @@ -109003,7 +109007,7 @@ } ] }, - "description": "Allows to manually change the allocation of individual shards in the cluster.", + "description": "Reroute the cluster.\nManually change the allocation of individual shards in the cluster.\nFor example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node.\n\nIt is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as `cluster.routing.rebalance.enable`) in order to remain in a balanced state.\nFor example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out.\n\nThe cluster can be set to disable allocations using the `cluster.routing.allocation.enable` setting.\nIf allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing.\n\nThe cluster will attempt to allocate a shard a maximum of `index.allocation.max_retries` times in a row (defaults to `5`), before giving up and leaving the shard unallocated.\nThis scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes.\n\nOnce the problem has been corrected, allocation can be manually retried by calling the reroute API with the `?retry_failed` URI query parameter, which will attempt a single retry round for these shards.", "inherits": { "type": { "name": "RequestBase", @@ -109017,7 +109021,7 @@ "path": [], "query": [ { - "description": "If true, then the request simulates the operation only and returns the resulting state.", + "description": "If true, then the request simulates the operation.\nIt will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes.", "name": "dry_run", "required": false, "serverDefault": false, @@ -109030,7 +109034,7 @@ } }, { - "description": "If true, then the response contains an explanation of why the commands can or cannot be executed.", + "description": "If true, then the response contains an explanation of why the commands can or cannot run.", "name": "explain", "required": false, "serverDefault": false, @@ -109095,7 +109099,7 @@ } } ], - "specLocation": "cluster/reroute/ClusterRerouteRequest.ts#L25-L70" + "specLocation": "cluster/reroute/ClusterRerouteRequest.ts#L25-L85" }, { "kind": "interface", @@ -109316,7 +109320,7 @@ "body": { "kind": "no_body" }, - "description": "Returns a comprehensive information about the state of the cluster.", + "description": "Get the cluster state.\nGet comprehensive information about the state of the cluster.\n\nThe cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.\n\nThe elected master node ensures that every node in the cluster has a copy of the same cluster state.\nThis API lets you retrieve a representation of this internal state for debugging or diagnostic purposes.\nYou may need to consult the Elasticsearch source code to determine the precise meaning of the response.\n\nBy default the API will route requests to the elected master node since this node is the authoritative source of cluster states.\nYou can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter.\n\nElasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data.\nIf you use this API repeatedly, your cluster may become unstable.\n\nWARNING: The response is a representation of an internal data structure.\nIts format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version.\nDo not query this API using external monitoring tools.\nInstead, obtain the information you require using other more stable cluster APIs.", "inherits": { "type": { "name": "RequestBase", @@ -109456,7 +109460,7 @@ } } ], - "specLocation": "cluster/state/ClusterStateRequest.ts#L29-L56" + "specLocation": "cluster/state/ClusterStateRequest.ts#L29-L75" }, { "kind": "response", @@ -111510,7 +111514,7 @@ "body": { "kind": "no_body" }, - "description": "Returns cluster statistics.\nIt returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", + "description": "Get cluster statistics.\nGet basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins).", "inherits": { "type": { "name": "RequestBase", @@ -178968,7 +178972,7 @@ "body": { "kind": "no_body" }, - "description": "You can use this API to clear the archived repositories metering information in the cluster.", + "description": "Clear the archived repositories metering.\nClear the archived repositories metering information in the cluster.", "inherits": { "type": { "name": "RequestBase", @@ -179006,7 +179010,7 @@ } ], "query": [], - "specLocation": "nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts#L24-L44" + "specLocation": "nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts#L24-L45" }, { "kind": "response", @@ -179085,7 +179089,7 @@ "body": { "kind": "no_body" }, - "description": "You can use the cluster repositories metering API to retrieve repositories metering information in a cluster.\nThis API exposes monotonically non-decreasing counters and it’s expected that clients would durably store the\ninformation needed to compute aggregations over a period of time. Additionally, the information exposed by this\nAPI is volatile, meaning that it won’t be present after node restarts.", + "description": "Get cluster repositories metering.\nGet repositories metering information for a cluster.\nThis API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time.\nAdditionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts.", "inherits": { "type": { "name": "RequestBase", @@ -179190,7 +179194,7 @@ "body": { "kind": "no_body" }, - "description": "This API yields a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of each node’s top hot threads.", + "description": "Get the hot threads for nodes.\nGet a breakdown of the hot threads on each selected node in the cluster.\nThe output is plain text with a breakdown of the top hot threads for each node.", "inherits": { "type": { "name": "RequestBase", @@ -179320,7 +179324,7 @@ } } ], - "specLocation": "nodes/hot_threads/NodesHotThreadsRequest.ts#L25-L84" + "specLocation": "nodes/hot_threads/NodesHotThreadsRequest.ts#L25-L85" }, { "kind": "response", @@ -182313,7 +182317,7 @@ "body": { "kind": "no_body" }, - "description": "Returns cluster nodes information.", + "description": "Get node information.\nBy default, the API returns all attributes and core settings for cluster nodes.", "inherits": { "type": { "name": "RequestBase", @@ -182391,7 +182395,7 @@ } } ], - "specLocation": "nodes/info/NodesInfoRequest.ts#L24-L56" + "specLocation": "nodes/info/NodesInfoRequest.ts#L24-L57" }, { "kind": "response", @@ -182482,7 +182486,7 @@ } ] }, - "description": "Reloads the keystore on nodes in the cluster.", + "description": "Reload the keystore on nodes in the cluster.\n\nSecure settings are stored in an on-disk keystore. Certain of these settings are reloadable.\nThat is, you can change them on disk and reload them without restarting any nodes in the cluster.\nWhen you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.\n\nWhen the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings.\nReloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted.\nAlternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.", "inherits": { "type": { "name": "RequestBase", @@ -182522,7 +182526,7 @@ } } ], - "specLocation": "nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts#L24-L51" + "specLocation": "nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts#L24-L59" }, { "kind": "response", @@ -182599,7 +182603,7 @@ "body": { "kind": "no_body" }, - "description": "Returns cluster nodes statistics.", + "description": "Get node statistics.\nGet statistics for nodes in a cluster.\nBy default, all stats are returned. You can limit the returned information by using metrics.", "inherits": { "type": { "name": "RequestBase", @@ -182777,7 +182781,7 @@ } } ], - "specLocation": "nodes/stats/NodesStatsRequest.ts#L24-L76" + "specLocation": "nodes/stats/NodesStatsRequest.ts#L24-L78" }, { "kind": "response", @@ -182944,7 +182948,7 @@ "body": { "kind": "no_body" }, - "description": "Returns information on the usage of features.", + "description": "Get feature usage information.", "inherits": { "type": { "name": "RequestBase", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index bd36f9b239..11cf6f19cd 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -1,3 +1,4 @@ +add-nodes,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/add-elasticsearch-nodes.html analysis-analyzers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-analyzers.html analysis-charfilters,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-charfilters.html analysis-normalizers,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/analysis-normalizers.html diff --git a/specification/_global/health_report/Request.ts b/specification/_global/health_report/Request.ts index dad3fdb5ae..068267ecab 100644 --- a/specification/_global/health_report/Request.ts +++ b/specification/_global/health_report/Request.ts @@ -22,6 +22,24 @@ import { integer } from '@_types/Numeric' import { Duration } from '@_types/Time' /** + * Get the cluster health. + * Get a report with the health status of an Elasticsearch cluster. + * The report contains a list of indicators that compose Elasticsearch functionality. + * + * Each indicator has a health status of: green, unknown, yellow or red. + * The indicator will provide an explanation and metadata describing the reason for its current health status. + * + * The cluster’s status is controlled by the worst indicator status. + * + * In the event that an indicator’s status is non-green, a list of impacts may be present in the indicator result which detail the functionalities that are negatively affected by the health issue. + * Each impact carries with it a severity level, an area of the system that is affected, and a simple description of the impact on the system. + * + * Some health indicators can determine the root cause of a health problem and prescribe a set of steps that can be performed in order to improve the health of the system. + * The root cause and remediation steps are encapsulated in a diagnosis. + * A diagnosis contains a cause detailing a root cause analysis, an action containing a brief description of the steps to take to fix the problem, the list of affected resources (if applicable), and a detailed step-by-step troubleshooting guide to fix the diagnosed problem. + * + * NOTE: The health indicators perform root cause analysis of non-green health statuses. This can be computationally expensive when called frequently. + * When setting up automated polling of the API for health status, set verbose to false to disable the more expensive analysis logic. * @rest_spec_name health_report * @availability stack since=8.7.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/_global/ping/PingRequest.ts b/specification/_global/ping/PingRequest.ts index 42af1f4d01..b4e05ae716 100644 --- a/specification/_global/ping/PingRequest.ts +++ b/specification/_global/ping/PingRequest.ts @@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base' /** * Ping the cluster. - * Returns whether the cluster is running. + * Get information about whether the cluster is running. * @rest_spec_name ping * @availability stack stability=stable * @availability serverless stability=stable visibility=public diff --git a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts index 41eca0b1e0..f38a39db22 100644 --- a/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts +++ b/specification/cluster/allocation_explain/ClusterAllocationExplainRequest.ts @@ -22,6 +22,11 @@ import { IndexName } from '@_types/common' import { integer } from '@_types/Numeric' /** + * Explain the shard allocations. + * Get explanations for shard allocations in the cluster. + * For unassigned shards, it provides an explanation for why the shard is unassigned. + * For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. + * This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise. * @rest_spec_name cluster.allocation_explain * @availability stack since=5.0.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts b/specification/cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts index 20c8df67cf..3f181de67e 100644 --- a/specification/cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts +++ b/specification/cluster/delete_voting_config_exclusions/ClusterDeleteVotingConfigExclusionsRequest.ts @@ -20,9 +20,12 @@ import { RequestBase } from '@_types/Base' /** + * Clear cluster voting config exclusions. + * Remove master-eligible nodes from the voting configuration exclusion list. * @rest_spec_name cluster.delete_voting_config_exclusions * @availability stack since=7.0.0 stability=stable * @doc_id voting-config-exclusions + * @ext_doc_id add-nodes */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/cluster/get_settings/ClusterGetSettingsRequest.ts b/specification/cluster/get_settings/ClusterGetSettingsRequest.ts index 8a608fb3eb..1ef75c0a03 100644 --- a/specification/cluster/get_settings/ClusterGetSettingsRequest.ts +++ b/specification/cluster/get_settings/ClusterGetSettingsRequest.ts @@ -21,7 +21,7 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** - * Returns cluster-wide settings. + * Get cluster-wide settings. * By default, it returns only settings that have been explicitly defined. * @rest_spec_name cluster.get_settings * @availability stack stability=stable diff --git a/specification/cluster/health/ClusterHealthRequest.ts b/specification/cluster/health/ClusterHealthRequest.ts index 31fc593a07..47db3c8aeb 100644 --- a/specification/cluster/health/ClusterHealthRequest.ts +++ b/specification/cluster/health/ClusterHealthRequest.ts @@ -30,8 +30,16 @@ import { integer } from '@_types/Numeric' import { Duration } from '@_types/Time' /** - * The cluster health API returns a simple status on the health of the cluster. You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices. - * The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster, yellow means that the primary shard is allocated but replicas are not, and green means that all shards are allocated. The index level status is controlled by the worst shard status. The cluster status is controlled by the worst index status. + * Get the cluster health status. + * You can also use the API to get the health status of only specified data streams and indices. + * For data streams, the API retrieves the health status of the stream’s backing indices. + * + * The cluster health status is: green, yellow or red. + * On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. + * The index level status is controlled by the worst shard status. + * + * One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. + * The cluster status is controlled by the worst index status. * @rest_spec_name cluster.health * @availability stack since=1.3.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/cluster/pending_tasks/ClusterPendingTasksRequest.ts b/specification/cluster/pending_tasks/ClusterPendingTasksRequest.ts index a6bbb197e2..3e1b6c128f 100644 --- a/specification/cluster/pending_tasks/ClusterPendingTasksRequest.ts +++ b/specification/cluster/pending_tasks/ClusterPendingTasksRequest.ts @@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** - * Returns cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet been executed. + * Get the pending cluster tasks. + * Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect. + * * NOTE: This API returns a list of any pending updates to the cluster state. - * These are distinct from the tasks reported by the Task Management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. + * These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. * However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API. * @rest_spec_name cluster.pending_tasks * @availability stack stability=stable diff --git a/specification/cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts b/specification/cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts index a581419d87..67421889c0 100644 --- a/specification/cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts +++ b/specification/cluster/post_voting_config_exclusions/ClusterPostVotingConfigExclusionsRequest.ts @@ -22,9 +22,28 @@ import { Ids, Names } from '@_types/common' import { Duration } from '@_types/Time' /** + * Update voting configuration exclusions. + * Update the cluster voting config exclusions by node IDs or node names. + * By default, if there are more than three master-eligible nodes in the cluster and you remove fewer than half of the master-eligible nodes in the cluster at once, the voting configuration automatically shrinks. + * If you want to shrink the voting configuration to contain fewer than three nodes or to remove half or more of the master-eligible nodes in the cluster at once, use this API to remove departing nodes from the voting configuration manually. + * The API adds an entry for each specified node to the cluster’s voting configuration exclusions list. + * It then waits until the cluster has reconfigured its voting configuration to exclude the specified nodes. + * + * Clusters should have no voting configuration exclusions in normal operation. + * Once the excluded nodes have stopped, clear the voting configuration exclusions with `DELETE /_cluster/voting_config_exclusions`. + * This API waits for the nodes to be fully removed from the cluster before it returns. + * If your cluster has voting configuration exclusions for nodes that you no longer intend to remove, use `DELETE /_cluster/voting_config_exclusions?wait_for_removal=false` to clear the voting configuration exclusions without waiting for the nodes to leave the cluster. + * + * A response to `POST /_cluster/voting_config_exclusions` with an HTTP status code of 200 OK guarantees that the node has been removed from the voting configuration and will not be reinstated until the voting configuration exclusions are cleared by calling `DELETE /_cluster/voting_config_exclusions`. + * If the call to `POST /_cluster/voting_config_exclusions` fails or returns a response with an HTTP status code other than 200 OK then the node may not have been removed from the voting configuration. + * In that case, you may safely retry the call. + * + * NOTE: Voting exclusions are required only when you remove at least half of the master-eligible nodes from a cluster in a short time period. + * They are not required when removing master-ineligible nodes or when removing fewer than half of the master-eligible nodes. * @rest_spec_name cluster.post_voting_config_exclusions * @availability stack since=7.0.0 stability=stable * @doc_id voting-config-exclusions + * @ext_doc_id add-nodes */ export interface Request extends RequestBase { query_parameters: { diff --git a/specification/cluster/put_settings/ClusterPutSettingsRequest.ts b/specification/cluster/put_settings/ClusterPutSettingsRequest.ts index 19bc33b4a1..c2f9bfc1e3 100644 --- a/specification/cluster/put_settings/ClusterPutSettingsRequest.ts +++ b/specification/cluster/put_settings/ClusterPutSettingsRequest.ts @@ -23,6 +23,24 @@ import { RequestBase } from '@_types/Base' import { Duration } from '@_types/Time' /** + * Update the cluster settings. + * Configure and update dynamic settings on a running cluster. + * You can also configure dynamic settings locally on an unstarted or shut down node in `elasticsearch.yml`. + * + * Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. + * You can also reset transient or persistent settings by assigning them a null value. + * + * If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) `elasticsearch.yml` setting; 4) Default setting value. + * For example, you can apply a transient setting to override a persistent setting or `elasticsearch.yml` setting. + * However, a change to an `elasticsearch.yml` setting will not override a defined transient or persistent setting. + * + * TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster. + * If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings. + * Only use `elasticsearch.yml` for static cluster settings and node settings. + * The API doesn’t require a restart and ensures a setting’s value is the same on all nodes. + * + * WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. + * If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration. * @rest_spec_name cluster.put_settings * @availability stack stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts index a81800ec0b..218077a6e6 100644 --- a/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts +++ b/specification/cluster/remote_info/ClusterRemoteInfoRequest.ts @@ -20,9 +20,9 @@ import { RequestBase } from '@_types/Base' /** - * The cluster remote info API allows you to retrieve all of the configured - * remote cluster information. It returns connection and endpoint information - * keyed by the configured remote cluster alias. + * 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. * @rest_spec_name cluster.remote_info * @availability stack since=6.1.0 stability=stable * @doc_id cluster-remote-info diff --git a/specification/cluster/reroute/ClusterRerouteRequest.ts b/specification/cluster/reroute/ClusterRerouteRequest.ts index 1b07ae501a..cac1dea4f7 100644 --- a/specification/cluster/reroute/ClusterRerouteRequest.ts +++ b/specification/cluster/reroute/ClusterRerouteRequest.ts @@ -23,6 +23,20 @@ import { Duration } from '@_types/Time' import { Command } from './types' /** + * Reroute the cluster. + * Manually change the allocation of individual shards in the cluster. + * For example, a shard can be moved from one node to another explicitly, an allocation can be canceled, and an unassigned shard can be explicitly allocated to a specific node. + * + * It is important to note that after processing any reroute commands Elasticsearch will perform rebalancing as normal (respecting the values of settings such as `cluster.routing.rebalance.enable`) in order to remain in a balanced state. + * For example, if the requested allocation includes moving a shard from node1 to node2 then this may cause a shard to be moved from node2 back to node1 to even things out. + * + * The cluster can be set to disable allocations using the `cluster.routing.allocation.enable` setting. + * If allocations are disabled then the only allocations that will be performed are explicit ones given using the reroute command, and consequent allocations due to rebalancing. + * + * The cluster will attempt to allocate a shard a maximum of `index.allocation.max_retries` times in a row (defaults to `5`), before giving up and leaving the shard unallocated. + * This scenario can be caused by structural problems such as having an analyzer which refers to a stopwords file which doesn’t exist on all nodes. + * + * Once the problem has been corrected, allocation can be manually retried by calling the reroute API with the `?retry_failed` URI query parameter, which will attempt a single retry round for these shards. * @rest_spec_name cluster.reroute * @availability stack since=5.0.0 stability=stable * @availability serverless stability=stable visibility=private @@ -31,12 +45,13 @@ import { Command } from './types' export interface Request extends RequestBase { query_parameters: { /** - * If true, then the request simulates the operation only and returns the resulting state. + * If true, then the request simulates the operation. + * It will calculate the result of applying the commands to the current cluster state and return the resulting cluster state after the commands (and rebalancing) have been applied; it will not actually perform the requested changes. * @server_default false */ dry_run?: boolean /** - * If true, then the response contains an explanation of why the commands can or cannot be executed. + * If true, then the response contains an explanation of why the commands can or cannot run. * @server_default false */ explain?: boolean diff --git a/specification/cluster/state/ClusterStateRequest.ts b/specification/cluster/state/ClusterStateRequest.ts index 70f8d93a36..3b35cb1e13 100644 --- a/specification/cluster/state/ClusterStateRequest.ts +++ b/specification/cluster/state/ClusterStateRequest.ts @@ -27,6 +27,25 @@ import { import { Duration } from '@_types/Time' /** + * Get the cluster state. + * Get comprehensive information about the state of the cluster. + * + * The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster. + * + * The elected master node ensures that every node in the cluster has a copy of the same cluster state. + * This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. + * You may need to consult the Elasticsearch source code to determine the precise meaning of the response. + * + * By default the API will route requests to the elected master node since this node is the authoritative source of cluster states. + * You can also retrieve the cluster state held on the node handling the API request by adding the `?local=true` query parameter. + * + * Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. + * If you use this API repeatedly, your cluster may become unstable. + * + * WARNING: The response is a representation of an internal data structure. + * Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. + * Do not query this API using external monitoring tools. + * Instead, obtain the information you require using other more stable cluster APIs. * @rest_spec_name cluster.state * @availability stack since=1.3.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/cluster/stats/ClusterStatsRequest.ts b/specification/cluster/stats/ClusterStatsRequest.ts index f4b35474ca..23cb647e9f 100644 --- a/specification/cluster/stats/ClusterStatsRequest.ts +++ b/specification/cluster/stats/ClusterStatsRequest.ts @@ -22,8 +22,8 @@ import { NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** - * Returns cluster statistics. - * It returns basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins). + * Get cluster statistics. + * Get basic index metrics (shard numbers, store size, memory usage) and information about the current nodes that form the cluster (number, roles, os, jvm versions, memory usage, cpu and installed plugins). * @rest_spec_name cluster.stats * @availability stack since=1.3.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts b/specification/nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts index 6a0db3bc1f..cccf463f54 100644 --- a/specification/nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts +++ b/specification/nodes/clear_repositories_metering_archive/ClearRepositoriesMeteringArchiveRequest.ts @@ -22,7 +22,8 @@ import { NodeIds } from '@_types/common' import { long } from '@_types/Numeric' /** - * You can use this API to clear the archived repositories metering information in the cluster. + * Clear the archived repositories metering. + * Clear the archived repositories metering information in the cluster. * @rest_spec_name nodes.clear_repositories_metering_archive * @availability stack since=7.16.0 stability=experimental * @availability serverless stability=experimental visibility=private diff --git a/specification/nodes/get_repositories_metering_info/GetRepositoriesMeteringInfoRequest.ts b/specification/nodes/get_repositories_metering_info/GetRepositoriesMeteringInfoRequest.ts index 698427d263..ddc35edb75 100644 --- a/specification/nodes/get_repositories_metering_info/GetRepositoriesMeteringInfoRequest.ts +++ b/specification/nodes/get_repositories_metering_info/GetRepositoriesMeteringInfoRequest.ts @@ -21,10 +21,10 @@ import { RequestBase } from '@_types/Base' import { NodeIds } from '@_types/common' /** - * You can use the cluster repositories metering API to retrieve repositories metering information in a cluster. - * This API exposes monotonically non-decreasing counters and it’s expected that clients would durably store the - * information needed to compute aggregations over a period of time. Additionally, the information exposed by this - * API is volatile, meaning that it won’t be present after node restarts. + * Get cluster repositories metering. + * Get repositories metering information for a cluster. + * This API exposes monotonically non-decreasing counters and it is expected that clients would durably store the information needed to compute aggregations over a period of time. + * Additionally, the information exposed by this API is volatile, meaning that it will not be present after node restarts. * @rest_spec_name nodes.get_repositories_metering_info * @availability stack since=7.16.0 stability=experimental * @availability serverless stability=experimental visibility=private diff --git a/specification/nodes/hot_threads/NodesHotThreadsRequest.ts b/specification/nodes/hot_threads/NodesHotThreadsRequest.ts index 2f3073c5cf..46ef45bb17 100644 --- a/specification/nodes/hot_threads/NodesHotThreadsRequest.ts +++ b/specification/nodes/hot_threads/NodesHotThreadsRequest.ts @@ -23,8 +23,9 @@ import { long } from '@_types/Numeric' import { Duration } from '@_types/Time' /** - * This API yields a breakdown of the hot threads on each selected node in the cluster. - * The output is plain text with a breakdown of each node’s top hot threads. + * Get the hot threads for nodes. + * Get a breakdown of the hot threads on each selected node in the cluster. + * The output is plain text with a breakdown of the top hot threads for each node. * @rest_spec_name nodes.hot_threads * @availability stack stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/nodes/info/NodesInfoRequest.ts b/specification/nodes/info/NodesInfoRequest.ts index 724fa0c79d..88c20e3b5e 100644 --- a/specification/nodes/info/NodesInfoRequest.ts +++ b/specification/nodes/info/NodesInfoRequest.ts @@ -22,7 +22,8 @@ import { Metrics, NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** - * Returns cluster nodes information. + * Get node information. + * By default, the API returns all attributes and core settings for cluster nodes. * @rest_spec_name nodes.info * @availability stack since=1.3.0 stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts b/specification/nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts index 783743df7c..bf1dce910a 100644 --- a/specification/nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts +++ b/specification/nodes/reload_secure_settings/ReloadSecureSettingsRequest.ts @@ -22,7 +22,15 @@ import { NodeIds, Password } from '@_types/common' import { Duration } from '@_types/Time' /** - * Reloads the keystore on nodes in the cluster. + * Reload the keystore on nodes in the cluster. + * + * Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. + * That is, you can change them on disk and reload them without restarting any nodes in the cluster. + * When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node. + * + * When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. + * Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. + * Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password. * @rest_spec_name nodes.reload_secure_settings * @availability stack since=6.5.0 stability=stable * @doc_tag cluster diff --git a/specification/nodes/stats/NodesStatsRequest.ts b/specification/nodes/stats/NodesStatsRequest.ts index b363ea64ec..d349a4df7d 100644 --- a/specification/nodes/stats/NodesStatsRequest.ts +++ b/specification/nodes/stats/NodesStatsRequest.ts @@ -22,7 +22,9 @@ import { Fields, Level, Metrics, NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** - * Returns cluster nodes statistics. + * Get node statistics. + * Get statistics for nodes in a cluster. + * By default, all stats are returned. You can limit the returned information by using metrics. * @rest_spec_name nodes.stats * @availability stack stability=stable * @availability serverless stability=stable visibility=private diff --git a/specification/nodes/usage/NodesUsageRequest.ts b/specification/nodes/usage/NodesUsageRequest.ts index 7508891e45..1b9a15ad03 100644 --- a/specification/nodes/usage/NodesUsageRequest.ts +++ b/specification/nodes/usage/NodesUsageRequest.ts @@ -22,7 +22,7 @@ import { Metrics, NodeIds } from '@_types/common' import { Duration } from '@_types/Time' /** - * Returns information on the usage of features. + * Get feature usage information. * @rest_spec_name nodes.usage * @availability stack since=6.0.0 stability=stable * @availability serverless stability=stable visibility=private