Clarify unassigned.reason docs (#81017) (#81120)

Today we indicate that the `unassigned.reason` field in various APIs
indicates the reason why a shard is unassigned. This isn't really true,
it tells you some information about the event that caused the shard to
_become_ unassigned (or which most recently changed its routing table
entry while remaining unassigned) but tells you almost nothing about why
the shard _is now_ unassigned and how to fix it. That's what the
allocation explain API is for. This commit clarifies this point in the
docs.

Closes #80892

Co-authored-by: James Rodewig <james.rodewig@elastic.co>

Co-authored-by: James Rodewig <james.rodewig@elastic.co>

Author: DaveCTurner

docs/reference/cat/shards.asciidoc

@@ -249,7 +249,9 @@ Time at which the shard became unassigned in
 Time (UTC)].
 
 `unassigned.details`, `ud`::
-Details about why the shard became unassigned.
+Details about why the shard became unassigned. This does not explain why the
+shard is currently unassigned. To understand why a shard is not assigned, use
+the <<cluster-allocation-explain>> API.
 
 `unassigned.for`, `uf`::
 Time at which the shard was requested to be unassigned in
@@ -258,16 +260,24 @@ Time (UTC)].
 
 [[reason-unassigned]]
 `unassigned.reason`, `ur`::
-Reason the shard is unassigned. Returned values are:
+Indicates the reason for the last change to the state of this unassigned shard.
+This does not explain why the shard is currently unassigned. To understand why
+a shard is not assigned, use the <<cluster-allocation-explain>> API. Returned
+values include:
 +
 * `ALLOCATION_FAILED`: Unassigned as a result of a failed allocation of the shard.
 * `CLUSTER_RECOVERED`: Unassigned as a result of a full cluster recovery.
 * `DANGLING_INDEX_IMPORTED`: Unassigned as a result of importing a dangling index.
 * `EXISTING_INDEX_RESTORED`: Unassigned as a result of restoring into a closed index.
+* `FORCED_EMPTY_PRIMARY`: The shard's allocation was last modified by forcing an empty primary using the <<cluster-reroute>> API.
+* `INDEX_CLOSED`: Unassigned because the index was closed.
 * `INDEX_CREATED`: Unassigned as a result of an API creation of an index.
 * `INDEX_REOPENED`: Unassigned as a result of opening a closed index.
+* `MANUAL_ALLOCATION`: The shard's allocation was last modified by the <<cluster-reroute>> API.
 * `NEW_INDEX_RESTORED`: Unassigned as a result of restoring into a new index.
 * `NODE_LEFT`: Unassigned as a result of the node hosting it leaving the cluster.
+* `NODE_RESTARTING`: Similar to `NODE_LEFT`, except that the node was registered as restarting using the <<node-lifecycle-api,Node shutdown API>>. 
+* `PRIMARY_FAILED`: The shard was initializing as a replica, but the primary shard failed before the initialization completed.
 * `REALLOCATED_REPLICA`: A better replica location is identified and causes the existing replica allocation to be cancelled.
 * `REINITIALIZED`: When a shard moves from started back to initializing.
 * `REPLICA_ADDED`: Unassigned as a result of explicit addition of a replica.

docs/reference/how-to/fix-common-cluster-issues.asciidoc

@@ -420,12 +420,11 @@ GET _cat/shards?v=true&h=index,shard,prirep,state,node,unassigned.reason&s=state
 ----
 
 Unassigned shards have a `state` of `UNASSIGNED`. The `prirep` value is `p` for
-primary shards and `r` for replicas. The `unassigned.reason` describes why the
-shard remains unassigned.
+primary shards and `r` for replicas.
 
-To get a more in-depth explanation of an unassigned shard's allocation status,
-use the <<cluster-allocation-explain,cluster allocation explanation API>>. You
-can often use details in the response to resolve the issue.
+To understand why an unassigned shard is not being assigned and what action
+you must take to allow {es} to assign it, use the
+<<cluster-allocation-explain,cluster allocation explanation API>>.
 
 [source,console]
 ----

server/src/main/java/org/elasticsearch/rest/action/cat/RestShardsAction.java

@@ -118,7 +118,7 @@ protected Table getTableWithHeader(final RestRequest request) {
 
         table.addCell("sync_id", "alias:sync_id;default:false;desc:sync id");
 
-        table.addCell("unassigned.reason", "alias:ur;default:false;desc:reason shard is unassigned");
+        table.addCell("unassigned.reason", "alias:ur;default:false;desc:reason shard became unassigned");
         table.addCell("unassigned.at", "alias:ua;default:false;desc:time shard became unassigned (UTC)");
         table.addCell("unassigned.for", "alias:uf;default:false;text-align:right;desc:time has been unassigned");
         table.addCell("unassigned.details", "alias:ud;default:false;desc:additional details as to why the shard became unassigned");