root
/
elasticsearch
mirror of https://github.com/elastic/elasticsearch.git
1
0
Fork 0
Code Issues Actions 1 Packages Projects Releases Wiki Activity
elasticsearch/docs/reference/cluster/allocation-explain.asciidoc

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

339 lines
11 KiB
Plaintext
Raw Normal View History

Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[[cluster-allocation-explain]]
[DOCS] Sort cluster API docs alphabetically (#48198)
2019-10-23 01:27:31 +08:00
=== Cluster allocation explain API
++++
<titleabbrev>Cluster allocation explain</titleabbrev>
++++
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
Provides an explanation for a shard's current allocation.
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
[source,console]
----
GET _cluster/allocation/explain
{
"index": "my-index-000001",
"shard": 0,
"primary": false,
"current_node": "my-node"
}
----
// TEST[setup:my_index]
// TEST[s/"primary": false,/"primary": false/]
// TEST[s/"current_node": "my-node"//]
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
[[cluster-allocation-explain-api-request]]
==== {api-request-title}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
`GET _cluster/allocation/explain`
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
Clarify allocation explain if random shard chosen (#75670) Today we often encounter users that are confused by the behaviour of calling `GET _cluster/allocation/explain` without a body: it _seems_ to work, but it explains a random shard, and if this isn't the shard they're thinking of then it's unclear how to proceed. With this commit we add a note to the response when a shard was randomly chosen indicating that it is possible, and possibly useful, to explain a different shard. We also adjust the exception message in the case when all shards are assigned to indicate why it's an invalid request and what to do to make it valid.
2021-08-02 22:14:09 +08:00
`POST _cluster/allocation/explain`
[DOCS] Add security privileges to cluster API docs (#67589)
2021-01-19 23:18:59 +08:00
[[cluster-allocation-explain-api-prereqs]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
[[cluster-allocation-explain-api-desc]]
==== {api-description-title}
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
The purpose of the cluster allocation explain API is to provide
[DOCS] Fix double spaces (#71082)
2021-03-31 21:57:47 +08:00
explanations for shard allocations in the cluster. For unassigned shards,
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
the explain API provides an explanation for why the shard is unassigned.
For assigned shards, the explain API provides an explanation for why the
Fix typo in allocation explain API docs This commit addresses a simple typo in the application explain API docs. Relates #23669
2017-03-21 20:36:54 +08:00
shard is remaining on its current node and has not moved or rebalanced to
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
another node. This API can be very useful when attempting to diagnose why a
shard is unassigned or why a shard continues to remain on its current node when
you might expect otherwise.
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
[[cluster-allocation-explain-api-query-params]]
==== {api-query-parms-title}
`include_disk_info`::
[DOCS] Fix case for 'Boolean' (#64299)
2020-10-29 21:04:43 +08:00
(Optional, Boolean) If `true`, returns information about disk usage and
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
shard sizes. Defaults to `false`.
`include_yes_decisions`::
[DOCS] Fix case for 'Boolean' (#64299)
2020-10-29 21:04:43 +08:00
(Optional, Boolean) If `true`, returns 'YES' decisions in explanation.
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
Defaults to `false`.
[DOCS] Mark cluster allocation explain API as experimental in docs
2016-09-07 01:29:33 +08:00
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
[[cluster-allocation-explain-api-request-body]]
==== {api-request-body-title}
`current_node`::
(Optional, string) Specifies the node ID or the name of the node to only
explain a shard that is currently located on the specified node.
`index`::
(Optional, string) Specifies the name of the index that you would like an
explanation for.
`primary`::
[DOCS] Fix case for 'Boolean' (#64299)
2020-10-29 21:04:43 +08:00
(Optional, Boolean) If `true`, returns explanation for the primary shard
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
for the given shard ID.
`shard`::
(Optional, integer) Specifies the ID of the shard that you would like an
explanation for.
[[cluster-allocation-explain-api-examples]]
==== {api-examples-title}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
===== Unassigned primary shard
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
The following request gets an allocation explanation for an unassigned primary
shard.
[DOCS] Use same index in Cluster Allocation Explain docs (#50936) Updates several example snippets in the Cluster Allocation Explain API docs to consistently use the `my_index` index. Previously, the snippets switches from `my_index` to `idx`, which could confuse users. Co-authored-by: Emmanuel DEMEY <demey.emmanuel@gmail.com> Co-authored-by: Emmanuel DEMEY <demey.emmanuel@gmail.com>
2020-01-16 22:13:31 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
////
[DOCS] [2 of 5] Change // CONSOLE comments to [source,console] (#46353)
2019-09-10 01:13:41 +08:00
[source,console]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
PUT my-index-000001?master_timeout=1s&timeout=1s
Allocate newly created indices on data_hot tier nodes (#61342) This commit adds the functionality to allocate newly created indices on nodes in the "hot" tier by default when they are created. This does not break existing behavior, as nodes with the `data` role are considered to be part of the hot tier. Users that separate their deployments by using the `data_hot` (and `data_warm`, `data_cold`, `data_frozen`) roles will have their data allocated on the hot tier nodes now by default. This change is a little more complicated than changing the default value for `index.routing.allocation.include._tier` from null to "data_hot". Instead, this adds the ability to have a plugin inject a setting into the builder for a newly created index. This has the benefit of allowing this setting to be visible as part of the settings when retrieving the index, for example: ``` // Create an index PUT /eggplant // Get an index GET /eggplant?flat_settings ``` Returns the default settings now of: ```json { "eggplant" : { "aliases" : { }, "mappings" : { }, "settings" : { "index.creation_date" : "1597855465598", "index.number_of_replicas" : "1", "index.number_of_shards" : "1", "index.provided_name" : "eggplant", "index.routing.allocation.include._tier" : "data_hot", "index.uuid" : "6ySG78s9RWGystRipoBFCA", "index.version.created" : "8000099" } } } ``` After the initial setting of this setting, it can be treated like any other index level setting. This new setting is *not* set on a new index if any of the following is true: - The index is created with an `index.routing.allocation.include.<anything>` setting - The index is created with an `index.routing.allocation.exclude.<anything>` setting - The index is created with an `index.routing.allocation.require.<anything>` setting - The index is created with a null `index.routing.allocation.include._tier` value - The index was created from an existing source metadata (shrink, clone, split, etc) Relates to #60848
2020-08-28 02:51:12 +08:00
{
"settings": {
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
"index.routing.allocation.include._name": "nonexistent_node",
Add index.routing.allocation.prefer._tier setting (#62589) This commit adds the `index.routing.allocation.prefer._tier` setting to the `DataTierAllocationDecider`. This special-purpose allocation setting lets a user specify a preference-based list of tiers for an index to be assigned to. For example, if the setting were set to: ``` "index.routing.allocation.prefer._tier": "data_hot,data_warm,data_content" ``` If the cluster contains any nodes with the `data_hot` role, the decider will only allow them to be allocated on the `data_hot` node(s). If there are no `data_hot` nodes, but there are `data_warm` and `data_content` nodes, then the index will be allowed to be allocated on `data_warm` nodes. This allows us to specify an index's preference for tier(s) without causing the index to be unassigned if no nodes of a preferred tier are available. Subsequent work will change the ILM migration to make additional use of this setting. Relates to #60848
2020-09-19 04:49:59 +08:00
"index.routing.allocation.include._tier_preference": null
Allocate newly created indices on data_hot tier nodes (#61342) This commit adds the functionality to allocate newly created indices on nodes in the "hot" tier by default when they are created. This does not break existing behavior, as nodes with the `data` role are considered to be part of the hot tier. Users that separate their deployments by using the `data_hot` (and `data_warm`, `data_cold`, `data_frozen`) roles will have their data allocated on the hot tier nodes now by default. This change is a little more complicated than changing the default value for `index.routing.allocation.include._tier` from null to "data_hot". Instead, this adds the ability to have a plugin inject a setting into the builder for a newly created index. This has the benefit of allowing this setting to be visible as part of the settings when retrieving the index, for example: ``` // Create an index PUT /eggplant // Get an index GET /eggplant?flat_settings ``` Returns the default settings now of: ```json { "eggplant" : { "aliases" : { }, "mappings" : { }, "settings" : { "index.creation_date" : "1597855465598", "index.number_of_replicas" : "1", "index.number_of_shards" : "1", "index.provided_name" : "eggplant", "index.routing.allocation.include._tier" : "data_hot", "index.uuid" : "6ySG78s9RWGystRipoBFCA", "index.version.created" : "8000099" } } } ``` After the initial setting of this setting, it can be treated like any other index level setting. This new setting is *not* set on a new index if any of the following is true: - The index is created with an `index.routing.allocation.include.<anything>` setting - The index is created with an `index.routing.allocation.exclude.<anything>` setting - The index is created with an `index.routing.allocation.require.<anything>` setting - The index is created with a null `index.routing.allocation.include._tier` value - The index was created from an existing source metadata (shrink, clone, split, etc) Relates to #60848
2020-08-28 02:51:12 +08:00
}
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
////
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
[source,console]
----
GET _cluster/allocation/explain
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index": "my-index-000001",
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
"shard": 0,
"primary": true
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
// TEST[continued]
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
The API response indicates the shard can only be allocated to a nonexistent
node.
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[DOCS] [5 of 5] Change // TESTRESPONSE comments to [source,console-results] (#46449)
2019-09-07 02:05:36 +08:00
[source,console-result]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index" : "my-index-000001",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"shard" : 0,
"primary" : true,
"current_state" : "unassigned", <1>
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
"unassigned_info" : {
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"reason" : "INDEX_CREATED", <2>
"at" : "2017-01-04T18:08:16.600Z",
"last_allocation_status" : "no"
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
},
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"can_allocate" : "no", <3>
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
"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.",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"node_allocation_decisions" : [
{
"node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
"node_name" : "node-0",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"transport_address" : "127.0.0.1:9401",
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
"node_attributes" : {},
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"node_decision" : "no", <4>
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter", <5>
"decision" : "NO",
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]" <6>
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
}
]
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
}
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
]
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
// TESTRESPONSE[s/"at" : "[^"]*"/"at" : $body.$_path/]
// TESTRESPONSE[s/"node_id" : "[^"]*"/"node_id" : $body.$_path/]
// TESTRESPONSE[s/"transport_address" : "[^"]*"/"transport_address" : $body.$_path/]
// TESTRESPONSE[s/"node_attributes" : \{\}/"node_attributes" : $body.$_path/]
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
<1> The current state of the shard.
<2> The reason for the shard originally becoming unassigned.
<3> Whether to allocate the shard.
<4> Whether to allocate the shard to the particular node.
<5> The decider which led to the `no` decision for the node.
<6> An explanation as to why the decider returned a `no` decision, with a helpful hint pointing to the setting that led to the decision.
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
The following response contains an allocation explanation for an unassigned
primary shard that was previously allocated.
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[source,js]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index" : "my-index-000001",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"shard" : 0,
"primary" : true,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "NODE_LEFT",
"at" : "2017-01-04T18:03:28.464Z",
"details" : "node_left[OIWe8UhhThCK0V5XfmdrmQ]",
"last_allocation_status" : "no_valid_shard_copy"
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
},
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"can_allocate" : "no_valid_shard_copy",
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
"allocate_explanation" : "Elasticsearch can't allocate this shard because there are no copies of its data in the cluster. Elasticsearch will allocate this shard when a node holding a good copy of its data joins the cluster. If no such node is available, restore this index from a recent snapshot."
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
// NOTCONSOLE
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
===== Unassigned replica shard
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
The following response contains an allocation explanation for a replica that's
unassigned due to <<delayed-allocation,delayed allocation>>.
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[source,js]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index" : "my-index-000001",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"shard" : 0,
"primary" : false,
"current_state" : "unassigned",
"unassigned_info" : {
"reason" : "NODE_LEFT",
"at" : "2017-01-04T18:53:59.498Z",
"details" : "node_left[G92ZwuuaRY-9n8_tc-IzEg]",
"last_allocation_status" : "no_attempt"
},
"can_allocate" : "allocation_delayed",
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
"allocate_explanation" : "The node containing this shard copy recently left the cluster. Elasticsearch is waiting for it to return. If the node does not return within [%s] then Elasticsearch will allocate this shard to another node. Please wait.",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"configured_delay" : "1m", <1>
"configured_delay_in_millis" : 60000,
"remaining_delay" : "59.8s", <2>
"remaining_delay_in_millis" : 59824,
"node_allocation_decisions" : [
{
"node_id" : "pmnHu_ooQWCPEFobZGbpWw",
"node_name" : "node_t2",
"transport_address" : "127.0.0.1:9402",
"node_decision" : "yes"
},
{
"node_id" : "3sULLVJrRneSg0EfBB-2Ew",
"node_name" : "node_t0",
"transport_address" : "127.0.0.1:9400",
"node_decision" : "no",
"store" : { <3>
"matching_size" : "4.2kb",
"matching_size_in_bytes" : 4325
},
"deciders" : [
{
"decider" : "same_shard",
"decision" : "NO",
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"explanation" : "a copy of this shard is already allocated to this node [[my-index-000001][0], node[3sULLVJrRneSg0EfBB-2Ew], [P], s[STARTED], a[id=eV9P8BN1QPqRc3B4PLx6cg]]"
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
}
]
}
]
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
// NOTCONSOLE
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
<1> The configured delay before allocating a replica shard that does not exist due to the node holding it leaving the cluster.
<2> The remaining delay before allocating the replica shard.
<3> Information about the shard data found on a node.
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
===== Assigned shard
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
The following response contains an allocation explanation for an assigned shard.
The response indicates the shard is not allowed to remain on its current node
and must be reallocated.
Add API to explain why a shard is or isn't assigned This adds a new `/_cluster/allocation/explain` API that explains why a shard can or cannot be allocated to nodes in the cluster. Additionally, it will show where the master *desires* to put the shard, according to the `ShardsAllocator`. It looks like this: ``` GET /_cluster/allocation/explain?pretty { "index": "only-foo", "shard": 0, "primary": false } ``` Though, you can optionally send an empty body, which means "explain the allocation for the first unassigned shard you find". The output when a shard is unassigned looks like this: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : false }, "assigned" : false, "unassigned_info" : { "reason" : "INDEX_CREATED", "at" : "2016-03-22T20:04:23.620Z" }, "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 0.06666675, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "NO", "weight" : -1.3833332, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 2.3166666, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` And when the shard *is* assigned, the output looks like: ``` { "shard" : { "index" : "only-foo", "index_uuid" : "KnW0-zELRs6PK84l0r38ZA", "id" : 0, "primary" : true }, "assigned" : true, "assigned_node_id" : "Qc6VL8c5RWaw1qXZ0Rg57g", "nodes" : { "V-Spi0AyRZ6ZvKbaI3691w" : { "node_name" : "Susan Storm", "node_attributes" : { "bar" : "baz" }, "final_decision" : "NO", "weight" : 1.4499999, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] }, "Qc6VL8c5RWaw1qXZ0Rg57g" : { "node_name" : "Slipstream", "node_attributes" : { "bar" : "baz", "foo" : "bar" }, "final_decision" : "CURRENTLY_ASSIGNED", "weight" : 0.0, "decisions" : [ { "decider" : "same_shard", "decision" : "NO", "explanation" : "the shard cannot be allocated on the same node id [Qc6VL8c5RWaw1qXZ0Rg57g] on which it already exists" } ] }, "PzdyMZGXQdGhqTJHF_hGgA" : { "node_name" : "The Symbiote", "node_attributes" : { }, "final_decision" : "NO", "weight" : 3.6999998, "decisions" : [ { "decider" : "filter", "decision" : "NO", "explanation" : "node does not match index include filters [foo:\"bar\"]" } ] } } } ``` Only "NO" decisions are returned by default, but all decisions can be shown by specifying the `?include_yes_decisions=true` parameter in the request. Resolves #14593
2016-02-27 04:21:36 +08:00
[source,js]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index" : "my-index-000001",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"shard" : 0,
"primary" : true,
"current_state" : "started",
"current_node" : {
"id" : "8lWJeJ7tSoui0bxrwuNhTA",
"name" : "node_t1",
"transport_address" : "127.0.0.1:9401"
},
"can_remain_on_current_node" : "no", <1>
"can_remain_decisions" : [ <2>
{
"decider" : "filter",
"decision" : "NO",
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
}
],
"can_move_to_other_node" : "no", <3>
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
"move_explanation" : "This shard may not remain on its current node, but Elasticsearch isn't allowed to move it to another node. 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.",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"node_allocation_decisions" : [
{
"node_id" : "_P8olZS8Twax9u6ioN-GGA",
"node_name" : "node_t0",
"transport_address" : "127.0.0.1:9400",
"node_decision" : "no",
"weight_ranking" : 1,
"deciders" : [
{
"decider" : "filter",
"decision" : "NO",
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
"explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
}
]
}
]
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
// NOTCONSOLE
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
<1> Whether the shard is allowed to remain on its current node.
<2> The deciders that factored into the decision of why the shard is not allowed to remain on its current node.
<3> Whether the shard is allowed to be allocated to another node.
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
The following response contains an allocation explanation for a shard that must
remain on its current node. Moving the shard to another node would not improve
cluster balance.
Expose the ClusterInfo object in the allocation explain output This adds an optional parameter to the cluster allocation explain API that will return the cluster info object, `include_disk_info`, the output looks like: GET /_cluster/allocation/explain?include_disk_info -d' {"index": "i", "shard": 0, "primary": false}' { ... other info ... "cluster_info" : { "nodes" : { "7Uws-vL7R6WVm3ZwQA1n5A" : { "node_name" : "Kraven the Hunter", "least_available" : { "path" : "/path/to/data1", "total_bytes" : 165999570944, "used_bytes" : 118180614144, "free_bytes" : 47818956800, "free_disk_percent" : 28.80667493781158, "used_disk_percent" : 71.19332506218842 }, "most_available" : { "path" : "/path/to/data2", "total_bytes" : 165999570944, "used_bytes" : 118180614144, "free_bytes" : 47818956800, "free_disk_percent" : 28.80667493781158, "used_disk_percent" : 71.19332506218842 } } }, "shard_sizes" : { "[i][2][p]_bytes" : 0, "[i][4][p]_bytes" : 130, "[i][1][p]_bytes" : 0, "[i][3][p]_bytes" : 0, "[i][0][p]_bytes" : 130 }, "shard_paths" : { "[i][3], node[7Uws-vL7R6WVm3ZwQA1n5A], [P], s[STARTED], a[id=LegZLDniTVaw0Y1urv7s3g]" : "/path/to/data1/nodes/0", "[i][1], node[7Uws-vL7R6WVm3ZwQA1n5A], [P], s[STARTED], a[id=lAU_4vf_SKmoRdtg0ACnjQ]" : "/path/to/data1/nodes/0", "[i][2], node[7Uws-vL7R6WVm3ZwQA1n5A], [P], s[STARTED], a[id=Aurpeuj7SeGeyPDDpCtRgg]" : "/path/to/data1/nodes/0", "[i][0], node[7Uws-vL7R6WVm3ZwQA1n5A], [P], s[STARTED], a[id=Vgg8GlQTQ82C2j6HYBq8DQ]" : "/path/to/data1/nodes/0", "[i][4], node[7Uws-vL7R6WVm3ZwQA1n5A], [P], s[STARTED], a[id=t8hQlVSxQe-58fSeaXcAqg]" : "/path/to/data1/nodes/0" } } } Resolves #14405
2016-06-24 05:05:39 +08:00
[source,js]
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
{
[DOCS] Update my-index examples (#60132) Changes the following example index names to `my-index-000001` for consistency: * `my-index` * `my_index` * `myindex`
2020-07-28 02:46:39 +08:00
"index" : "my-index-000001",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"shard" : 0,
"primary" : true,
"current_state" : "started",
"current_node" : {
"id" : "wLzJm4N4RymDkBYxwWoJsg",
"name" : "node_t0",
"transport_address" : "127.0.0.1:9400",
"weight_ranking" : 1
},
"can_remain_on_current_node" : "yes",
"can_rebalance_cluster" : "yes", <1>
"can_rebalance_to_other_node" : "no", <2>
Make allocation explanations more actionable (#83983) The cluster allocation explain API includes a top-level status indicating to the user whether the shard can be assigned/rebalanced/etc or not. Today this status is fairly terse and experience shows that users sometimes struggle to understand how to interpret it and to decide on follow-up actions. This commit makes the top-level explanation more detailed and actionable. For instance, in the cases like `THROTTLED` where the status is transient we instruct the user to wait; if a shard is lost we say to restore it from a snapshot; if a shard cannot be assigned we say to choose a specific node where its assignment is expected and to address the obstacles. Co-authored-by: James Rodewig <james.rodewig@elastic.co>
2022-02-22 17:23:01 +08:00
"rebalance_explanation" : "Elasticsearch cannot rebalance this shard to another node since there is no node to which allocation is permitted which would improve the cluster balance. If you expect this shard to be rebalanced to another node, find this node in the node-by-node explanation and address the reasons which prevent Elasticsearch from rebalancing this shard there.",
Cluster allocation explain API documentation (#22436) This commit updates the cluster allocation explain API documentation to explain the new request parameters and response formats, and gives examples of the explain API responses under various scenarios.
2017-01-10 22:55:39 +08:00
"node_allocation_decisions" : [
{
"node_id" : "oE3EGFc8QN-Tdi5FFEprIA",
"node_name" : "node_t1",
"transport_address" : "127.0.0.1:9401",
"node_decision" : "worse_balance", <3>
"weight_ranking" : 1
}
]
}
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
----
[Docs] Convert remaining code snippets in docs (#26422) This commit converts the last remaining code snippets so that they are now testable.
2017-08-30 18:11:10 +08:00
// NOTCONSOLE
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
[DOCS] Reformats cluster allocation explain API (#45603) Co-Authored-By: James Rodewig <james.rodewig@elastic.co>
2019-08-16 21:38:09 +08:00
<1> Whether rebalancing is allowed on the cluster.
<2> Whether the shard can be rebalanced to another node.
<3> The reason the shard cannot be rebalanced to the node, in this case indicating that it offers no better balance than the current node.
Open with better cluster allocation explain ex. (#72245) Today the only example of calling the cluster allocation explain API above the fold is the bare `GET /_cluster/allocation/explain` which kind of works but is not usually what the user wants. This commit changes the docs so that we open with an example showing how we usually expect it to be called. This will make it clearer that you should normally specify exactly for which shard you want an explanation. It also tidies up a few other wrinkles in these docs. Co-authored-by: James Rodewig <40268737+jrodewig@users.noreply.github.com>
2021-04-27 00:41:22 +08:00
===== No arguments
If you call the API with no arguments, {es} retrieves an allocation explanation
for an arbitrary unassigned primary or replica shard.
[source,console]
----
GET _cluster/allocation/explain
----
// TEST[catch:bad_request]
If the cluster contains no unassigned shards, the API returns a `400` error.