Start with data stream lifecycle documentation (#95326)

Author: gmarouli

docs/reference/data-management.asciidoc

@@ -20,17 +20,32 @@ so you can move it to less expensive, less performant hardware.
 For your oldest data, what matters is that you have access to the data. 
 It's ok if queries take longer to complete.
 
-To help you manage your data, {es} enables you to:
+To help you manage your data, {es} offers you:
 
+* <<index-lifecycle-management, {ilm-cap}>> ({ilm-init}) to manage both indices and data streams and it is fully customisable, and
+* <<data-stream-lifecycle, Data stream lifecycle>> which is the built-in lifecycle of data streams and addresses the most
+common lifecycle management needs.
+
+preview::["The built-in data stream lifecycle is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but this feature is not subject to the support SLA of official GA features."]
+
+**{ilm-init}** can be used to manage both indices and data streams and it allows you to:
+
+* Define the retention period of your data. The retention period is the minimum time your data will be stored in {es}.
+Data older than this period can be deleted by {es}.
 * Define <<data-tiers, multiple tiers>> of data nodes with different performance characteristics.
-* Automatically transition indices through the data tiers according to your performance needs and retention policies
-with <<index-lifecycle-management, {ilm}>> ({ilm-init}). 
+* Automatically transition indices through the data tiers according to your performance needs and retention policies.
 * Leverage <<searchable-snapshots, searchable snapshots>> stored in a remote repository to provide resiliency 
 for your older indices while reducing operating costs and maintaining search performance.  
 * Perform <<async-search-intro, asynchronous searches>> of data stored on less-performant hardware.
+
+**Data stream lifecycle** is less feature rich but is focused on simplicity, so it allows you to easily:
+
+* Define the retention period of your data. The retention period is the minimum time your data will be stored in {es}.
+Data older than this period can be deleted by {es} at a later time.
+* Improve the performance of your data stream by performing background operations that will optimise the way your data
+stream is stored.
 --
 
 include::ilm/index.asciidoc[]
 
 include::datatiers.asciidoc[]
-

docs/reference/data-streams/data-stream-apis.asciidoc

@@ -12,6 +12,14 @@ The following APIs are available for managing <<data-streams,data streams>>:
 * <<promote-data-stream-api>>
 * <<modify-data-streams-api>>
 
+[[data-stream-lifecycle-api]]
+The following APIs are available for managing the built-in lifecycle of data streams:
+
+* <<data-streams-put-lifecycle,Update data stream lifecycle>> preview:[]
+* <<data-streams-get-lifecycle,Get data stream lifecycle>> preview:[]
+* <<data-streams-delete-lifecycle,Delete data stream lifecycle>> preview:[]
+* <<data-streams-explain-lifecycle,Explain data stream lifecycle>> preview:[]
+
 The following API is available for <<tsds,time series data streams>>:
 
 * <<indices-downsample-data-stream>>
@@ -33,4 +41,12 @@ include::{es-repo-dir}/data-streams/promote-data-stream-api.asciidoc[]
 
 include::{es-repo-dir}/data-streams/modify-data-streams-api.asciidoc[]
 
+include::{es-repo-dir}/data-streams/lifecycle/apis/put-lifecycle.asciidoc[]
+
+include::{es-repo-dir}/data-streams/lifecycle/apis/get-lifecycle.asciidoc[]
+
+include::{es-repo-dir}/data-streams/lifecycle/apis/delete-lifecycle.asciidoc[]
+
+include::{es-repo-dir}/data-streams/lifecycle/apis/explain-lifecycle.asciidoc[]
+
 include::{es-repo-dir}/indices/downsample-data-stream.asciidoc[]

docs/reference/data-streams/data-streams.asciidoc

@@ -135,3 +135,4 @@ include::set-up-a-data-stream.asciidoc[]
 include::use-a-data-stream.asciidoc[]
 include::change-mappings-and-settings.asciidoc[]
 include::tsds.asciidoc[]
+include::lifecycle/index.asciidoc[]

docs/reference/dlm/apis/delete-lifecycle.asciidoc renamed to docs/reference/data-streams/lifecycle/apis/delete-lifecycle.asciidoc

@@ -1,10 +1,10 @@
-[[dlm-delete-lifecycle]]
+[[data-streams-delete-lifecycle]]
 === Delete the lifecycle of a data stream
 ++++
 <titleabbrev>Delete Data Stream Lifecycle</titleabbrev>
 ++++
 
-experimental::[]
+preview::[]
 
 Deletes the lifecycle from a set of data streams.
 
@@ -14,18 +14,18 @@ Deletes the lifecycle from a set of data streams.
 * If the {es} {security-features} are enabled, you must have the `manage_data_stream_lifecycle` index privilege or higher to
 use this API. For more information, see <<security-privileges>>.
 
-[[dlm-delete-lifecycle-request]]
+[[data-streams-delete-lifecycle-request]]
 ==== {api-request-title}
 
 `DELETE _data_stream/<data-stream>/_lifecycle`
 
-[[dlm-delete-lifecycle-desc]]
+[[data-streams-delete-lifecycle-desc]]
 ==== {api-description-title}
 
 Deletes the lifecycle from the specified data streams. If multiple data streams are provided but at least one of them
 does not exist, then the deletion of the lifecycle will fail for all of them and the API will respond with `404`.
 
-[[dlm-delete-lifecycle-path-params]]
+[[data-streams-delete-lifecycle-path-params]]
 ==== {api-path-parms-title}
 
 `<data-stream>`::
@@ -41,7 +41,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=ds-expand-wildcards]
 +
 Defaults to `open`.
 
-[[dlm-delete-lifecycle-example]]
+[[data-streams-delete-lifecycle-example]]
 ==== {api-examples-title}
 
 ////

docs/reference/dlm/apis/explain-data-lifecycle.asciidoc renamed to docs/reference/data-streams/lifecycle/apis/explain-lifecycle.asciidoc

@@ -1,41 +1,39 @@
-[[dlm-explain-lifecycle]]
-=== Explain Lifecycle API
+[[data-streams-explain-lifecycle]]
+=== Explain data stream lifecycle
 ++++
-<titleabbrev>Explain Data Lifecycle</titleabbrev>
+<titleabbrev>Explain Data Stream Lifecycle</titleabbrev>
 ++++
 
-experimental::[]
+preview::[]
 
 Retrieves the current data lifecycle status for one or more data stream backing indices.
 
 [[explain-lifecycle-api-prereqs]]
 ==== {api-prereq-title}
 
-* Nit: would rephrase as:
-
 If the {es} {security-features} are enabled, you must have at least the `manage_data_stream_lifecycle` index privilege or
 `view_index_metadata` index privilege to use this API. For more information, see <<security-privileges>>.
 
-[[dlm-explain-lifecycle-request]]
+[[data-streams-explain-lifecycle-request]]
 ==== {api-request-title}
 
 `GET <target>/_lifecycle/explain`
 
-[[dlm-explain-lifecycle-desc]]
+[[data-streams-explain-lifecycle-desc]]
 ==== {api-description-title}
 
-Retrieves information about the index's current DLM lifecycle state, such as
+Retrieves information about the index or data stream's current data stream lifecycle state, such as
 time since index creation, time since rollover, the lifecycle configuration
 managing the index, or any error that {es} might've encountered during the lifecycle
 execution.
 
-[[dlm-explain-lifecycle-path-params]]
+[[data-streams-explain-lifecycle-path-params]]
 ==== {api-path-parms-title}
 
 `<target>`::
 (Required, string) Comma-separated list of indices.
 
-[[dlm-explain-lifecycle-query-params]]
+[[data-streams-explain-lifecycle-query-params]]
 ==== {api-query-parms-title}
 
 `include_defaults`::
@@ -44,7 +42,7 @@ execution.
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
-[[dlm-explain-lifecycle-example]]
+[[data-streams-explain-lifecycle-example]]
 ==== {api-examples-title}
 
 The following example retrieves the lifecycle state of the index `.ds-metrics-2023.03.22-000001`:
@@ -53,9 +51,9 @@ The following example retrieves the lifecycle state of the index `.ds-metrics-20
 --------------------------------------------------
 GET .ds-metrics-2023.03.22-000001/_lifecycle/explain
 --------------------------------------------------
-// TEST[skip:we're not setting up DLM in these tests]
+// TEST[skip:we're not setting up data stream lifecycle in these tests]
 
-If the index is managed by DLM `explain` will show the `managed_by_lifecycle` field
+If the index is managed by a data stream lifecycle `explain` will show the `managed_by_lifecycle` field
 set to `true` and the rest of the response will contain information about the
 lifecycle execution status for this index:
 
@@ -77,8 +75,8 @@ lifecycle execution status for this index:
 --------------------------------------------------
 // TESTRESPONSE[skip:the result is for illustrating purposes only]
 
-<1> Shows if the index is being managed by DLM. If the index is not managed by
-DLM the other fields will not be shown
+<1> Shows if the index is being managed by data stream lifecycle. If the index is not managed by
+a data stream lifecycle the other fields will not be shown
 <2> When the index was created, this timestamp is used to determine when to
 rollover
 <3> The time since the index creation (used for calculating when to rollover

docs/reference/dlm/apis/get-lifecycle.asciidoc renamed to docs/reference/data-streams/lifecycle/apis/get-lifecycle.asciidoc

@@ -1,10 +1,10 @@
-[[dlm-get-lifecycle]]
+[[data-streams-get-lifecycle]]
 === Get the lifecycle of a data stream
 ++++
 <titleabbrev>Get Data Stream Lifecycle</titleabbrev>
 ++++
 
-experimental::[]
+preview::[]
 
 Gets the lifecycle of a set of data streams.
 
@@ -15,20 +15,20 @@ Gets the lifecycle of a set of data streams.
 <<privileges-list-indices,index privilege>>, the `manage_data_stream_lifecycle` index privilege, or the
 `view_index_metadata` privilege to use this API. For more information, see <<security-privileges>>.
 
-[[dlm-get-lifecycle-request]]
+[[data-streams-get-lifecycle-request]]
 ==== {api-request-title}
 
 `GET _data_stream/<data-stream>/_lifecycle`
 
-[[dlm-get-lifecycle-desc]]
+[[data-streams-get-lifecycle-desc]]
 ==== {api-description-title}
 
 Gets the lifecycle of the specified data streams. If multiple data streams are requested but at least one of them
 does not exist, then the API will respond with `404` since at least one of the requested resources could not be retrieved.
 If the requested data streams do not have a lifecycle configured they will still be included in the API response but the
 `lifecycle` key will be missing.
 
-[[dlm-get-lifecycle-path-params]]
+[[data-streams-get-lifecycle-path-params]]
 ==== {api-path-parms-title}
 
 `<data-stream>`::
@@ -75,12 +75,12 @@ duration the document could be deleted. When undefined, every document in this d
 `rollover`::
 (Optional, object)
 The conditions which will trigger the rollover of a backing index as configured by the cluster setting
-`cluster.lifecycle.default.rollover`. This property is an implementation detail and it will only be retrieved when the query
-param `include_defaults` is set to `true`. The contents of this field are subject to change.
+`cluster.lifecycle.default.rollover`. This property is an implementation detail and it will only be retrieved
+when the query param `include_defaults` is set to `true`. The contents of this field are subject to change.
 =====
 ====
 
-[[dlm-get-lifecycle-example]]
+[[data-streams-get-lifecycle-example]]
 ==== {api-examples-title}
 
 ////

docs/reference/dlm/apis/put-lifecycle.asciidoc renamed to docs/reference/data-streams/lifecycle/apis/put-lifecycle.asciidoc

@@ -1,10 +1,10 @@
-[[dlm-put-lifecycle]]
+[[data-streams-put-lifecycle]]
 === Set the lifecycle of a data stream
 ++++
 <titleabbrev>Put Data Stream Lifecycle</titleabbrev>
 ++++
 
-experimental::[]
+preview::[]
 
 Configures the data lifecycle for the targeted data streams.
 
@@ -14,18 +14,18 @@ Configures the data lifecycle for the targeted data streams.
 If the {es} {security-features} are enabled, you must have the `manage_data_stream_lifecycle` index privilege or higher to use this API.
 For more information, see <<security-privileges>>.
 
-[[dlm-put-lifecycle-request]]
+[[data-streams-put-lifecycle-request]]
 ==== {api-request-title}
 
 `PUT _data_stream/<data-stream>/_lifecycle`
 
-[[dlm-put-lifecycle-desc]]
+[[data-streams-put-lifecycle-desc]]
 ==== {api-description-title}
 
 Configures the data lifecycle for the targeted data streams. If multiple data streams are provided but at least one of them
 does not exist, then the update of the lifecycle will fail for all of them and the API will respond with `404`.
 
-[[dlm-put-lifecycle-path-params]]
+[[data-streams-put-lifecycle-path-params]]
 ==== {api-path-parms-title}
 
 `<data-stream>`::
@@ -55,7 +55,7 @@ If defined, every document added to this data stream will be stored at least for
 duration the document could be deleted. When empty, every document in this data stream will be stored indefinitely.
 ====
 
-[[dlm-put-lifecycle-example]]
+[[data-streams-put-lifecycle-example]]
 ==== {api-examples-title}
 
 The following example sets the lifecycle of `my-data-stream`:

docs/reference/data-streams/lifecycle/index.asciidoc

@@ -0,0 +1,64 @@
+[role="xpack"]
+[[data-stream-lifecycle]]
+== Data stream lifecycle
+
+preview::[]
+
+A data stream lifecycle is the built-in mechanism data streams use to manage their lifecycle. It enables you to easily
+automate the management of your data streams according to your retention requirements. For example, you could configure
+the lifecycle to:
+
+* Ensure that data indexed in the data stream will be kept at least for the retention time you defined.
+* Ensure that data older than the retention period will be deleted automatically by {es} at a later time.
+
+To achieve that, it supports:
+
+* Automatic <<index-rollover,rollover>>, which chunks your incoming data in smaller pieces to facilitate better performance
+and backwards incompatible mapping changes.
+* Configurable retention, which allows you to configure the time period for which your data is guaranteed to be stored.
+{es} is allowed at a later time to delete data older than this time period.
+
+[discrete]
+[[data-streams-lifecycle-how-it-works]]
+=== How does it work?
+
+In intervals configured by <<data-streams-lifecycle-poll-interval,`data_streams.lifecycle.poll_interval`>>, {es} goes over
+each data stream and performs the following steps:
+
+1. Checks if the data stream has a data lifecycle configured, skipping any indices not part of a managed data stream.
+2. Rolls over the write index of the data stream, if it fulfills the conditions defined by
+<<cluster-lifecycle-default-rollover,`cluster.lifecycle.default.rollover`>>.
+3. Applies retention to the remaining backing indices. This means deleting the backing indices whose
+`generation_time` is longer than the configured retention period. The `generation_time` is only applicable to rolled over backing
+indices and it is either the time since the backing index got rolled over, or the time optionally configured in the
+<<index-data-stream-lifecycle-origination-date,`index.lifecycle.origination_date`>> setting.
+
+IMPORTANT: We use the `generation_time` instead of the creation time because this ensures that all data in the backing
+index have passed the retention period. As a result, the retention period is not the exact time data gets deleted, but
+the minimum time data will be stored.
+
+NOTE: The steps `2` and `3` apply only to backing indices that are not already managed by {ilm-init}, meaning that these indices either do
+not have an {ilm-init} policy defined, or if they do, they have <<index-lifecycle-prefer-ilm,`index.lifecycle.prefer_ilm`>>
+set to `false`.
+
+[discrete]
+[[data-stream-lifecycle-configuration]]
+=== Configuring data stream lifecycle
+
+Since the lifecycle is configured on the data stream level, the process to configure a lifecycle on a new data stream and
+on an existing one differ.
+
+In the following sections, we will go through the following tutorials:
+
+* To create a new data stream with a lifecycle, you need to add the data lifecycle as part of the index template
+that matches the name of your data stream (see <<tutorial-manage-new-data-stream>>). When a write operation
+with the name of your data stream reaches {es} then the data stream will be created with the respective data lifecycle.
+* To update the lifecycle of an existing data stream you need to use the <<data-stream-lifecycle-api, data stream lifecycle APIs>>
+to edit the lifecycle on the data stream itself (see <<tutorial-manage-existing-data-stream>>).
+
+NOTE: Updating the data lifecycle of an existing data stream is different from updating the settings or the mapping,
+because it is applied on the data stream level and not on the individual backing indices.
+
+include::tutorial-manage-new-data-stream.asciidoc[]
+
+include::tutorial-manage-existing-data-stream.asciidoc[]