[7.13] [DOCS] Document how to switch ILM policies (#73967)

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

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/]
+--