[DOCS] Edit cluster operation summaries (#3256)

Co-authored-by: Marci W <[email protected]>
(cherry picked from commit 0215517)

Author: 2 people

output/openapi/elasticsearch-openapi.json

@@ -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

output/openapi/elasticsearch-serverless-openapi.json

@@ -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

output/schema/schema.json

@@ -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

specification/_doc_ids/table.csv

@@ -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

specification/_global/health_report/Request.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: {

specification/_global/ping/PingRequest.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

specification/cluster/allocation_explain/ClusterAllocationExplainRequest.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