Merge pull request #12272 from clintongormley/index_priority_docs

Docs: Documented index prioritization

docs/reference/index-modules/allocation.asciidoc

@@ -12,6 +12,8 @@ include::allocation/filtering.asciidoc[]
 
 include::allocation/delayed.asciidoc[]
 
+include::allocation/prioritization.asciidoc[]
+
 include::allocation/total_shards.asciidoc[]
 
 

docs/reference/index-modules/allocation/prioritization.asciidoc

@@ -0,0 +1,55 @@
+[[recovery-prioritization]]
+=== Index recovery prioritization
+
+Unallocated shards are recovered in order of priority, whenever possible.
+Indices are sorted into priority order as follows:
+
+* the optional `index.priority` setting (higher before lower)
+* the index creation date (higher before lower)
+* the index name (higher before lower)
+
+This means that, by default, newer indices will be recovered before older indices.
+
+Use the per-index dynamically updateable `index.priority` setting to customise
+the index prioritization order.  For instance:
+
+[source,json]
+------------------------------
+PUT index_1
+
+PUT index_2
+
+PUT index_3
+{
+  "settings": {
+    "index.priority": 10
+  }
+}
+
+PUT index_4
+{
+  "settings": {
+    "index.priority": 5
+  }
+}
+------------------------------
+// AUTOSENSE
+
+In the above example:
+
+* `index_3` will be recovered first because it has the highest `index.priority`.
+* `index_4` will be recovered next because it has the next highest priority.
+* `index_2` will be recovered next because it was created more recently.
+* `index_1` will be recovered last.
+
+This setting accepts an integer, and can be updated on a live index with the
+<<indices-update-settings,update index settings API>>:
+
+[source,json]
+------------------------------
+PUT index_4/_settings
+{
+  "index.priority": 1
+}
+------------------------------
+// AUTOSENSE