From a1474f63bea427c443ec3de07b7b9431293f9549 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 6 Jan 2025 15:33:27 -0800 Subject: [PATCH] Add shutdown API examples --- output/openapi/elasticsearch-openapi.json | 8 +++--- output/schema/schema.json | 25 +++++++++++-------- specification/_doc_ids/table.csv | 3 +++ .../delete_node/ShutdownDeleteNodeRequest.ts | 1 + .../ShutdownDeleteNodeResponseExample1.yaml | 5 ++++ .../get_node/ShutdownGetNodeRequest.ts | 1 + .../ShutdownGetNodeResponseExample1.yaml | 17 +++++++++++++ .../put_node/ShutdownPutNodeRequest.ts | 15 +++++++++-- .../ShutdownPutNodeRequestExample1.yaml | 9 +++++++ 9 files changed, 67 insertions(+), 17 deletions(-) create mode 100644 specification/shutdown/delete_node/ShutdownDeleteNodeResponseExample1.yaml create mode 100644 specification/shutdown/get_node/ShutdownGetNodeResponseExample1.yaml create mode 100644 specification/shutdown/put_node/ShutdownPutNodeRequestExample1.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index abcb815e05..51c9b3d8c5 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -31925,13 +31925,13 @@ "shutdown" ], "summary": "Prepare a node to be shut down", - "description": "NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", + "description": "NOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", "operationId": "shutdown-put-node", "parameters": [ { "in": "path", "name": "node_id", - "description": "The node id of node to be shut down", + "description": "The node identifier.\nThis parameter is not validated against the cluster's active nodes.\nThis enables you to register a node for shut down while it is offline.\nNo error is thrown if you specify an invalid node ID.", "required": true, "deprecated": false, "schema": { @@ -31942,7 +31942,7 @@ { "in": "query", "name": "master_timeout", - "description": "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.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:TimeUnit" @@ -31952,7 +31952,7 @@ { "in": "query", "name": "timeout", - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "deprecated": false, "schema": { "$ref": "#/components/schemas/_types:TimeUnit" diff --git a/output/schema/schema.json b/output/schema/schema.json index 4771655be7..d5b7e282cd 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -17899,7 +17899,8 @@ } }, "description": "Cancel node shutdown preparations.\nRemove a node from the shutdown list so it can resume normal operations.\nYou must explicitly clear the shutdown request when a node rejoins the cluster or when a node has permanently left the cluster.\nShutdown requests are never removed automatically by Elasticsearch.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes.\nDirect use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", + "docId": "nodes-api-shutdown-delete", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/delete-shutdown.html", "name": "shutdown.delete_node", "privileges": { "cluster": [ @@ -17938,7 +17939,8 @@ } }, "description": "Get the shutdown status.\n\nGet information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled.\nThe API returns status information for each part of the shut down process.\n\nNOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", + "docId": "nodes-api-shutdown-status", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/get-shutdown.html", "name": "shutdown.get_node", "privileges": { "cluster": [ @@ -17982,8 +17984,9 @@ "stability": "stable" } }, - "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", - "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current", + "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", + "docId": "nodes-api-shutdown", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/put-shutdown.html", "name": "shutdown.put_node", "privileges": { "cluster": [ @@ -202155,7 +202158,7 @@ } } ], - "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L54" + "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L55" }, { "kind": "response", @@ -202385,7 +202388,7 @@ } } ], - "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L53" + "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L54" }, { "kind": "response", @@ -202531,7 +202534,7 @@ } ] }, - "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", + "description": "Prepare a node to be shut down.\n\nNOTE: This feature is designed for indirect use by Elastic Cloud, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.\n\nIf you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.\n\nIf the operator privileges feature is enabled, you must be an operator to use this API.\n\nThe 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.\nThis ensures that Elasticsearch can be stopped safely with minimal disruption to the cluster.\n\nYou must specify the type of shutdown: `restart`, `remove`, or `replace`.\nIf a node is already being prepared for shutdown, you can use this API to change the shutdown type.\n\nIMPORTANT: This API does NOT terminate the Elasticsearch process.\nMonitor the node shutdown status to determine when it is safe to stop Elasticsearch.", "inherits": { "type": { "name": "RequestBase", @@ -202544,7 +202547,7 @@ }, "path": [ { - "description": "The node id of node to be shut down", + "description": "The node identifier.\nThis parameter is not validated against the cluster's active nodes.\nThis enables you to register a node for shut down while it is offline.\nNo error is thrown if you specify an invalid node ID.", "name": "node_id", "required": true, "type": { @@ -202558,7 +202561,7 @@ ], "query": [ { - "description": "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.", + "description": "The period to wait for a connection to the master node.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "master_timeout", "required": false, "serverDefault": "30s", @@ -202571,7 +202574,7 @@ } }, { - "description": "Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.", + "description": "The period to wait for a response.\nIf no response is received before the timeout expires, the request fails and returns an error.", "name": "timeout", "required": false, "serverDefault": "30s", @@ -202584,7 +202587,7 @@ } } ], - "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L91" + "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L102" }, { "kind": "response", diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index af03e9641a..b5677e744c 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -359,6 +359,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 diff --git a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts b/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts index e84a7d7d28..8ef65ab252 100644 --- a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts +++ b/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: { diff --git a/specification/shutdown/delete_node/ShutdownDeleteNodeResponseExample1.yaml b/specification/shutdown/delete_node/ShutdownDeleteNodeResponseExample1.yaml new file mode 100644 index 0000000000..9c252fdbe6 --- /dev/null +++ b/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}" diff --git a/specification/shutdown/get_node/ShutdownGetNodeRequest.ts b/specification/shutdown/get_node/ShutdownGetNodeRequest.ts index e74fa31743..0cea4eb47b 100644 --- a/specification/shutdown/get_node/ShutdownGetNodeRequest.ts +++ b/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: { diff --git a/specification/shutdown/get_node/ShutdownGetNodeResponseExample1.yaml b/specification/shutdown/get_node/ShutdownGetNodeResponseExample1.yaml new file mode 100644 index 0000000000..88b99881ad --- /dev/null +++ b/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}" diff --git a/specification/shutdown/put_node/ShutdownPutNodeRequest.ts b/specification/shutdown/put_node/ShutdownPutNodeRequest.ts index 318f9128b5..c66c6dfbce 100644 --- a/specification/shutdown/put_node/ShutdownPutNodeRequest.ts +++ b/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 diff --git a/specification/shutdown/put_node/ShutdownPutNodeRequestExample1.yaml b/specification/shutdown/put_node/ShutdownPutNodeRequestExample1.yaml new file mode 100644 index 0000000000..ca9fb3d968 --- /dev/null +++ b/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}"