[DOCS] Edit node lifecycle summaries (#3309)

(cherry picked from commit 0a8b60a)

Author: lcawl

output/openapi/elasticsearch-openapi.json

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

output/schema/schema.json

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

specification/shutdown/delete_node/ShutdownDeleteNodeRequest.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: {