[ILM][DOCS] add extra scenario to policy update docs (#36871)

This extra scenario describes the case where an updated policy increases the current phase's `min_age`. Now, the docs explicitly describe this scenario as to what is expected -- old min_age is used. Closes #35356.
elastic · Dec 21, 2018 · 25625d2 · 25625d2
1 parent c13a7bc
commit 25625d2
Showing 1 changed file with 93 additions and 8 deletions.
diff --git a/docs/reference/ilm/update-lifecycle-policy.asciidoc b/docs/reference/ilm/update-lifecycle-policy.asciidoc
@@ -13,6 +13,9 @@ strategies for newly created indices. It is possible to update policy definition
 and an index's `index.lifecycle.name` settings independently. To prevent the situation
 that phase definitions are modified while currently being executed on an index, each index
 will keep the version of the current phase definition it began execution with until it completes.
+This also means that changes to `min_age` will not be propagated. If a new policy is set that
+introduces a later `min_age` for the currently executing phase, that new `min_age` will not
+be picked up by the update.
 
 There are three scenarios for examining the behavior updating policies and
 their effects on policy execution on indices.
@@ -227,7 +230,86 @@ GET my_index/_ilm/explain
 // CONSOLE
 // TESTRESPONSE[skip:no way to know if we will get this response immediately]
 
-Updating `my_executing_policy` to have no rollover action and, instead, go directly into a newly introduced `warm` phase.
+We can update `my_executing_policy` to enter the hot phase after one day.
+
+[source,js]
+------------------------
+PUT _ilm/policy/my_executing_policy
+{
+  "policy": {
+    "phases": {
+      "hot": {
+        "min_age": "1d", <1>
+        "actions": {
+          "rollover": {
+            "max_docs": 1
+          }
+        }
+      },
+      "delete": {
+        "min_age": "10d",
+        "actions": {
+          "delete": {}
+        }
+      }
+    }
+  }
+}
+------------------------
+// CONSOLE
+// TEST[continued]
+<1> updated `min_age` from "0ms" to "1d"
+
+The index `my_index` has already entered the hot phase, so it will still
+use version 1 of the policy until it completes the hot phase.
+
+////
+[source,js]
+--------------------------------------------------
+GET my_index/_ilm/explain
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+////
+
+[source,js]
+--------------------------------------------------
+{
+  "indices": {
+    "my_index": {
+      "index": "my_index",
+      "managed": true,
+      "policy": "my_executing_policy",
+      "lifecycle_date_millis": 1538475653281,
+      "phase": "hot",
+      "phase_time_millis": 1538475653317,
+      "action": "rollover",
+      "action_time_millis": 1538475653317,
+      "step": "check-rollover-ready",
+      "step_time_millis": 1538475653317,
+      "phase_execution": {
+        "policy": "my_executing_policy",
+        "modified_date_in_millis": 1538475653317,
+        "version": 1, <1>
+        "phase_definition": {
+          "min_age": "0ms",
+          "actions": {
+            "rollover": {
+              "max_docs": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TESTRESPONSE[skip:no way to know if we will get this response immediately]
+<1> the version of the policy used for executing the hot phase
+
+We can also update `my_executing_policy` to have no rollover action and,
+instead, go directly into a newly introduced `warm` phase.
 
 [source,js]
 ------------------------
@@ -256,8 +338,9 @@ PUT _ilm/policy/my_executing_policy
 // CONSOLE
 // TEST[continued]
 
-Now, version 2 of this policy has no `hot` phase, but if we run the Explain API again, we will see that nothing has changed.
-The index `my_index` is still executing version 1 of the policy.
+Now, version 3 of this policy has no `hot` phase, but if we run the
+Explain API again, we will see that nothing has changed. The index
+`my_index` is still executing version 1 of the policy.
 
 ////
 [source,js]
@@ -286,7 +369,7 @@ GET my_index/_ilm/explain
       "phase_execution": {
         "policy": "my_executing_policy",
         "modified_date_in_millis": 1538475653317,
-        "version": 1,
+        "version": 1, <1>
         "phase_definition": {
           "min_age": "0ms",
           "actions": {
@@ -302,9 +385,11 @@ GET my_index/_ilm/explain
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[skip:no way to know if we will get this response immediately]
+<1> the version of the policy used for executing the hot phase
 
-After indexing one document into `my_index` so that rollover succeeds and moves onto the next phase, we will notice something new. The
-index will move into the next phase in the updated version 2 of its policy.
+After indexing one document into `my_index` so that rollover succeeds and
+moves onto the next phase, we will notice something new. The index will
+move into the next phase in the updated version 3 of its policy.
 
 ////
 [source,js]
@@ -338,7 +423,7 @@ GET my_index/_ilm/explain
       "phase_execution": {
         "policy": "my_executing_policy",
         "modified_date_in_millis": 1538475653317,
-        "version": 2, <1>
+        "version": 3, <1>
         "phase_definition": {
           "min_age": "1d",
           "actions": {
@@ -354,7 +439,7 @@ GET my_index/_ilm/explain
 --------------------------------------------------
 // CONSOLE
 // TESTRESPONSE[skip:There is no way to force the index to move to the next step in a timely manner]
-<1> The index has moved to using version 2 of the policy
+<1> The index has moved to using version 3 of the policy
 
 `my_index` will move to the next phase in the latest policy definition, which is the newly added `warm` phase.