Adds documentation about defining rollover action in ILM (#33243)

* Adds documentation about defining rollover aciton in ILM

* Applies review comments

* Addresses further review comments

* Fixes Docs test

x-pack/docs/en/ilm/using-policies-rollover.asciidoc

@@ -1,7 +1,115 @@
 [[using-policies-rollover]]
 == Using policies to manage index rollover
 
-Demonstrate Template Usage - letting `is_write_index` default to true
+The rollover action enables you to automatically roll over to a new index based
-Demonstrate alias swapping - rollover will set new index to the write index
+on the index size, document count, or age. When a rollover is triggered, a new
-Discuss how the `after` param will now be relative to the rollover time
+index is created, the write alias is updated to point to the new index, and all
-Show how after/rollover-conditions interplay with one another
+subsequent updates are written to the new index.
+
+Rolling over to a new index based on size, document count, or age is preferable
+to time-based rollovers. Rolling over at an arbitrary time often results in
+many small indices, which can have a negative impact on performance and
+resource usage.
+
+You control when the rollover action is triggered by specifying one or more
+rollover parameters. The rollover is performed once any of the criteria are
+met. Because the criteria are checked periodically, the index might grow
+slightly beyond the specified threshold. To control how often the critera are
+checked, specify the `indices.lifecycle.poll_interval` cluster setting.
+
+The rollover action takes the following parameters:
+
+.`rollover` Action Parameters
+|===
+|Name |Description
+|max_size |The maximum estimated size the index is allowed to grow
+to. Defaults tonull. Optional.
+|max_docs |The maximum number of document the index should
+contain. Defaults tonull. Optional.
+|max_age |The maximum age of the index. Defaults to `null`. Optional.
+|===
+
+These parameters are used to determine when the index is considered "full" and
+a rollover should be performed. Where multiple criteria are defined the
+rollover operation will be performed once any of the criteria are met.
+
+The following request defines a policy with a rollover action that triggers
+when the index size reaches 25GB. The old index is subsequently deleted after
+30 days.
+
+NOTE: Once an index rolls over, {ilm} uses the timestamp of the rollover
+operation rather than the index creation time to evaluate when to move the
+index to the next phase. For indices that have rolled over, the `after`
+criteria specified for a phase is relative to the rollover time for indices. In
+this example, that means the index will be deleted 30 days after rollover, not
+30 days from when the index was created.
+
+[source,js]
+--------------------------------------------------
+PUT /_ilm/my_policy
+{
+  "policy": {
+    "phases": {
+      "hot": {
+        "actions": {
+          "rollover": {
+            "max_size": "25GB"
+          }
+        }
+      },
+      "delete": {
+        "after": "30d",
+        "actions": {
+          "delete": {}
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+
+To use an {ilm} policy, you need to specify it in the index template used to
+create the indices. For example, the following template associates `my_policy`
+with indices created from the template `my_template`.
+
+[source,js]
+-----------------------
+PUT _template/my_template
+{
+  "index_patterns": ["test-*"], <1>
+  "settings": {
+    "number_of_shards": 1,
+    "number_of_replicas": 1,
+    "index.lifecycle.name": "my_policy", <2>
+    "index.lifecycle.rollover_alias": "test-alias" <3>
+  }
+}
+-----------------------
+// CONSOLE
+<1> Template applies to all indices with the prefix test-
+<2> Associates my_policy with all indices created with this template
+<3> Rolls over the write alias test when the rollover action is triggered
+
+To be able to start using the policy for these `test-*` indexes we need to
+bootstrap the process by creating the first index.
+
+[source,js]
+-----------------------
+PUT test-000001 <1>
+{
+  "aliases": {
+    "test-alias":{
+      "is_write_index": true <2>
+    }
+  }
+}
+-----------------------
+// CONSOLE
+<1> Creates the index called test-000001. The rollover action increments the
+suffix number for each subsequent index.
+<2> Designates this index as the write index for this alias.
+
+When the rollover is performed, the newly-created index is set as the write
+index for the rolled over alias. Documents sent to the alias are indexed into
+the new index, enabling indexing to continue uninterrupted.