cluster-decommission.md

layout	title	nav_order	parent	has_children	redirect_from	canonical_url
default	Cluster decommission	30	Cluster APIs	false	/api-reference/cluster-decommission/ /opensearch/rest-api/cluster-decommission/	https://opensearch.org/docs/latest/api-reference/cluster-api/cluster-decommission/

Cluster decommission

Introduced 1.0 {: .label .label-purple }

The cluster decommission operation adds support decommissioning based on awareness. It greatly benefits multi-zone deployments, where awareness attributes, such as zones, can aid in applying new upgrades to a cluster in a controlled fashion. This is especially useful during outages, in which case, you can decommission the unhealthy zone to prevent replication requests from stalling and prevent your request backlog from becoming too large.

For more information about allocation awareness, see Shard allocation awareness.

Path and HTTP methods

PUT  /_cluster/decommission/awareness/{awareness_attribute_name}/{awareness_attribute_value}
GET  /_cluster/decommission/awareness/{awareness_attribute_name}/_status
DELETE /_cluster/decommission/awareness

Path parameters

Parameter	Type	Description
awareness_attribute_name	String	The name of awareness attribute, usually zone.
awareness_attribute_value	String	The value of the awareness attribute. For example, if you have shards allocated in two different zones, you can give each zone a value of zone-a or zoneb. The cluster decommission operation decommissions the zone listed in the method.

Example requests

Decommissioning and recommissioning a zone

You can use the following example requests to decommission and recommission a zone:

The following example request decommissions zone-a:

PUT /_cluster/decommission/awareness/<zone>/<zone-a>

{% include copy-curl.html %}

If you want to recommission a decommissioned zone, you can use the DELETE method:

DELETE /_cluster/decommission/awareness

{% include copy-curl.html %}

Getting zone decommission status

The following example requests returns the decommission status of all zones.

GET /_cluster/decommission/awareness/zone/_status

{% include copy-curl.html %}

Example responses

The following example response shows a successful zone decommission:

{
      "acknowledged": true
}

Getting zone decommission status

The following example response returns the decommission status of all zones:

{
     "zone-1": "INIT | DRAINING | IN_PROGRESS | SUCCESSFUL | FAILED"
}

Next steps

• For more information about zone awareness and weight, see Cluster awareness.
• For more information about allocation awareness, see Cluster formation.