OpenSearch/docs/reference/ilm/getting-started-ilm.asciidoc

[role="xpack"]
[testenv="basic"]
[[getting-started-index-lifecycle-management]]
== Getting started with {ilm}

Let's jump into {ilm} ({ilm-init}) by working through a hands-on scenario.
This section will leverage many new concepts unique to {ilm-init} that
you may not be familiar with. The following sections will explore
these in more details.

The goal of this example is to set up a set of indices that will encapsulate
the data from a time series data source. We can imagine there is a system
like {filebeat-ref}[Filebeat] that continuously indexes documents into
our writing index. We wish to roll over the index after it reaches a size
of 50 gigabytes, or has been created 30 days ago, and then delete the index
after 90 days.

=== Setting up a new policy

There are many new features introduced by {ilm-init}, but we will only focus on
a few that are needed for our example. For starters, we will use the
<<ilm-put-lifecycle,Put Policy>> API to define our first policy. Lifecycle
policies are defined in JSON and include specific
<<ilm-policy-definition,phases and actions>>.

[source,js]
------------------------
PUT _ilm/policy/datastream_policy   <1>
{
  "policy": {                       <2>
    "phases": {
      "hot": {                      <3>
        "actions": {
          "rollover": {             <4>
            "max_size": "50GB",
            "max_age": "30d"
          }
        }
      },
      "delete": {
        "min_age": "90d",           <5>
        "actions": {
          "delete": {}              <6>
        }
      }
    }
  }
}
------------------------
// CONSOLE
// TEST
<1> call to the <<ilm-put-lifecycle,put lifecycle API>> endpoint to create
    a new policy named "datastream_policy"
<2> policy definition sub-object
<3> the hot phase defined in the "phases" section. Optional `min_age` field
    not defined -- defaults to `0ms`
<4> rollover action definition
<5> delete phase begins after 90 days
<6> delete action definition


Here we created the policy called `datastream_policy` which rolls over
the index being written to after it reaches 50 gigabytes, or it is 30
days old. The rollover will occur when either of these conditions is true.
The index will be deleted 90 days after it is rolled over.

=== Applying a policy to our index

There are <<set-up-lifecycle-policy,a few ways>> to associate a
policy to an index. Since we wish specific settings to be applied to
the new index created from Rollover, we will set the policy via
index templates.


[source,js]
-----------------------
PUT _template/datastream_template
{
  "index_patterns": ["datastream-*"],                 <1>
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1,
    "index.lifecycle.name": "datastream_policy",      <2>
    "index.lifecycle.rollover_alias": "datastream"    <3>
  }
}
-----------------------
// CONSOLE
// TEST[continued]
<1> match all indices starting with "datastream-". These will include all
    newly created indices from actions like rollover
<2> the name of the lifecycle policy managing the index
<3> alias to use for the rollover action, required since a rollover action is
    defined in the policy.

The above index template introduces a few new settings specific to {ilm-init}.
The first being `index.lifecycle.name`. This setting will configure
the "datastream_policy" to the index applying this template. This means
that all newly created indices prefixed "datastream-" will be managed by
our policy. The other setting used here is `index.lifecycle.rollover_alias`.
This setting is required when using a policy containing the rollover
action and specifies which alias to rollover on behalf of this index.
The intention here is that the rollover alias is also defined on the index.

To begin, we will want to bootstrap our first index to write to.


[source,js]
-----------------------
PUT datastream-000001?include_type_name=true
{
  "aliases": {
    "datastream": {
      "is_write_index": true
    }
  }
}
-----------------------
// CONSOLE
// TEST[continued]

When creating our index, we have to consider a few important configurations
that tie our index and our policy together correctly. We need to make sure
that our index name matches our index template pattern of "datastream-*",
which it does. We are using the <<ilm-rollover-action, Rollover Action>> in our policy, which
requires that our index name ends with a number. In our case, we used
`000001`. This is important so that Rollover can increment this number when
naming the new index created from rolling over.

Our index creation request leverages its template to apply our settings,
but we must also configure our rollover alias: "datastream". To do this,
we take advantage of <<aliases-write-index,write indices>>. This is a way
to define an alias to be used for both reading and writing, with only one
index being the index that is being written to at a time. Rollover swaps
the write index to be the new index created from rollover, and sets the
alias to be read-only for the source index.

=== Checking progress

Now that we have an index managed by our policy, how do we tell what is going
on? Which phase are we in? Is something broken? This section will go over a
few APIs and their responses to help us inspect our indices with respect
to {ilm-init}.

With the help of the <<ilm-explain-lifecycle,Explain API>>, we can know
things like which phase we're in and when we entered that phase. The API
will also provide further info if errors occurred, or if we are blocked on
certain checks within actions.

[source,js]
--------------------------------------------------
GET datastream-*/_ilm/explain
--------------------------------------------------
// CONSOLE
// TEST[continued]

The above request will retrieve {ilm-init} execution information for all our
managed indices.


[source,js]
--------------------------------------------------
{
  "indices": {
    "datastream-000001": {
      "index": "datastream-000001",
      "managed": true,                           <1>
      "policy": "datastream_policy",             <2>
      "lifecycle_date_millis": 1538475653281,
      "phase": "hot",                            <3>
      "phase_time_millis": 1538475653317,
      "action": "rollover",                      <4>
      "action_time_millis": 1538475653317,
      "step": "attempt-rollover",                <5>
      "step_time_millis": 1538475653317,
      "phase_execution": {
        "policy": "datastream_policy",
        "phase_definition": {                    <6>
          "min_age": "0ms",
          "actions": {
            "rollover": {
              "max_size": "50gb",
              "max_age": "30d"
            }
          }
        },
        "version": 1,                            <7>
        "modified_date_in_millis": 1539609701576
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TESTRESPONSE[skip:no way to know if we will get this response immediately]
<1> this index is managed by ILM
<2> the policy in question, in this case, "datastream_policy"
<3> what phase the index is currently in
<4> what action the index is currently on
<5> what step the index is currently on
<6> the definition of the phase
    (in this case, the "hot" phase) that the index is currently on
<7> the version of the policy being used to execute the current phase

You can read about the full details of this response in the
<<ilm-explain-lifecycle, explain API docs>>. For now, let's focus on how
the response details which phase, action, and step we're in. We are in the
"hot" phase, and "rollover" action. Rollover will continue to be called
by {ilm-init} until its conditions are met and it rolls over the index.
Afterwards, the original index will stay in the hot phase until 90 more
days pass and it is deleted in the delete phase.
As time goes on, new indices will be created and deleted.
With `datastream-000002` being created when the index mets the rollover
conditions and `datastream-000003` created after that. We will be able
to search across all of our managed indices using the "datastream" alias,
and we will be able to write to our to-be-rolled-over write indices using
that same alias.



That's it! We have our first use-case managed by {ilm-init}.

To learn more about all our APIs,
check out <<index-lifecycle-management-api,ILM APIs>>.