Cluster health

Introduced 1.0

The most basic cluster health request returns a simple status of the health of your cluster. OpenSearch expresses cluster health in three colors: green, yellow, and red. A green status means all primary shards and their replicas are allocated to nodes. A yellow status means all primary shards are allocated to nodes, but some replicas aren’t. A red status means at least one primary shard is not allocated to any node.

To get the status of a specific index, provide the index name.

Path and HTTP methods

  1. GET _cluster/health
  2. GET _cluster/health/<index>

Path parameters

The following table lists the available path parameters. All path parameters are optional.

ParameterData typeDescription
<index-name>StringLimits health reporting to a specific index. Can be a single index or a comma-separated list of index names.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

ParameterTypeDescription
expand_wildcardsEnumExpands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are all, open, closed, hidden, and none. Default is open.
levelEnumThe level of detail for returned health information. Supported values are cluster, indices, shards, and awareness_attributes. Default is cluster.
awareness_attributeStringThe name of the awareness attribute, for which to return cluster health (for example, zone). Applicable only if level is set to awareness_attributes.
localBooleanWhether to return information from the local node only instead of from the cluster manager node. Default is false.
cluster_manager_timeoutTimeThe amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
timeoutTimeThe amount of time to wait for a response. If the timeout expires, the request fails. Default is 30 seconds.
wait_for_active_shardsStringWait until the specified number of shards is active before returning a response. all for all shards. Default is 0.
wait_for_nodesStringWait for N number of nodes. Use 12 for exact match, >12 and <12 for range.
wait_for_eventsEnumWait until all currently queued events with the given priority are processed. Supported values are immediate, urgent, high, normal, low, and languid.
wait_for_no_relocating_shardsBooleanWhether to wait until there are no relocating shards in the cluster. Default is false.
wait_for_no_initializing_shardsBooleanWhether to wait until there are no initializing shards in the cluster. Default is false.
wait_for_statusEnumWait until the cluster health reaches the specified status or better. Supported values are green, yellow, and red.
weightsJSON objectAssigns weights to attributes within the request body of the PUT request. Weights can be set in any ration, for example, 2:3:5. In a 2:3:5 ratio with three zones, for every 100 requests sent to the cluster, each zone would receive either 20, 30, or 50 search requests in a random order. When assigned a weight of 0, the zone does not receive any search traffic.

Example requests

The following examples show how to use the cluster health API.

This request waits 50 seconds for the cluster to reach the yellow status or better:

  1. GET _cluster/health?wait_for_status=yellow&timeout=50s

copy

If the cluster health becomes yellow or green before 50 seconds elapse, it returns a response immediately. Otherwise it returns a response as soon as it exceeds the timeout.

The following example request retrieves cluster health for all indexes in the cluster:

  1. GET _cluster/health

copy

Example response

The response contains cluster health information:

  1. {
  2.   "cluster_name" : "opensearch-cluster",
  3.   "status" : "green",
  4.   "timed_out" : false,
  5.   "number_of_nodes" : 2,
  6.   "number_of_data_nodes" : 2,
  7.   "discovered_master" : true,
  8.   "active_primary_shards" : 6,
  9.   "active_shards" : 12,
  10.   "relocating_shards" : 0,
  11.   "initializing_shards" : 0,
  12.   "unassigned_shards" : 0,
  13.   "delayed_unassigned_shards" : 0,
  14.   "number_of_pending_tasks" : 0,
  15.   "number_of_in_flight_fetch" : 0,
  16.   "task_max_waiting_in_queue_millis" : 0,
  17.   "active_shards_percent_as_number" : 100.0
  18. }

Response body fields

The following table lists all response fields.

FieldData typeDescription
cluster_nameStringThe name of the cluster.
statusStringThe cluster health status, which represents the state of shard allocation in the cluster. May be green, yellow, or red.
number_of_nodesIntegerThe number of nodes in the cluster.
number_of_data_nodesIntegerThe number of data nodes in the cluster.
discovered_cluster_managerBooleanSpecifies whether the cluster manager is discovered.
active_primary_shardsIntegerThe number of active primary shards.
active_shardsIntegerThe total number of active shards, including primary and replica shards.
relocating_shardsIntegerThe number of relocating shards.
initializing_shardsIntegerThe number of initializing shards.
unassigned_shardsIntegerThe number of unassigned shards.
delayed_unassigned_shardsIntegerThe number of delayed unassigned shards.
number_of_pending_tasksIntegerThe number of pending tasks in the cluster.
number_of_in_flight_fetchIntegerThe number of unfinished fetches.
task_max_waiting_in_queue_millisIntegerThe maximum wait time for all tasks waiting to be performed, in milliseconds.
active_shards_percent_as_numberDoubleThe percentage of active shards in the cluster.
awareness_attributesObjectContains cluster health information for each awareness attribute.

Returning cluster health by awareness attribute

To check cluster health by awareness attribute (for example, zone or rack), specify awareness_attributes in the level query parameter:

  1. GET _cluster/health?level=awareness_attributes

copy

The response contains cluster health metrics partitioned by awareness attribute:

  1. {
  2.   "cluster_name": "runTask",
  3.   "status": "green",
  4.   "timed_out": false,
  5.   "number_of_nodes": 3,
  6.   "number_of_data_nodes": 3,
  7.   "discovered_master": true,
  8.   "discovered_cluster_manager": true,
  9.   "active_primary_shards": 0,
  10.   "active_shards": 0,
  11.   "relocating_shards": 0,
  12.   "initializing_shards": 0,
  13.   "unassigned_shards": 0,
  14.   "delayed_unassigned_shards": 0,
  15.   "number_of_pending_tasks": 0,
  16.   "number_of_in_flight_fetch": 0,
  17.   "task_max_waiting_in_queue_millis": 0,
  18.   "active_shards_percent_as_number": 100,
  19.   "awareness_attributes": {
  20.     "zone": {
  21.       "zone-3": {
  22.         "active_shards": 0,
  23.         "initializing_shards": 0,
  24.         "relocating_shards": 0,
  25.         "unassigned_shards": 0,
  26.         "data_nodes": 1,
  27.         "weight": 1
  28.       },
  29.       "zone-1": {
  30.         "active_shards": 0,
  31.         "initializing_shards": 0,
  32.         "relocating_shards": 0,
  33.         "unassigned_shards": 0,
  34.         "data_nodes": 1,
  35.         "weight": 1
  36.       },
  37.       "zone-2": {
  38.         "active_shards": 0,
  39.         "initializing_shards": 0,
  40.         "relocating_shards": 0,
  41.         "unassigned_shards": 0,
  42.         "data_nodes": 1,
  43.         "weight": 1
  44.       }
  45.     },
  46.     "rack": {
  47.       "rack-3": {
  48.         "active_shards": 0,
  49.         "initializing_shards": 0,
  50.         "relocating_shards": 0,
  51.         "unassigned_shards": 0,
  52.         "data_nodes": 1,
  53.         "weight": 1
  54.       },
  55.       "rack-1": {
  56.         "active_shards": 0,
  57.         "initializing_shards": 0,
  58.         "relocating_shards": 0,
  59.         "unassigned_shards": 0,
  60.         "data_nodes": 1,
  61.         "weight": 1
  62.       },
  63.       "rack-2": {
  64.         "active_shards": 0,
  65.         "initializing_shards": 0,
  66.         "relocating_shards": 0,
  67.         "unassigned_shards": 0,
  68.         "data_nodes": 1,
  69.         "weight": 1
  70.       }
  71.     }
  72.   }
  73. }

If you’re interested in a particular awareness attribute, you can include the name of the awareness attribute as a query parameter:

  1. GET _cluster/health?level=awareness_attributes&awareness_attribute=zone

copy

In response to the preceding request, OpenSearch returns cluster health information only for the zone awareness attribute.

The unassigned shard information will be accurate only if you enable replica count enforcement and configure forced awareness for the awareness attribute either before cluster start or after cluster start but before any indexing requests. If you enable replica enforcement after the cluster receives indexing requests, the unassigned shard information may be inaccurate. If you don’t configure replica count enforcement and forced awareness, the unassigned_shards field will contain -1.

Required permissions

If you use the Security plugin, make sure you have the appropriate permissions: cluster:monitor/health.