elasticsearch/docs/reference/ilm/example-index-lifecycle-policy.asciidoc

[role="xpack"]

[[example-using-index-lifecycle-policy]]
=== Tutorial: Customize built-in {ilm-init} policies
++++
<titleabbrev>Customize built-in {ilm-init} policies</titleabbrev>
++++

{es} includes the following built-in {ilm-init} policies:

* `logs`
* `metrics`
* `synthetics`

The {agent} uses these policies to manage backing indices for its data streams.
This tutorial shows you how to use {kib}’s *Index Lifecycle Policies* to
customize these policies based on your application's performance, resilience,
and retention requirements.


[discrete]
[[example-using-index-lifecycle-policy-scenario]]
==== Scenario

You want to send log files to an {es} cluster so you can visualize and analyze
the data. This data has the following retention requirements:

* When the write index reaches 50GB or is 30 days old, roll over to a new index.
* After rollover, keep indices in the hot data tier for 30 days.
* 30 days after rollover:
** Move indices to the warm data tier.
** Set <<glossary-replica-shard, replica shards>> to 1.
** <<indices-forcemerge, Force merge>> multiple index segments to free up the
space used by deleted documents.
* Delete indices 90 days after rollover.


[discrete]
[[example-using-index-lifecycle-policy-prerequisites]]
==== Prerequisites

To complete this tutorial, you'll need:

* An {es} cluster with hot and warm data tiers.

** {ess}:
Elastic Stack deployments on the {ess} include a hot tier by default. To add a
warm tier, edit your deployment and click **Add capacity** for the warm data
tier.
+
[role="screenshot"]
image::images/ilm/tutorial-ilm-ess-add-warm-data-tier.png[Add a warm data tier to your deployment]

** Self-managed cluster:
Assign `data_hot` and `data_warm` roles to nodes as described in
<<data-tiers>>.
+
For example, include the `data_warm` node role in the `elasticsearch.yml` file
of each node in the warm tier:
+
[source,yaml]
----
node.roles: [ "data_warm" ]
----

* A host with the {agent} installed and configured to send logs to your {es}
cluster.

[discrete]
[[example-using-index-lifecycle-policy-view-ilm-policy]]
==== View the policy

The {agent} uses data streams with an index pattern of `logs-*-*` to store log
monitoring data. The built-in `logs` {ilm-init} policy automatically manages
backing indices for these data streams.

To view the `logs` policy in {kib}:

. Open the menu and go to **Stack Management > Index Lifecycle Policies**.
. Select the `logs` policy.

The `logs` policy uses the recommended rollover defaults: start writing to a new
index when the current write index reaches 50GB or becomes 30 days old.

To view or change the rollover settings, click **Settings** for the hot phase.
Then disable **Use recommended defaults** to display the rollover settings.

[role="screenshot"]
image::images/ilm/tutorial-ilm-hotphaserollover-default.png[View rollover defaults]

[discrete]
[[ilm-ex-modify-policy]]
==== Modify the policy

The default `logs` policy is designed to prevent the creation of many tiny daily
indices. You can modify the policy to meet your performance requirements and
manage resource usage.

. Activate the warm phase and click **Settings**.
+
--
[role="screenshot"]
image::images/ilm/tutorial-ilm-modify-default-warm-phase-rollover.png[Add a warm phase with custom settings]

.. Set *Move data into phase when* to *30 days*. This moves indices to the warm
tier 30 days after rollover.

.. Enable **Replicas** and change *Number of replicas* to *1*.

.. Enable *Force merge* and set *Number of segments* to *1*.
--

. Activate the delete phase and set *Move data into phase when* to *90* days.
This deletes indices 90 days after rollover.
+
[role="screenshot"]
image::images/ilm/tutorial-ilm-delete-rollover.png[Add a delete phase]

. Click **Save Policy**.