Shard assignment places an Elasticsearch shard on an available cluster node. Elasticsearch balances primary shards across nodes and keeps replica copies away from their partners. section 14.1.2 section 15.3.2
Balancing shards across nodes
With five nodes and an index containing ten shards, Elasticsearch can assign two shards to each node. Replicas are balanced similarly, but never placed on the same node as their primary shard. A single-node cluster therefore remains YELLOW when replicas cannot be assigned. section 14.1.2 section 15.3.2
An unassigned shard has no eligible node. This can occur when a cluster is too small for replicas, when nodes fail during rebalancing, or when allocation deciders reject placement because of constraints such as disk watermarks. Existing indexes may halt searches and writes; new indexes may pause writes. section 14.1.2 section 15.3.2
Explain an unassigned shard
GET _cluster/allocation/explain { "index": "programming_books2", "shard": 0, "primary": true, "current_node": "mkmac.local" } The response reports the current state and allocation decisions. A same_shard decision can reject placing a copy beside its partner, while disk_threshold can reject a node above its configured low watermark. section 15.3.2
Listing 14.2 Asking the cluster for a shard failure explanation
GET _cluster/allocation/explain
{
"index": "chats",
"shard": 0,
"primary": false
}
Use the allocation explanation request to inspect why a specific primary or replica shard remains unassigned. section 14.1.2
