Expand "Configure a lifecycle policy" docs

manage-data/data-store/data-streams/modify-data-stream.md

@@ -214,11 +214,10 @@ To change a [dynamic index setting](elasticsearch://reference/elasticsearch/inde
 
 
 ::::{important}
-To change the `index.lifecycle.name` setting, first use the [remove policy API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-remove-policy) to remove the existing {{ilm-init}} policy. See [Switch lifecycle policies](../../lifecycle/index-lifecycle-management/configure-lifecycle-policy.md#switch-lifecycle-policies).
+To change the `index.lifecycle.name` setting, first use the [remove policy API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-remove-policy) to remove the existing {{ilm-init}} policy. See [Switch lifecycle policies](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md#switch-lifecycle-policies).
 ::::
 
 
-
 ### Change a static index setting for a data stream [change-static-index-setting-for-a-data-stream]
 
 [Static index settings](elasticsearch://reference/elasticsearch/index-settings/index.md) can only be set when a backing index is created. You cannot update static index settings using the [update index settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings).

manage-data/lifecycle/data-tiers.md

@@ -390,7 +390,7 @@ When data reaches the `cold` or `frozen` phases, it is automatically converted t
 5. Restore indices from the searchable snapshots.
 
     1. Follow the steps to [specify the data tier based allocation inclusion rules](/manage-data/lifecycle/data-tiers.md#update-data-tier-allocation-rules).
-    2. Remove the associated ILM policy (set it to `null`). If you want to apply a different ILM policy, follow the steps to [Switch lifecycle policies](/manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy.md#switch-lifecycle-policies).
+    2. Remove the associated ILM policy (set it to `null`). If you want to apply a different ILM policy, follow the steps to [Switch lifecycle policies](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md#switch-lifecycle-policies).
     3. If needed, specify the alias for rollover, otherwise set it to `null`.
     4. Optionally, specify the desired number of replica shards.
 

manage-data/lifecycle/index-lifecycle-management.md

@@ -68,12 +68,13 @@ For example, if you are indexing metrics data from a fleet of ATMs into Elastics
 You can create and manage index lifecycle policies through {{kib}}'s [Index Management](/manage-data/data-store/index-basics.md#index-management) UI or the [{{ilm-init}} APIs](https://www.elastic.co/docs/api/doc/elasticsearch/v8/group/endpoint-ilm). For more details on creating and managing index lifecycle policies refer to:
 
 * [Configure a lifecycle policy](/manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy.md)
-* [Update a lifecycle policy](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md)
+* [View the lifecycle status of an index](/manage-data/lifecycle/index-lifecycle-management/policy-view-status.md)
+* [Update or switch a lifecycle policy](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md)
 * [Start and stop index lifecycle management](/manage-data/lifecycle/index-lifecycle-management/start-stop-index-lifecycle-management.md)
 * [Restore a managed data stream or index](/manage-data/lifecycle/index-lifecycle-management/restore-managed-data-stream-index.md)
 * [Customize built-in policies](/manage-data/lifecycle/index-lifecycle-management/tutorial-customize-built-in-policies.md)
 
-Default {{ilm}} policies are created automatically when you use {{agent}}, {{beats}}, or the {{ls}} {{es}} output plugin to send data to the {{stack}}.
+Default {{ilm}} policies are created automatically when you install an [Elastic Integration](integration-docs://reference/index.md), or when you use {{agent}}, {{beats}}, or the {{ls}} {{es}} output plugin to send data to the {{stack}}.
 
 ![index lifecycle policies](/manage-data/images/elasticsearch-reference-index-lifecycle-policies.png)
 

manage-data/lifecycle/index-lifecycle-management/manage-existing-indices.md

@@ -22,7 +22,7 @@ Starting in Curator version 5.7, Curator ignores {{ilm-init}} managed indices.
 
 ## Apply policies to existing time series indices [ilm-existing-indices-apply]
 
-The simplest way to transition to managing your periodic indices with {{ilm-init}} is to [configure an index template](configure-lifecycle-policy.md#apply-policy-template) to apply a lifecycle policy to new indices. Once the index you are writing to is being managed by {{ilm-init}}, you can [manually apply a policy](configure-lifecycle-policy.md#apply-policy-multiple) to your older indices.
+The simplest way to transition to managing your periodic indices with {{ilm-init}} is to [configure an index template](configure-lifecycle-policy.md#apply-policy-template) to apply a lifecycle policy to new indices. Once the index you are writing to is being managed by {{ilm-init}}, you can [manually apply a policy](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md) to your older indices.
 
 Define a separate policy for your older indices that omits the rollover action. Rollover is used to manage where new data goes, so isn’t applicable.
 

manage-data/lifecycle/index-lifecycle-management/policy-apply.md

@@ -0,0 +1,72 @@
+---
+navigation_title: Manually apply a policy to an index
+applies_to:
+  stack: ga
+products:
+  - id: elasticsearch
+---
+
+# Manually apply a lifecycle policy to an index [apply-policy-manually]
+
+When you create new {{es}} index you can use an index template to apply the lifecycle policy by which the index will be managed. This process is described in [Configure a lifecycle policy](/manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy.md).
+
+You can also manually apply a lifecycle policy to an existing index, as described on this page. If an index is currently managed by an ILM policy you must first remove that policy before applying a new one. Refer to [Switch to a different lifecycle policy](/manage-data/lifecycle/index-lifecycle-management/policy-updates.md#switch-lifecycle-policies) for details.
+
+You can do this procedure in {{kib}} or using the {{es}} API.
+
+::::{warning}
+Do not manually apply a policy that uses the rollover action. Policies that use rollover must be applied by the [index template](/manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy.md#apply-policy-template). Otherwise, the policy is not carried forward when the rollover action creates a new index.
+::::
+
+::::{tab-set}
+:group: kibana-api
+:::{tab-item} {{kib}}
+:sync: kibana
+
+To apply a lifecycle policy to an existing index:
+
+1. Go to **Stack Management > Index Management**. In the **Indices** tab, search for and select an index. Enable **Include hidden indices** to see the full list of indices.
+
+1. From the **Manage index** dropdown menu select **Add lifecycle policy**.
+
+1. Choose a lifecycle policy and confirm your changes.
+
+Once the policy is applied, {{ilm-init}} starts managing the index immediately.
+:::
+
+:::{tab-item} API
+:sync: api
+Use the [update settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings) to apply a lifecycle policy to an index.
+
+```console
+PUT my-index/_settings
+{
+  "index": {
+    "lifecycle": {
+      "name": "my_ilm_policy"
+    }
+  }
+}
+```
+
+You can apply the same policy to multiple indices by using wildcards in the index name when you call the API.
+
+```console
+PUT my-indices*/_settings
+{
+  "index": {
+    "lifecycle": {
+      "name": "my_ilm_policy"
+    }
+  }
+}
+```
+
+::::::{warning}
+Be careful not to inadvertently match indices that you don’t want to modify.
+::::::
+
+Once the policy is applied, {{ilm-init}} starts managing the index immediately.
+
+:::
+::::

manage-data/lifecycle/index-lifecycle-management/policy-updates.md

@@ -1,5 +1,5 @@
 ---
-navigation_title: Update a policy
+navigation_title: Update or switch a policy
 mapped_pages:
   - https://www.elastic.co/guide/en/elasticsearch/reference/current/update-lifecycle-policy.html
 applies_to:
@@ -8,7 +8,7 @@ products:
   - id: elasticsearch
 ---
 
-# Update a lifecycle policy
+# Update or switch a lifecycle policy
 
 
 You can change how the lifecycle of an index or collection of rolling indices is managed by modifying the current policy or switching to a different policy.
@@ -31,3 +31,133 @@ For example, if you create a policy that has a hot phase that does not specify a
 
 When you apply a different policy to a managed index, the index completes the current phase using the cached definition from the previous policy. The index starts using the new policy when it moves to the next phase.
 
+
+## Update an existing lifecycle policy [update-lifecycle-policy]
+
+You can update a lifecycle policy that is currently associated with one or more indices.
+
+:::{warning}
+Avoid changing any managed policies that are shipped with {{es}}, such as `logs@lifecycle` or `metrics@lifecycle`. Instead, create a new, [custom ILM policy](/manage-data/lifecycle/index-lifecycle-management/tutorial-customize-built-in-policies.md) and associate it with the intended index template or indices.
+:::
+
+::::{tab-set}
+:group: kibana-api
+:::{tab-item} {{kib}}
+:sync: kibana
+To update a lifecycle policy:
+
+1. Go to **Stack Management > Index Lifecycle Policies** and use the search tool to find the lifecycle policy that you want to update.
+
+   You can deselect the **Include managed system policies** option to filter out managed policies from the list, since it's strongly recommended not to update these.
+
+1. Check the links in the **Linked index templates** and **Linked indices** columns to confirm that your updates will apply only to templates or indices that you want to affect with a new policy.
+
+1. For the policy that you want to update, select the `edit` icon in the **Actions** menu.
+
+    Note that from the **Actions** menu you can also choose to add the ILM policy to any existing index templates.
+
+1. On the **Edit policy** page, enable any {{ilm-init}} phases as needed, and expand **Advanced settings** to adjust the [index lifecycle actions](elasticsearch://reference/elasticsearch/index-lifecycle-actions/index.md) configured for that phase.
+:::
+
+
+
+:::{tab-item} API
+:sync: api
+Use the [Create or update policy](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-put-lifecycle) API to update an existing ILM policy:
+
+```console
+PUT _ilm/policy/my_policy
+{
+  "policy": {
+    "phases": {
+      "hot": {
+        "actions": {
+          "rollover": {
+            "max_primary_shard_size": "25GB" <1>
+          }
+        }
+      },
+      "delete": {
+        "min_age": "30d",
+        "actions": {
+          "delete": {} <2>
+        }
+      }
+    }
+  }
+}
+```
+
+1. Roll over the index when one or more of its shards reach 25GB in size
+2. Delete the index 30 days after rollover
+
+
+The specified policy will be replaced and the policy version is incremented.
+:::
+::::
+
+
+## Switch to a different lifecycle policy [switch-lifecycle-policies]
+
+You can change an index to be managed by a different {{ilm-init}} policy.
+
+:::::{warning}
+When you remove an ILM policy, all {{ilm-init}} metadata is removed from the managed index without consideration of the index’s lifecycle status. This can leave indices in an undesired state.
+
+For example, in certain cases the [`forcemerge`](elasticsearch://reference/elasticsearch/index-lifecycle-actions/ilm-forcemerge.md) action temporarily closes an index before reopening it. Removing an index’s {{ilm-init}} policy during a `forcemerge` can leave the index closed until it is manually reopened.
+:::::
+
+::::{tab-set}
+:group: kibana-api
+:::{tab-item} {{kib}}
+:sync: kibana
+To switch an index’s lifecycle policy:
+
+1. Go to **Stack Management > Index Management**. In the **Indices** tab, search for and select the index that you that you want to switch to a new policy. You can use the **Lifecycle status** filter to narrow the list.
+
+1. From the **Manage index** dropdown menu select **Remove lifecycle policy**. Confirm your choice and then the ILM policy is removed.
+
+1. From the **Manage index** dropdown menu select **Add lifecycle policy**, and then select a new policy to apply.
+:::
+
+:::{tab-item} API
+:sync: api
+Use the {{es}} [remove policy](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-remove-policy) and [update settings](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings) APIs to switch an index’s lifecycle policy:
+
+1. Remove the existing policy using the [remove policy API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-remove-policy). Target a data stream or alias to remove the policies of all its indices.
+
+    ```console
+    POST logs-my_app-default/_ilm/remove
+    ```
+
+2. Use the [get index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get) to check an index’s state. Target a data stream or alias to get the state of all its indices.
+
+    ```console
+    GET logs-my_app-default
+    ```
+
+    You can then change the index as needed. For example, you can re-open any closed indices using the [open index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-open).
+
+    ```console
+    POST logs-my_app-default/_open
+    ```
+
+3. Assign a new policy using the [update settings API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-settings). 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 [phase execution](index-lifecycle.md#ilm-phase-execution) to silently fail.
+    ::::::
+
+    ```console
+    PUT logs-my_app-default/_settings
+    {
+      "index": {
+        "lifecycle": {
+          "name": "new-lifecycle-policy"
+        }
+      }
+    }
+    ```
+
+:::
+::::