From 1b8c867785fe9f94dd6f25c795048adcd35e9f57 Mon Sep 17 00:00:00 2001
From: Joe Gallo <joe.gallo@elastic.co>
Date: Tue, 7 Dec 2021 11:03:41 -0500
Subject: [PATCH] _tier_preference docs changes for 7.16 (#81401)

---
 .../migrate-index-allocation-filters.asciidoc | 26 +++++++++++++++++--
 .../ilm/apis/migrate-to-data-tiers.asciidoc   |  9 ++++---
 docs/reference/modules/cluster/misc.asciidoc  | 18 +++++++++++++
 3 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/docs/reference/data-management/migrate-index-allocation-filters.asciidoc b/docs/reference/data-management/migrate-index-allocation-filters.asciidoc
index 0c013a00829ca..efa6c97513c2e 100644
--- a/docs/reference/data-management/migrate-index-allocation-filters.asciidoc
+++ b/docs/reference/data-management/migrate-index-allocation-filters.asciidoc
@@ -56,6 +56,8 @@ To switch to using node roles:
 settings>> from your {ilm} policy.
 . <<stop-setting-custom-hot-attribute, Stop setting the custom hot attribute>>
 on new indices.
+. <<enforce-default-tier-preference, Enforce a default tier preference>>
+on new indices.
 . Update existing indices to <<set-tier-preference, set a tier preference>>.
 
 
@@ -136,9 +138,29 @@ DELETE _template/.cloud-hot-warm-allocation-0
 
 If you're using a custom index template, update it to remove the <<shard-allocation-filtering, attribute-based allocation filters>> you used to assign new indices to the hot tier.
 
+[discrete]
+[[enforce-default-tier-preference]]
+==== Enforce a default tier preference on new indices
+
+Setting <<enforcing-a-default-tier-preference,`cluster.routing.allocation.enforce_default_tier_preference`>> to `true`
+ensures that newly created indices will have a <<tier-preference-allocation-filter,_tier_preference>>, overriding the
+<<indices-create-index,create index>> API or an associated <<index-templates,index template>>, if either of those
+specifies `null` for the setting.
+
+[source,console]
+----
+PUT _cluster/_settings
+{
+  "persistent": {
+    "cluster.routing.allocation.enforce_default_tier_preference": true
+  }
+}
+----
+// TEST[continued]
+
 [discrete]
 [[set-tier-preference]]
-==== Set a tier preference for existing indices.
+==== Set a tier preference for existing indices
 
 {ilm-init} automatically transitions managed indices through the available
 data tiers by automatically injecting a <<ilm-migrate,migrate action>>
@@ -148,7 +170,7 @@ To enable {ilm-init} to move an _existing_ managed index
 through the data tiers, update the index settings to:
 
 . Remove the custom allocation filter by setting it to `null`.
-. Set the <<data-tier-shard-filtering,tier preference>>.
+. Set the <<tier-preference-allocation-filter,tier preference>>.
 
 For example, if your old template set the `data` attribute to `hot`
 to allocate shards to the hot tier, set the `data` attribute to `null`
diff --git a/docs/reference/ilm/apis/migrate-to-data-tiers.asciidoc b/docs/reference/ilm/apis/migrate-to-data-tiers.asciidoc
index 2eb6875c7756e..c9932318110b2 100644
--- a/docs/reference/ilm/apis/migrate-to-data-tiers.asciidoc
+++ b/docs/reference/ilm/apis/migrate-to-data-tiers.asciidoc
@@ -15,12 +15,13 @@ Migrating away from custom node attributes routing can be manually performed
 as indicated in the <<migrate-index-allocation-filters, Migrate index allocation
 filters to node roles>> page.
 
-This API provides an automated way of executing three out of the four manual steps listed
-in the <<data-tier-migration, migration guide>>:
+This API provides an automated way of executing four out of the five manual steps listed
+in the <<migrate-index-allocation-filters, migration guide>>:
 
 . <<stop-setting-custom-hot-attribute, Stop setting the custom hot attribute on new indices>>
 . <<remove-custom-allocation-settings, Remove custom allocation settings from existing {ilm-init} policies>>
-. <<set-tier-preference, Replace custom allocation settings from existing indices>> with the corresponding <<data-tier-shard-filtering,tier preference>>
+. <<enforce-default-tier-preference, Enforce a default tier preference on new indices>>
+. <<set-tier-preference, Replace custom allocation settings from existing indices>> with the corresponding <<tier-preference-allocation-filter,tier preference>>
 
 [[ilm-migrate-to-data-tiers-request]]
 ==== {api-request-title}
@@ -137,4 +138,4 @@ If the request succeeds, a response like the following will be received:
 <1> Shows the name of the legacy index template that was deleted. This will be missing
 if no legacy index template was deleted.
 <2> The ILM policies that were updated.
-<3> The indices that were migrated to <<data-tier-shard-filtering,tier preference>> routing.
+<3> The indices that were migrated to <<tier-preference-allocation-filter,tier preference>> routing.
diff --git a/docs/reference/modules/cluster/misc.asciidoc b/docs/reference/modules/cluster/misc.asciidoc
index 83adaef9ec1a0..408cb21191361 100644
--- a/docs/reference/modules/cluster/misc.asciidoc
+++ b/docs/reference/modules/cluster/misc.asciidoc
@@ -201,3 +201,21 @@ left the cluster, for example), are impacted by this setting.
      This setting controls how often assignment checks are performed to react to
      these factors. The default is 30 seconds. The minimum permitted value is 10
      seconds.
+
+
+[[enforcing-a-default-tier-preference]]
+===== Enforcing a default _tier_preference
+
+Newly created indices have <<tier-preference-allocation-filter, `index.routing.allocation.include._tier_preference`>>
+automatically assigned <<data-tier-allocation, by default>>.
+This can be overridden by setting the `_tier_preference` to `null`
+via the <<indices-create-index,create index>> API or using an <<index-templates,index template>>.
+
+In 8.0, it will not be possible to bypass this behavior by setting the
+`_tier_preference` to `null` -- all newly created indices will always
+have an associated `_tier_preference`.
+
+`cluster.routing.allocation.enforce_default_tier_preference`::
+     (<<dynamic-cluster-setting,Dynamic>>)
+     Enforce that newly created indices must always have a non-null `_tier_preference`,
+     bypassing request or template settings. Defaults to `false`.