IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Wait for snapshot Resolve lifecycle policy execution errors »
Elastic Docs ›Elasticsearch Guide [7.7] ›ILM: Manage the index lifecycle

Configure a lifecycle policy

edit

Configure a lifecycle policy

edit

For ILM to manage an index, a valid policy must be specified in the index.lifecycle.name index setting.

To configure a lifecycle policy for rolling indices, you create the policy and add it to the index template.

To use a policy to manage an index that doesn’t roll over, you can specify a lifecycle policy when you create it.

ILM policies are stored in the global cluster state and can be included in snapshots by setting include_global_state to true when you take the snapshot. When the snapshot is restored, all of the policies in the global state are restored and any local policies with the same names are overwritten.

When you enable index lifecycle management for Beats or the Logstash Elasticsearch output plugin, the necessary policies and configuration changes are applied automatically. You can modify the default policies, but you do not need to explicitly configure a policy or bootstrap an initial index.

Create lifecycle policy

edit

You use the create policy API to define a new lifecycle policy. For example, the following request creates my_policy, a policy that defines a hot and and delete phase. When the index reaches 25GB, it rolls over directly to the delete phase. The index is deleted 30 days after rollover.

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

Roll over the index when it reaches 25GB in size

Delete the index 30 days after rollover

Apply lifecycle policy with an index template

edit

To use a policy that triggers the rollover action, you need to configure the policy in the index template used to create each new index.

In addition to specifying the name of the policy in the index.lifecycle.name setting, you specify a index.lifecycle.rollover_alias for referencing the indices managed by this policy.

PUT _template/my_template
{
  "index_patterns": ["test-*"], 
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1,
    "index.lifecycle.name": "my_policy", 
    "index.lifecycle.rollover_alias": "test-alias" 
  }
}

Use this template for all new indices whose names begin with test-

Apply my_policy to new indices created with this template

Define an index alias for referencing indices managed by my_policy

Create an initial managed index

edit

You need to manually create the first index managed by a policy that uses the rollover action and designate it as the write index. The name of the index must match the pattern defined in the index template and end with a number. This number is incremented to generate the name of indices created by the rollover action.

For example, the following request creates the test-00001 index. Because it matches the index pattern specified in my_template, Elasticsearch automatically applies the settings from that template.

PUT test-000001
{
  "aliases": {
    "test-alias":{
      "is_write_index": true 
    }
  }
}

Set this initial index to be the write index for this alias.

Now you can start indexing data to the rollover alias specified in the lifecycle policy. With the sample my_policy policy, the rollover action is triggered once the initial index exceeds 25GB. ILM then creates a new index that becomes the write index for the test-alias.

Apply lifecycle policy manually

edit

When you create an index, you can apply a lifecycle policy by specifying the index.lifecycle.name setting. This causes ILM to immediately start managing the index.

PUT test-index
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1,
    "index.lifecycle.name": "my_policy"
  }
}

Do not manually apply a policy that uses the rollover action. Policies that use rollover must be applied by the index template. Otherwise, the policy is not carried forward when the rollover action creates a new index.

Apply a policy to multiple indices

edit

You can apply the same policy to multiple indices by using wildcards in the index name when you call the update settings API.

Be careful that you don’t inadvertently match indices that you don’t want to modify.

PUT mylogs-pre-ilm*/_settings 
{
  "index": {
    "lifecycle": {
      "name": "mylogs_policy_existing"
    }
  }
}

Updates all indices with names that start with mylogs-pre-ilm
« Wait for snapshot Resolve lifecycle policy execution errors »