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

@@ -386,7 +386,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/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: Apply a policy to an index
+applies_to:
+  stack: ga
+products:
+  - id: elasticsearch
+---
+
+# 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 here. 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 to an index which has not yet rolled over. Otherwise, the policy may not be 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 the index that you created, for example `test-00001`. 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,129 @@ 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.
+
+::::{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.
+
+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 it reaches 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}
+Note the following restrictions when switching the policy for an index:
+
+* Avoid changing any managed policies that are shipped with {{es}}, such as `logs@lifecycle` or `metrics@lifecycle`. Instead, create a new ILM policy and associate it with the intended index template or indices.
+
+* 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 indefinitely.
+:::::
+
+::::{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"
+        }
+      }
+    }
+    ```
+
+:::
+::::

manage-data/lifecycle/index-lifecycle-management/policy-view-status.md

@@ -0,0 +1,132 @@
+---
+navigation_title: View the lifecycle status of an index
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/reference/current/update-lifecycle-policy.html
+applies_to:
+  stack: ga
+products:
+  - id: elasticsearch
+---
+
+# View the lifecycle status of an index [view-lifecycle-status]
+
+For any existing managed index in your cluster, you can access the ILM policy applied to it and details such as its current phase.
+
+::::{tab-set}
+:group: kibana-api
+:::{tab-item} {{kib}}
+:sync: kibana
+To view the current lifecycle status for one or more indices:
+
+1. Go to **Stack Management > Index Management** and open the **Indices** tab.
+1. Enable **Include hidden indices** to view all indices, including those managed by ILM. Note that if you're using data streams, you can find the data stream associated with any index listed in the **Data stream** column.
+1. Use the search tool to find the index you're looking for. You can also filter the results by lifecycle status and lifecycle phase.
+1. Select the index to view details.
+1. Open the **Index lifecycle** tab to view ILM details such as the current lifecycle phase, the ILM policy name, the current [index lifecycle action](elasticsearch://reference/elasticsearch/index-lifecycle-actions/index.md), and other details.
+
+   ![Index lifecycle status page](/manage-data/images/elasticsearch-reference-ilm-status.png "")
+
+To view the current lifecycle status for a datastream:
+
+1. Go to **Stack Management > Index Management** and open the **Data Streams** tab.
+1. Use the search tool to find the data stream you're looking for.
+1. Select the data stream to view details. In the flyout that opens, you have direct links to access the ILM policy and the index template.
+
+   ![Data stream status page](/manage-data/images/elasticsearch-reference-datastream-status.png "")
+:::
+
+:::{tab-item} API
+:sync: api
+Use the [Explain the lifecycle state API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ilm-explain-lifecycle) to view the current lifecycle status for an index:
+
+```console
+GET my-index/_ilm/explain
+```
+
+The API response shows the current ILM phase and other details:
+
+```json
+{
+  "indices": {
+    ".ds-logs-elastic_agent.filebeat-default-2025.06.04-000001": {
+      "index": ".ds-logs-elastic_agent.filebeat-default-2025.06.04-000001",
+      "managed": true,
+      "policy": "logs",
+      "index_creation_date_millis": 1749060710541,
+      "time_since_index_creation": "19.05d",
+      "lifecycle_date_millis": 1749060710541,
+      "age": "19.05d",
+      "phase": "hot",
+      "phase_time_millis": 1749060711038,
+      "action": "rollover",
+      "action_time_millis": 1749060712038,
+      "step": "check-rollover-ready",
+      "step_time_millis": 1749060712038,
+      "phase_execution": {
+        "policy": "logs",
+        "phase_definition": {
+          "min_age": "0ms",
+          "actions": {
+            "rollover": {
+              "max_age": "30d",
+              "max_primary_shard_docs": 200000000,
+              "min_docs": 1,
+              "max_primary_shard_size": "50gb"
+            }
+          }
+        },
+        "version": 1,
+        "modified_date_in_millis": 1749059754275
+      }
+    }
+  }
+}
+```
+
+You can also call this API for a data stream:
+
+```console
+GET my-datastream/_ilm/explain
+```
+
+When called for a data stream, the API retrieves the current lifecycle status for the stream's backing indices:
+
+```json
+{
+  "indices": {
+    ".ds-logs-elastic_agent.filebeat-default-2025.06.04-000001": {
+      "index": ".ds-logs-elastic_agent.filebeat-default-2025.06.04-000001",
+      "managed": true,
+      "policy": "logs",
+      "index_creation_date_millis": 1749060710541,
+      "time_since_index_creation": "19.06d",
+      "lifecycle_date_millis": 1749060710541,
+      "age": "19.06d",
+      "phase": "hot",
+      "phase_time_millis": 1749060711038,
+      "action": "rollover",
+      "action_time_millis": 1749060712038,
+      "step": "check-rollover-ready",
+      "step_time_millis": 1749060712038,
+      "phase_execution": {
+        "policy": "logs",
+        "phase_definition": {
+          "min_age": "0ms",
+          "actions": {
+            "rollover": {
+              "max_age": "30d",
+              "max_primary_shard_docs": 200000000,
+              "min_docs": 1,
+              "max_primary_shard_size": "50gb"
+            }
+          }
+        },
+        "version": 1,
+        "modified_date_in_millis": 1749059754275
+      }
+    }
+  }
+}
+```
+:::
+::::

manage-data/toc.yml

@@ -119,6 +119,8 @@ toc:
               - file: lifecycle/index-lifecycle-management/skip-rollover.md
               - file: lifecycle/index-lifecycle-management/tutorial-automate-rollover.md
           - file: lifecycle/index-lifecycle-management/configure-lifecycle-policy.md
+          - file: lifecycle/index-lifecycle-management/policy-apply.md
+          - file: lifecycle/index-lifecycle-management/policy-view-status.md
           - file: lifecycle/index-lifecycle-management/policy-updates.md
           - file: lifecycle/index-lifecycle-management/start-stop-index-lifecycle-management.md
           - file: lifecycle/index-lifecycle-management/restore-managed-data-stream-index.md