[Backport 8.x] [DOCS] Add response examples to cluster allocation explain API

specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample1.yaml

@@ -0,0 +1,38 @@
+summary: Conflicting settings
+description: >
+  An example of an allocation explanation for an unassigned primary shard.
+  In this example, a newly created index has an index setting that requires that it only be allocated to a node named `nonexistent_node`, which does not exist, so the index is unable to allocate.
+# type: response
+# response_code:
+value: |-
+  {
+    "index" : "my-index-000001",
+    "shard" : 0,
+    "primary" : true,
+    "current_state" : "unassigned",
+    "unassigned_info" : {
+      "reason" : "INDEX_CREATED",
+      "at" : "2017-01-04T18:08:16.600Z",
+      "last_allocation_status" : "no"
+    },
+    "can_allocate" : "no",
+    "allocate_explanation" : "Elasticsearch isn't allowed to allocate this shard to any of the nodes in the cluster. Choose a node to which you expect this shard to be allocated, find this node in the node-by-node explanation, and address the reasons which prevent Elasticsearch from allocating this shard there.",
+    "node_allocation_decisions" : [
+      {
+        "node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
+        "node_name" : "node-0",
+        "transport_address" : "127.0.0.1:9401",
+        "roles" : ["data", "data_cold", "data_content", "data_frozen", "data_hot", "data_warm", "ingest", "master", "ml", "remote_cluster_client", "transform"],
+        "node_attributes" : {},
+        "node_decision" : "no",
+        "weight_ranking" : 1,
+        "deciders" : [
+          {
+            "decider" : "filter",
+            "decision" : "NO",
+            "explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
+          }
+        ]
+      }
+    ]
+  }

specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample2.yaml

@@ -0,0 +1,42 @@
+summary: Maximum retries
+description: >
+  An example of an allocation explanation for an unassigned primary shard that has reached the maximum number of allocation retry attempts.
+  After the maximum number of retries is reached, Elasticsearch stops attempting to allocate the shard in order to prevent infinite retries which may impact cluster performance.
+# type: response
+# response_code:
+value: |-
+  {
+    "index" : "my-index-000001",
+    "shard" : 0,
+    "primary" : true,
+    "current_state" : "unassigned",
+    "unassigned_info" : {
+      "at" : "2017-01-04T18:03:28.464Z",
+      "failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException",
+      "reason": "ALLOCATION_FAILED",
+      "failed_allocation_attempts": 5,
+      "last_allocation_status": "no",
+    },
+    "can_allocate": "no",
+    "allocate_explanation": "cannot allocate because allocation is not permitted to any of the nodes",
+    "node_allocation_decisions" : [
+      {
+        "node_id" : "3sULLVJrRneSg0EfBB-2Ew",
+        "node_name" : "node_t0",
+        "transport_address" : "127.0.0.1:9400",
+        "roles" : ["data_content", "data_hot"],
+        "node_decision" : "no",
+        "store" : {
+          "matching_size" : "4.2kb",
+          "matching_size_in_bytes" : 4325
+        },
+        "deciders" : [
+          {
+            "decider": "max_retry",
+            "decision" : "NO",
+            "explanation": "shard has exceeded the maximum number of retries [5] on failed allocation attempts - manually call [POST /_cluster/reroute?retry_failed] to retry, [unassigned_info[[reason=ALLOCATION_FAILED], at[2024-07-30T21:04:12.166Z], failed_attempts[5], failed_nodes[[mEKjwwzLT1yJVb8UxT6anw]], delayed=false, details[failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException], allocation_status[deciders_no]]]"
+          }
+        ]
+      }
+    ]
+  }