From 3d33e96d2ebae4cd4ac28690921738f3221294a1 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Mon, 28 Jun 2021 10:32:01 -0400
Subject: [PATCH] [DOCS] Document how to switch ILM policies (#73967)

To switch an index's lifecycle policy, you must first remove the existing
policy. Otherwise, phase execution for the index may silently fail.

Closes #70151
---
 .../change-mappings-and-settings.asciidoc     |  4 ++
 .../ilm/set-up-lifecycle-policy.asciidoc      | 67 +++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/docs/reference/data-streams/change-mappings-and-settings.asciidoc b/docs/reference/data-streams/change-mappings-and-settings.asciidoc
index 7f6f8cc9b1342..b17b47120a41a 100644
--- a/docs/reference/data-streams/change-mappings-and-settings.asciidoc
+++ b/docs/reference/data-streams/change-mappings-and-settings.asciidoc
@@ -320,6 +320,10 @@ PUT /my-data-stream/_settings
 ----
 --
 
+IMPORTANT: To change the `index.lifecycle.name` setting, first use the
+<<ilm-remove-policy,remove policy API>> to remove the existing {ilm-init}
+policy. See <<switch-lifecycle-policies>>.
+
 [discrete]
 [[change-static-index-setting-for-a-data-stream]]
 === Change a static index setting for a data stream
diff --git a/docs/reference/ilm/set-up-lifecycle-policy.asciidoc b/docs/reference/ilm/set-up-lifecycle-policy.asciidoc
index c22135fce8c91..92511ab52cd75 100644
--- a/docs/reference/ilm/set-up-lifecycle-policy.asciidoc
+++ b/docs/reference/ilm/set-up-lifecycle-policy.asciidoc
@@ -268,3 +268,70 @@ PUT mylogs-pre-ilm*/_settings <1>
 // TEST[continued]
 
 <1> Updates all indices with names that start with `mylogs-pre-ilm`
+
+[discrete]
+[[switch-lifecycle-policies]]
+==== Switch lifecycle policies
+
+To switch an index's lifecycle policy, follow these steps:
+
+. Remove the existing policy using the <<ilm-remove-policy,remove policy API>>.
+Target a data stream or alias to remove the policies of all its indices.
++
+[source,console]
+----
+POST logs-my_app-default/_ilm/remove
+----
+// TEST[continued]
+// TEST[s/^/PUT _data_stream\/logs-my_app-default\n/]
+
+. The remove policy API removes all {ilm-init} metadata from the index and
+doesn't consider the index's lifecycle status. This can leave indices in an
+undesired state.
++
+--
+For example, the <<ilm-forcemerge,`forcemerge`>> action temporarily closes an
+index before reopening it. Removing an index's {ilm-init} policy during a
+`forcemerge` can leave the index closed indefinitely.
+
+After policy removal, use the <<indices-get-index,get index API>> to check an
+index's state . Target a data stream or alias to get the state of all its
+indices.
+
+[source,console]
+----
+GET logs-my_app-default
+----
+// TEST[continued]
+
+You can then change the index as needed. For example, you can re-open any
+closed indices using the <<indices-open-close,open index API>>.
+
+[source,console]
+----
+POST logs-my_app-default/_open
+----
+// TEST[continued]
+--
+
+. Assign a new policy using the <<indices-update-settings,update settings API>>.
+Target a data stream or alias to assign a policy to all its indices.
++
+--
+WARNING: Don't assign a new policy without first removing the existing policy.
+This can cause <<ilm-phase-execution,phase execution>> to silently fail.
+
+[source,console]
+----
+PUT logs-my_app-default/_settings
+{
+  "index": {
+    "lifecycle": {
+      "name": "new-lifecycle-policy"
+    }
+  }
+}
+----
+// TEST[continued]
+// TEST[s/new-lifecycle-policy/mylogs_policy_existing/]
+--