Update or switch a lifecycle policy

Stack

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.

To ensure that policy updates don’t put an index into a state where it can’t exit the current phase, the phase definition is cached in the index metadata when it enters the phase. If changes can be safely applied, ILM updates the cached phase definition. If they cannot, phase execution continues using the cached definition.

When the index advances to the next phase, it uses the phase definition from the updated policy.

How changes are applied

When a policy is initially applied to an index, the index gets the latest version of the policy. If you update the policy, the policy version is bumped and ILM can detect that the index is using an earlier version that needs to be updated.

Changes to min_age are not propagated to the cached definition. Changing a phase’s min_age does not affect indices that are currently executing that phase.

For example, if you create a policy that has a hot phase that does not specify a min_age, indices immediately enter the hot phase when the policy is applied. If you then update the policy to specify a min_age of 1 day for the hot phase, that has no effect on indices that are already in the hot phase. Indices created after the policy update won’t enter the hot phase until they are a day old.

How new policies are applied

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

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 Elasticsearch, such as logs@lifecycle or metrics@lifecycle. Instead, create a new, custom ILM policy and associate it with the intended index template or indices.

Kibana

To update a lifecycle policy:

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.
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.
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.
On the Edit policy page, enable any ILM phases as needed, and expand Advanced settings to adjust the index lifecycle actions configured for that phase.

API

Use the Create or update policy API to update an existing ILM policy:

		 PUT _ilm/policy/my_policy {
  "policy": {
    "phases": {
      "hot": {
        "actions": {
          "rollover": {
            "max_primary_shard_size": "25GB"
          }
        }
      },
      "delete": {
        "min_age": "30d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}

	

Roll over the index when one or more of its shards reach 25GB in size.
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

You can change an index to be managed by a different ILM policy.

Warning

When you remove an ILM policy, all ILM 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 action temporarily closes an index before reopening it. Removing an index’s ILM policy during a forcemerge can leave the index closed until it is manually reopened.

Kibana

To switch an index’s lifecycle policy:

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.
From the Manage index dropdown menu, select Remove lifecycle policy. Confirm your choice before the ILM policy is removed.
From the Manage index dropdown menu, select Add lifecycle policy, and then select a new policy to apply.

API

Use the Elasticsearch remove policy and update settings APIs to switch an index’s lifecycle policy:

Remove the existing policy using the remove policy API. Target a data stream or alias to remove the policies of all its indices.
```
 POST logs-my_app-default/_ilm/remove 
```
Use the get index API to check an index’s state. Target a data stream or alias to get the state of all its indices.
```
 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.
```
 POST logs-my_app-default/_open 
```
Assign a new policy using the 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 phase execution to silently fail.
```
 PUT logs-my_app-default/_settings {
  "index": {
    "lifecycle": {
      "name": "new-lifecycle-policy"
    }
  }
}
```