[ILM][DOCS] add extra scenario to policy update docs

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 20, 2018 · b0dd442 · b0dd442
1 parent 9c1e47d
commit b0dd442
Showing 1 changed file with 86 additions and 5 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,85 @@ 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",
+        "actions": {
+          "rollover": {
+            "max_docs": 1
+          }
+        }
+      },
+      "delete": {
+        "min_age": "10d",
+        "actions": {
+          "delete": {}
+        }
+      }
+    }
+  }
+}
+------------------------
+// CONSOLE
+// TEST[continued]
+
+Now, version 2 of this policy has `min_age` for the hot phase set to one day, 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]
+--------------------------------------------------
+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,
+        "phase_definition": {
+          "min_age": "0ms",
+          "actions": {
+            "rollover": {
+              "max_docs": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TESTRESPONSE[skip:no way to know if we will get this response immediately]
+
+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,7 +337,7 @@ 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.
+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.
 
 ////
@@ -304,7 +385,7 @@ GET my_index/_ilm/explain
 // TESTRESPONSE[skip:no way to know if we will get this response immediately]
 
 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.
+index will move into the next phase in the updated version 3 of its policy.
 
 ////
 [source,js]
@@ -338,7 +419,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 +435,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.