Cluster allocation explain

Introduced 1.0

The most basic cluster allocation explain request finds an unassigned shard and explains why it can’t be allocated to a node.

If you add some options, you can instead get information on a specific shard, including why OpenSearch assigned it to its current node.

Path and HTTP methods

  1. GET _cluster/allocation/explain
  2. POST _cluster/allocation/explain

Query parameters

All parameters are optional.

ParameterTypeDescription
include_yes_decisionsBooleanOpenSearch makes a series of yes or no decisions when trying to allocate a shard to a node. If this parameter is true, OpenSearch includes the (generally more numerous) “yes” decisions in its response. Default is false.
include_disk_infoBooleanWhether to include information about disk usage in the response. Default is false.

Request body fields

All cluster allocation explain fields are optional.

FieldTypeDescription
current_nodeStringIf you only want an explanation if the shard happens to be on a particular node, specify that node name here.
indexStringThe name of the shard’s index.
primaryBooleanWhether to provide an explanation for the primary shard (true) or its first replica (false), which share the same shard ID.
shardIntegerThe shard ID that you want an explanation for.

Example request

  1. GET _cluster/allocation/explain?include_yes_decisions=true
  2. {
  3.   "index": "movies",
  4.   "shard": 0,
  5.   "primary": true
  6. }

copy

Example response

  1. {
  2.   "index": "movies",
  3.   "shard": 0,
  4.   "primary": true,
  5.   "current_state": "started",
  6.   "current_node": {
  7.     "id": "d8jRZcW1QmCBeVFlgOJx5A",
  8.     "name": "opensearch-node1",
  9.     "transport_address": "172.24.0.4:9300",
  10.     "weight_ranking": 1
  11.   },
  12.   "can_remain_on_current_node": "yes",
  13.   "can_rebalance_cluster": "yes",
  14.   "can_rebalance_to_other_node": "no",
  15.   "rebalance_explanation": "cannot rebalance as no target node exists that can both allocate this shard and improve the cluster balance",
  16.   "node_allocation_decisions": [{
  17.     "node_id": "vRxi4uPcRt2BtHlFoyCyTQ",
  18.     "node_name": "opensearch-node2",
  19.     "transport_address": "172.24.0.3:9300",
  20.     "node_decision": "no",
  21.     "weight_ranking": 1,
  22.     "deciders": [{
  23.         "decider": "max_retry",
  24.         "decision": "YES",
  25.         "explanation": "shard has no previous failures"
  26.       },
  27.       {
  28.         "decider": "replica_after_primary_active",
  29.         "decision": "YES",
  30.         "explanation": "shard is primary and can be allocated"
  31.       },
  32.       {
  33.         "decider": "enable",
  34.         "decision": "YES",
  35.         "explanation": "all allocations are allowed"
  36.       },
  37.       {
  38.         "decider": "node_version",
  39.         "decision": "YES",
  40.         "explanation": "can relocate primary shard from a node with version [1.0.0] to a node with equal-or-newer version [1.0.0]"
  41.       },
  42.       {
  43.         "decider": "snapshot_in_progress",
  44.         "decision": "YES",
  45.         "explanation": "no snapshots are currently running"
  46.       },
  47.       {
  48.         "decider": "restore_in_progress",
  49.         "decision": "YES",
  50.         "explanation": "ignored as shard is not being recovered from a snapshot"
  51.       },
  52.       {
  53.         "decider": "filter",
  54.         "decision": "YES",
  55.         "explanation": "node passes include/exclude/require filters"
  56.       },
  57.       {
  58.         "decider": "same_shard",
  59.         "decision": "NO",
  60.         "explanation": "a copy of this shard is already allocated to this node [[movies][0], node[vRxi4uPcRt2BtHlFoyCyTQ], [R], s[STARTED], a[id=x8w7QxWdQQa188HKGn0iMQ]]"
  61.       },
  62.       {
  63.         "decider": "disk_threshold",
  64.         "decision": "YES",
  65.         "explanation": "enough disk for shard on node, free: [35.9gb], shard size: [15.1kb], free after allocating shard: [35.9gb]"
  66.       },
  67.       {
  68.         "decider": "throttling",
  69.         "decision": "YES",
  70.         "explanation": "below shard recovery limit of outgoing: [0 < 2] incoming: [0 < 2]"
  71.       },
  72.       {
  73.         "decider": "shards_limit",
  74.         "decision": "YES",
  75.         "explanation": "total shard limits are disabled: [index: -1, cluster: -1] <= 0"
  76.       },
  77.       {
  78.         "decider": "awareness",
  79.         "decision": "YES",
  80.         "explanation": "allocation awareness is not enabled, set cluster setting [cluster.routing.allocation.awareness.attributes] to enable it"
  81.       }
  82.     ]
  83.   }]
  84. }