[DOCS] Edit node lifecycle summaries (#3309)

elastic · Dec 17, 2024 · 0a8b60a · 0a8b60a
1 parent 7cf7656
commit 0a8b60a
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 17 deletions.
diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts b/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts
@@ -22,8 +22,18 @@ import { NodeId } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Cancel node shutdown preparations.
+ * Remove a node from the shutdown list so it can resume normal operations.
+ * You must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster.
+ * Shutdown requests are never removed automatically by Elasticsearch.
+ *
+ * NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.
+ * Direct use is not supported.
+ *
+ * If the operator privileges feature is enabled, you must be an operator to use this API.
  * @rest_spec_name shutdown.delete_node
  * @availability stack since=7.13.0 stability=stable
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {

diff --git a/specification/shutdown/get_node/ShutdownGetNodeRequest.ts b/specification/shutdown/get_node/ShutdownGetNodeRequest.ts
@@ -22,8 +22,17 @@ import { NodeIds } from '@_types/common'
 import { TimeUnit } from '@_types/Time'
 
 /**
+ * Get the shutdown status.
+ *
+ * Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.
+ * The API returns status information for each part of the shut down process.
+ *
+ * NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+ *
+ * If the operator privileges feature is enabled, you must be an operator to use this API.
  * @rest_spec_name shutdown.get_node
  * @availability stack since=7.13.0 stability=stable
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {

diff --git a/specification/shutdown/put_node/ShutdownPutNodeRequest.ts b/specification/shutdown/put_node/ShutdownPutNodeRequest.ts
@@ -23,8 +23,23 @@ import { TimeUnit } from '@_types/Time'
 import { Type } from '../_types/types'
 
 /**
+ * Prepare a node to be shut down.
+ *
+ * NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
+ *
+ * If the operator privileges feature is enabled, you must be an operator to use this API.
+ *
+ * The API migrates ongoing tasks and index shards to other nodes as needed to prepare a node to be restarted or shut down and removed from the cluster.
+ * This ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.
+ *
+ * You must specify the type of shutdown: `restart`, `remove`, or `replace`.
+ * If a node is already being prepared for shutdown, you can use this API to change the shutdown type.
+ *
+ * IMPORTANT: This API does NOT terminate the Elasticsearch process.
+ * Monitor the node shutdown status to determine when it is safe to stop Elasticsearch.
  * @rest_spec_name shutdown.put_node
  * @availability stack since=7.13.0 stability=stable
+ * @cluster_privileges manage
  */
 export interface Request extends RequestBase {
   path_parts: {