From 8d90a7704610c1439ac38a541adf88e7b79df732 Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Mon, 17 Mar 2025 16:51:54 -0700 Subject: [PATCH] [DOCS] Add response examples to cluster allocation explain API (#3961) (cherry picked from commit 86162177b0591ee23e245277458739fefcd651d0) --- output/openapi/elasticsearch-openapi.json | 12 ++++++ output/schema/schema.json | 12 ++++++ ...sterAllocationExplainResponseExample1.yaml | 38 +++++++++++++++++ ...sterAllocationExplainResponseExample2.yaml | 42 +++++++++++++++++++ 4 files changed, 104 insertions(+) create mode 100644 specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample1.yaml create mode 100644 specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample2.yaml diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index bc83a152c8..177a9893ef 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -97941,6 +97941,18 @@ "primary", "shard" ] + }, + "examples": { + "ClusterAllocationExplainResponseExample1": { + "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.\n", + "value": "{\n \"index\" : \"my-index-000001\",\n \"shard\" : 0,\n \"primary\" : true,\n \"current_state\" : \"unassigned\",\n \"unassigned_info\" : {\n \"reason\" : \"INDEX_CREATED\",\n \"at\" : \"2017-01-04T18:08:16.600Z\",\n \"last_allocation_status\" : \"no\"\n },\n \"can_allocate\" : \"no\",\n \"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.\",\n \"node_allocation_decisions\" : [\n {\n \"node_id\" : \"8qt2rY-pT6KNZB3-hGfLnw\",\n \"node_name\" : \"node-0\",\n \"transport_address\" : \"127.0.0.1:9401\",\n \"roles\" : [\"data\", \"data_cold\", \"data_content\", \"data_frozen\", \"data_hot\", \"data_warm\", \"ingest\", \"master\", \"ml\", \"remote_cluster_client\", \"transform\"],\n \"node_attributes\" : {},\n \"node_decision\" : \"no\",\n \"weight_ranking\" : 1,\n \"deciders\" : [\n {\n \"decider\" : \"filter\",\n \"decision\" : \"NO\",\n \"explanation\" : \"node does not match index setting [index.routing.allocation.include] filters [_name:\\\"nonexistent_node\\\"]\"\n }\n ]\n }\n ]\n}" + }, + "ClusterAllocationExplainResponseExample2": { + "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.\n", + "value": "{\n \"index\" : \"my-index-000001\",\n \"shard\" : 0,\n \"primary\" : true,\n \"current_state\" : \"unassigned\",\n \"unassigned_info\" : {\n \"at\" : \"2017-01-04T18:03:28.464Z\",\n \"failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException\",\n \"reason\": \"ALLOCATION_FAILED\",\n \"failed_allocation_attempts\": 5,\n \"last_allocation_status\": \"no\",\n },\n \"can_allocate\": \"no\",\n \"allocate_explanation\": \"cannot allocate because allocation is not permitted to any of the nodes\",\n \"node_allocation_decisions\" : [\n {\n \"node_id\" : \"3sULLVJrRneSg0EfBB-2Ew\",\n \"node_name\" : \"node_t0\",\n \"transport_address\" : \"127.0.0.1:9400\",\n \"roles\" : [\"data_content\", \"data_hot\"],\n \"node_decision\" : \"no\",\n \"store\" : {\n \"matching_size\" : \"4.2kb\",\n \"matching_size_in_bytes\" : 4325\n },\n \"deciders\" : [\n {\n \"decider\": \"max_retry\",\n \"decision\" : \"NO\",\n \"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]]]\"\n }\n ]\n }\n ]\n}" + } } } } diff --git a/output/schema/schema.json b/output/schema/schema.json index 30b25830ad..2ea26a4265 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -111359,6 +111359,18 @@ } ] }, + "examples": { + "ClusterAllocationExplainResponseExample1": { + "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.\n", + "summary": "Conflicting settings", + "value": "{\n \"index\" : \"my-index-000001\",\n \"shard\" : 0,\n \"primary\" : true,\n \"current_state\" : \"unassigned\",\n \"unassigned_info\" : {\n \"reason\" : \"INDEX_CREATED\",\n \"at\" : \"2017-01-04T18:08:16.600Z\",\n \"last_allocation_status\" : \"no\"\n },\n \"can_allocate\" : \"no\",\n \"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.\",\n \"node_allocation_decisions\" : [\n {\n \"node_id\" : \"8qt2rY-pT6KNZB3-hGfLnw\",\n \"node_name\" : \"node-0\",\n \"transport_address\" : \"127.0.0.1:9401\",\n \"roles\" : [\"data\", \"data_cold\", \"data_content\", \"data_frozen\", \"data_hot\", \"data_warm\", \"ingest\", \"master\", \"ml\", \"remote_cluster_client\", \"transform\"],\n \"node_attributes\" : {},\n \"node_decision\" : \"no\",\n \"weight_ranking\" : 1,\n \"deciders\" : [\n {\n \"decider\" : \"filter\",\n \"decision\" : \"NO\",\n \"explanation\" : \"node does not match index setting [index.routing.allocation.include] filters [_name:\\\"nonexistent_node\\\"]\"\n }\n ]\n }\n ]\n}" + }, + "ClusterAllocationExplainResponseExample2": { + "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.\n", + "summary": "Maximum retries", + "value": "{\n \"index\" : \"my-index-000001\",\n \"shard\" : 0,\n \"primary\" : true,\n \"current_state\" : \"unassigned\",\n \"unassigned_info\" : {\n \"at\" : \"2017-01-04T18:03:28.464Z\",\n \"failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException\",\n \"reason\": \"ALLOCATION_FAILED\",\n \"failed_allocation_attempts\": 5,\n \"last_allocation_status\": \"no\",\n },\n \"can_allocate\": \"no\",\n \"allocate_explanation\": \"cannot allocate because allocation is not permitted to any of the nodes\",\n \"node_allocation_decisions\" : [\n {\n \"node_id\" : \"3sULLVJrRneSg0EfBB-2Ew\",\n \"node_name\" : \"node_t0\",\n \"transport_address\" : \"127.0.0.1:9400\",\n \"roles\" : [\"data_content\", \"data_hot\"],\n \"node_decision\" : \"no\",\n \"store\" : {\n \"matching_size\" : \"4.2kb\",\n \"matching_size_in_bytes\" : 4325\n },\n \"deciders\" : [\n {\n \"decider\": \"max_retry\",\n \"decision\" : \"NO\",\n \"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]]]\"\n }\n ]\n }\n ]\n}" + } + }, "name": { "name": "Response", "namespace": "cluster.allocation_explain" diff --git a/specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample1.yaml b/specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample1.yaml new file mode 100644 index 0000000000..d970908334 --- /dev/null +++ b/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\"]" + } + ] + } + ] + } diff --git a/specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample2.yaml b/specification/cluster/allocation_explain/examples/response/ClusterAllocationExplainResponseExample2.yaml new file mode 100644 index 0000000000..96c3a8c821 --- /dev/null +++ b/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]]]" + } + ] + } + ] + }