From 0a8b60a595343387b55a78e8cf0049b3964034e4 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 16 Dec 2024 17:17:50 -0800 Subject: [PATCH] [DOCS] Edit node lifecycle summaries (#3309) --- output/openapi/elasticsearch-openapi.json | 16 ++++----- output/schema/schema.json | 33 ++++++++++++++----- .../delete_node/ShutdownDeleteNodeRequest.ts | 10 ++++++ .../get_node/ShutdownGetNodeRequest.ts | 9 +++++ .../put_node/ShutdownPutNodeRequest.ts | 15 +++++++++ 5 files changed, 66 insertions(+), 17 deletions(-) diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 806a29b60c..ce5940e0ac 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -30933,8 +30933,8 @@ "tags": [ "shutdown" ], - "summary": "Retrieve status of a node or nodes that are currently marked as shutting down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Get the shutdown status", + "description": "Get 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.", "operationId": "shutdown-get-node-1", "parameters": [ { @@ -30958,8 +30958,8 @@ "tags": [ "shutdown" ], - "summary": "Adds a node to be shut down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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.", "operationId": "shutdown-put-node", "parameters": [ { @@ -31043,8 +31043,8 @@ "tags": [ "shutdown" ], - "summary": "Removes a node from the shutdown list", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Cancel node shutdown preparations", + "description": "Remove 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.", "operationId": "shutdown-delete-node", "parameters": [ { @@ -31099,8 +31099,8 @@ "tags": [ "shutdown" ], - "summary": "Retrieve status of a node or nodes that are currently marked as shutting down", - "description": "Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "summary": "Get the shutdown status", + "description": "Get 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.", "operationId": "shutdown-get-node", "parameters": [ { diff --git a/output/schema/schema.json b/output/schema/schema.json index 314dc8f689..c3d734e4c5 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -17686,9 +17686,14 @@ "stability": "stable" } }, - "description": "Removes a node from the shutdown list. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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", "name": "shutdown.delete_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.delete_node" @@ -17720,9 +17725,14 @@ "stability": "stable" } }, - "description": "Retrieve status of a node or nodes that are currently marked as shutting down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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", "name": "shutdown.get_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.get_node" @@ -17760,9 +17770,14 @@ "stability": "stable" } }, - "description": "Adds a node to be shut down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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", "name": "shutdown.put_node", + "privileges": { + "cluster": [ + "manage" + ] + }, "request": { "name": "Request", "namespace": "shutdown.put_node" @@ -199980,7 +199995,7 @@ "body": { "kind": "no_body" }, - "description": "Removes a node from the shutdown list. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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.", "inherits": { "type": { "name": "RequestBase", @@ -200033,7 +200048,7 @@ } } ], - "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L44" + "specLocation": "shutdown/delete_node/ShutdownDeleteNodeRequest.ts#L24-L54" }, { "kind": "response", @@ -200210,7 +200225,7 @@ "body": { "kind": "no_body" }, - "description": "Retrieve status of a node or nodes that are currently marked as shutting down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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.", "inherits": { "type": { "name": "RequestBase", @@ -200263,7 +200278,7 @@ } } ], - "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L44" + "specLocation": "shutdown/get_node/ShutdownGetNodeRequest.ts#L24-L53" }, { "kind": "response", @@ -200409,7 +200424,7 @@ } ] }, - "description": "Adds a node to be shut down. Designed for indirect use by ECE/ESS and ECK. Direct use is not supported.", + "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.", "inherits": { "type": { "name": "RequestBase", @@ -200462,7 +200477,7 @@ } } ], - "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L76" + "specLocation": "shutdown/put_node/ShutdownPutNodeRequest.ts#L25-L91" }, { "kind": "response", diff --git a/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts b/specification/shutdown/delete_node/ShutdownDeleteNodeRequest.ts index 25df4239a5..e84a7d7d28 100644 --- 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 index 63fed84660..e74fa31743 100644 --- 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 index 6ab62d3eb5..318f9128b5 100644 --- 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: {