[Backport 8.17] Add shutdown API examples

specification/_doc_ids/table.csv

@@ -357,6 +357,9 @@ monitor-elasticsearch-cluster,https://www.elastic.co/guide/en/elasticsearch/refe
 multi-fields,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/multi-fields.html
 network-direction-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/network-direction-processor.html
 node-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/modules-node.html#node-roles
+nodes-api-shutdown-delete,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-shutdown.html
+nodes-api-shutdown-status,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-shutdown.html
+nodes-api-shutdown,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-shutdown.html
 paginate-search-results,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/paginate-search-results.html
 painless-contexts,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-contexts.html
 painless-execute-api,https://www.elastic.co/guide/en/elasticsearch/painless/{branch}/painless-execute-api.html

specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts

@@ -34,6 +34,7 @@ import { TimeUnit } from '@_types/Time'
  * @rest_spec_name shutdown.delete_node
  * @availability stack since=7.13.0 stability=stable
  * @cluster_privileges manage
+ * @doc_id nodes-api-shutdown-delete
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/shutdown/delete_node/ShutdownDeleteNodeResponseExample1.yaml

@@ -0,0 +1,5 @@
+# summary:
+description: A successful response from `DELETE /_nodes/USpTGYaBSIKbgSUJR2Z9lg/shutdown`.
+# type: response
+# response_code: ''
+value: "{\n    \"acknowledged\": true\n}"

specification/shutdown/get_node/ShutdownGetNodeRequest.ts

@@ -33,6 +33,7 @@ import { TimeUnit } from '@_types/Time'
  * @rest_spec_name shutdown.get_node
  * @availability stack since=7.13.0 stability=stable
  * @cluster_privileges manage
+ * @doc_id nodes-api-shutdown-status
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/shutdown/get_node/ShutdownGetNodeResponseExample1.yaml

@@ -0,0 +1,17 @@
+# summary:
+description: >
+  Get the status of shutdown preparations with `GET /_nodes/USpTGYaBSIKbgSUJR2Z9lg/shutdown`.
+  The response shows information about the shutdown preparations, including the status of shard migration, task migration, and plugin cleanup
+# type: response
+# response_code: ''
+value:
+  "{\n    \"nodes\": [\n        {\n            \"node_id\": \"USpTGYaBSIKbgSUJR2Z9lg\"\
+  ,\n            \"type\": \"RESTART\",\n            \"reason\": \"Demonstrating how\
+  \ the node shutdown API works\",\n            \"shutdown_startedmillis\": 1624406108685,\n\
+  \            \"allocation_delay\": \"10m\",\n            \"status\": \"COMPLETE\"\
+  ,\n            \"shard_migration\": {\n                \"status\": \"COMPLETE\"\
+  ,\n                \"shard_migrations_remaining\": 0,\n                \"explanation\"\
+  : \"no shard relocation is necessary for a node restart\"\n            },\n    \
+  \        \"persistent_tasks\": {\n                \"status\": \"COMPLETE\"\n   \
+  \         },\n            \"plugins\": {\n                \"status\": \"COMPLETE\"\
+  \n            }\n        }\n    ]\n}"

specification/shutdown/put_node/ShutdownPutNodeRequest.ts

@@ -27,6 +27,8 @@ import { Type } from '../_types/types'
  *
  * 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 you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.
+ *
  * 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.
@@ -40,19 +42,28 @@ import { Type } from '../_types/types'
  * @rest_spec_name shutdown.put_node
  * @availability stack since=7.13.0 stability=stable
  * @cluster_privileges manage
+ * @doc_id nodes-api-shutdown
  */
 export interface Request extends RequestBase {
   path_parts: {
+    /**
+     * The node identifier.
+     * This parameter is not validated against the cluster's active nodes.
+     * This enables you to register a node for shut down while it is offline.
+     * No error is thrown if you specify an invalid node ID.
+     */
     node_id: NodeId
   }
   query_parameters: {
     /**
-     * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
+     * The period to wait for a connection to the master node.
+     * If no response is received before the timeout expires, the request fails and returns an error.
      * @server_default 30s
      */
     master_timeout?: TimeUnit
     /**
-     * Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
+     * The period to wait for a response.
+     * If no response is received before the timeout expires, the request fails and returns an error.
      * @server_default 30s
      */
     timeout?: TimeUnit

specification/shutdown/put_node/ShutdownPutNodeRequestExample1.yaml

@@ -0,0 +1,9 @@
+# summary:
+# method_request: PUT /_nodes/USpTGYaBSIKbgSUJR2Z9lg/shutdown
+description: >
+  Register a node for shutdown with `PUT /_nodes/USpTGYaBSIKbgSUJR2Z9lg/shutdown`.
+  The `restart` type prepares the node to be restarted.
+# type: request
+value:
+  "{\n  \"type\": \"restart\",\n  \"reason\": \"Demonstrating how the node shutdown\
+  \ API works\",\n  \"allocation_delay\": \"20m\"\n}"