Skip to content

Commit c239049

Browse files
Clarify scope and procedure for 'Configure a lifecycle policy' (#2535)
This addresses Edu's feedback for the popular Configure a lifecycle policy page, clarifying a few things: - Indicate that ILM applies to both data streams and standalone indices. - With standalone indices more manual work is required as compared to data streams, with additional steps described in Step 3 of the procedure. - Those additional steps are to set up the initial index and create an alias (we highlighted only the former). Please see [preview page](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/2535/manage-data/lifecycle/index-lifecycle-management/configure-lifecycle-policy). Rel: [#190](elastic/docs-content-internal#190) --------- Co-authored-by: Vlada Chirmicci <[email protected]>
1 parent 21b1842 commit c239049

File tree

1 file changed

+13
-11
lines changed

1 file changed

+13
-11
lines changed

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

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
navigation_title: Configure a policy
2+
navigation_title: Configure a lifecycle policy
33
mapped_pages:
44
- https://www.elastic.co/guide/en/elasticsearch/reference/current/set-up-lifecycle-policy.html
55
applies_to:
@@ -10,22 +10,22 @@ products:
1010

1111
# Configure a lifecycle policy [set-up-lifecycle-policy]
1212

13-
An [{{ilm}}](/manage-data/lifecycle/index-lifecycle-management.md) ({{ilm-init}}) policy defines how your indices are managed over time, automating when and how they transition as they age.
13+
An [{{ilm}}](/manage-data/lifecycle/index-lifecycle-management.md) ({{ilm-init}}) policy defines how your indices are managed over time, automating when and how they transition as they age. You can use {{ilm-init}} to manage both indices and [data streams](/manage-data/data-store/data-streams.md). There are fewer configuration steps required to set up ILM with data streams. In comparison, configuring ILM with indices requires you to create an initial managed index and alias in addition to defining a policy and creating a template to apply it. This page describes the steps to configure an {{ilm-init}} lifecycle policy for both scenarios.
14+
15+
:::{note}
16+
This page is specifically about using {{ilm-init}} with indices or data streams. If you're looking for a simpler data streams lifecycle management option that focuses on a data retention period, refer to [Data stream lifecycle](/manage-data/lifecycle/data-stream.md). Check [Data lifecycle](/manage-data/lifecycle.md) to compare these lifecycle management options.
17+
:::
1418

1519
**Consider these aspects when configuring an {{ilm-init}} policy:**
1620

17-
* For {{ilm-init}} to manage an index, you need to specify a valid policy in the `index.lifecycle.name` index setting.
21+
* To manage an index or data stream with {{ilm-init}}, you need to specify a valid policy in the `index.lifecycle.name` index setting.
1822

19-
* To configure a lifecycle policy for [rolling indices](rollover.md) or data streams, you create the policy and add it to the [index template](../../data-store/templates.md).
23+
* To configure a lifecycle policy for [rolling indices](rollover.md) or data streams, you create the policy and add it to the [index template](../../data-store/templates.md). Data streams are generally recommended in favor of rolling indices due to the lesser amount of manual configuration required. When you use {{ilm-init}} with rolling indices, you must, additionally, create an initial managed index (ensuring that it is named appropriately) and assign an alias to it. This additional process is described in [Step 3](#create-initial-index) on this page.
2024

2125
* To use a policy to manage a single index, you can specify a lifecycle policy when you create the index, or apply a policy directly to an existing index.
2226

2327
* {{ilm-init}} 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](../../../deploy-manage/tools/snapshot-and-restore/create-snapshots.md). 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.
2428

25-
:::{note}
26-
This page is specifically about {{ilm-init}}. If you're looking for a simpler lifecycle management option for data streams, refer to [Data stream lifecycle](/manage-data/lifecycle/data-stream.md). Check [Data lifecycle](/manage-data/lifecycle.md) to compare these lifecycle management options.
27-
:::
28-
2929
## Overview [ilm-configure-overview]
3030

3131
To set up ILM to manage one or more indices, the general procedure is as follows:
@@ -35,7 +35,7 @@ To set up ILM to manage one or more indices, the general procedure is as follows
3535

3636
If you're configuring ILM for rolling indices and not using [data streams](../../data-store/data-streams.md), you additionally need to:
3737

38-
3. [Create an initial managed index](#create-initial-index)
38+
3. [Create an initial managed index and alias](#create-initial-index)
3939

4040
You can perform these actions in {{kib}} or using the {{es}} API.
4141

@@ -207,12 +207,14 @@ PUT _index_template/my_template
207207
:::
208208
::::
209209

210-
## Create an initial managed index [create-initial-index]
210+
## Create an initial managed index and alias [create-initial-index]
211211

212212
When you set up policies for your own rolling indices and are not using the recommended [data streams](../../data-store/data-streams.md), you must manually create the first index managed by a policy and designate it as the write index.
213213

214214
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.
215215

216+
This step is required only when you're planning to use {{ilm-init}} with rolling indices. It is not required when you're using data streams, where the initial managed index is created automatically.
217+
216218
::::{important}
217219
When you enable {{ilm}} for {{beats}}, {{agent}}, or for the {{agent}} or {{ls}} {{es}} output plugins, the necessary policies and configuration changes are applied automatically. If you'd like to create a specialized ILM policy for any data stream, refer to our tutorial [Customize built-in policies](/manage-data/lifecycle/index-lifecycle-management/tutorial-customize-built-in-policies.md).
218220
::::
@@ -250,7 +252,7 @@ Now you can start indexing data to the rollover alias specified in the lifecycle
250252
:sync: api
251253
Use the [Create an index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-create) to create the initial managed index.
252254

253-
The following request creates the `test-000001` index. Because it matches the index pattern specified in `my_template`, {{es}} automatically applies the settings from that template.
255+
The following request creates the `test-000001` index, with the alias `test-alias`. Because the index name matches the index pattern specified in `my_template`, {{es}} automatically applies the settings from that template.
254256

255257
```console
256258
PUT test-000001

0 commit comments

Comments
 (0)