From dbf6ba7e21a0d21f5b8b3e33f1c6ce269c1e4489 Mon Sep 17 00:00:00 2001
From: Colin Goodheart-Smithe <colings86@users.noreply.github.com>
Date: Tue, 28 Aug 2018 15:47:01 +0100
Subject: [PATCH] Adds docs for how to set up a policy (#32987)

* Adds docs for how to set up a policy

* Fix failing docs test
---
 .../en/ilm/set-up-lifecycle-policy.asciidoc   | 110 +++++++++++++++++-
 1 file changed, 107 insertions(+), 3 deletions(-)

diff --git a/x-pack/docs/en/ilm/set-up-lifecycle-policy.asciidoc b/x-pack/docs/en/ilm/set-up-lifecycle-policy.asciidoc
index b624de27008..4d735b08dda 100644
--- a/x-pack/docs/en/ilm/set-up-lifecycle-policy.asciidoc
+++ b/x-pack/docs/en/ilm/set-up-lifecycle-policy.asciidoc
@@ -1,6 +1,110 @@
 [[set-up-lifecycle-policy]]
 == Set up {ilm} policy
 
-Focus on how this is done in the general sense, not the fine points about
-rollover just yet. Specifically that `index.lifecycle.name` can be used here
-too, not just the create index API explicitly.
+In order for an index to use an {ilm} policy to manage its lifecycle we must
+first define a lifecycle policy for it to use. The following request creates
+a policy called `my_policy` in Elasticsearch which we can later use to manage
+our indexes.
+
+[source,js]
+------------------------
+PUT _ilm/my_policy
+{
+  "policy": {
+    "phases": {
+      "hot": {
+        "actions": {
+          "rollover": {
+            "max_size": "25GB" <1>
+          }
+        }
+      },
+      "delete": {
+        "after": "30d",
+        "actions": {
+          "delete": {} <2>
+        }
+      }
+    }
+  }
+}
+------------------------ 
+// CONSOLE
+<1> Rollover the index when it reaches 25GB in size
+<2> Delete the index when its 30 days old
+
+{ilm} will manage an index using the policy defined in the 
+`index.lifecycle.name` index setting. If this setting does not exist in the
+settings for a particular index {ilm} will not manage that index.
+
+To set the policy for an index there are two options:
+1. Apply the policy to an index template and bootstrap creating the first index
+2. Apply the policy to a new index in a create index request
+
+=== Applying a policy to an index template
+
+The `index.lifecycle.name` setting can be set in an index template so that it
+is automatically applied to indexes matching the templates index pattern:
+
+[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"
+  }
+}
+-----------------------
+// CONSOLE
+<1> This template will be applied to all indexes which have a name starting
+with `test-`
+<2> The template will set the policy to be used to `my_policy`
+
+Now that a policy exists and is used in an index template we can create an
+initial index which will be managed by our policy:
+
+[source,js]
+-----------------------
+PUT test-000001
+{
+  "aliases": {
+    "test-alias":{
+      "is_write_index": true <1>
+    }
+  }
+}
+-----------------------
+// CONSOLE
+<1> Set this initial index to be the write index for this alias.
+
+We can now write data to the `test-alias` alias. Because we have a rollover
+action defined in our policy when the index grows larger than 25GB {ilm} will
+create a new index and roll the alias over to use the new index automatically.
+
+=== Apply a policy to a create index request
+
+The `index.lifecycle.name` setting can be set on an individual create index
+request so {ilm} immediately starts managing the index:
+
+[source,js]
+-----------------------
+PUT test-index
+{
+  "settings": {
+    "number_of_shards": 1,
+    "number_of_replicas": 1,
+    "index.lifecycle.name": "my_policy"
+  }
+}
+-----------------------
+// CONSOLE
+
+NOTE: it is not recommended to set the policy on the index creation request if
+you are using the rollover action as the indexes created by the rollover action
+will not have the policy set. IF you are using the rollover action in your 
+policy its recommended to set the policy in an index template.
+