IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Node lifecycle APIs Get shutdown API »
Elastic Docs ›Elasticsearch Guide [7.15] ›REST APIs ›Node lifecycle APIs

Put shutdown API

edit

Put shutdown API

edit

This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

Prepares a node to be shut down.

Request

edit

PUT _nodes/<node-id>/shutdown

Prerequisites

edit

Description

edit

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 or remove. If a node is already being prepared for shutdown, you can use this API to change the shutdown type.

This API does NOT terminate the Elasticsearch process. Monitor the node shutdown status to determine when it is safe to stop Elasticsearch.

Path parameters

edit
<node-id>
(Required, string) The ID of the node you want to prepare for shutdown. If you specify a node that is offline, it will be prepared for shut down when it rejoins the cluster.

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.

Query parameters

edit
master_timeout
(Optional, time units) 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. Defaults to 30s.
timeout
(Optional, time units) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.

Request body

edit
type
(Required, string) Valid values are restart and remove. Use restart when you need to temporarily shut down a node to perform an upgrade, make configuration changes, or perform other maintenance. Because the node is expected to rejoin the cluster, data is not migrated off of the node. Use remove when you need to permanently remove a node from the cluster. The node is not marked ready for shutdown until data is migrated off of the node
reason
(Required, string) A human-readable reason that the node is being shut down. This field provides information for other cluster operators; it does not affect the shut down process.
allocation_delay
(Optional, string) Only valid if type is restart. Controls how long Elasticsearch will wait for the node to restart and join the cluster before reassigning its shards to other nodes. This works the same as delaying allocation with the index.unassigned.node_left.delayed_timeout setting. If you specify both a restart allocation delay and an index-level allocation delay, the longer of the two is used.

Examples

edit

Register a node for shutdown:

PUT /_nodes/USpTGYaBSIKbgSUJR2Z9lg/shutdown
{
  "type": "restart", 
  "reason": "Demonstrating how the node shutdown API works",
  "allocation_delay": "20m"
}

Prepares the node to be restarted. Use remove for nodes that will be permanently removed from the cluster.
« Node lifecycle APIs Get shutdown API »