From d300048cd5f1360ac2787703c401936fbb9ce186 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Fri, 15 Feb 2019 09:29:45 -0800
Subject: [PATCH] [DOCS] Updates methods for upgrading machine learning
 (#38876) (#38967)

---
 docs/reference/upgrade/close-ml.asciidoc      | 32 +++++++++++++++++++
 .../upgrade/cluster_restart.asciidoc          | 11 +++++--
 docs/reference/upgrade/open-ml.asciidoc       | 13 ++++++++
 .../upgrade/rolling_upgrade.asciidoc          | 12 +++++--
 4 files changed, 64 insertions(+), 4 deletions(-)
 create mode 100644 docs/reference/upgrade/close-ml.asciidoc
 create mode 100644 docs/reference/upgrade/open-ml.asciidoc

diff --git a/docs/reference/upgrade/close-ml.asciidoc b/docs/reference/upgrade/close-ml.asciidoc
new file mode 100644
index 00000000000..c4efddca759
--- /dev/null
+++ b/docs/reference/upgrade/close-ml.asciidoc
@@ -0,0 +1,32 @@
+[testenv="platinum"]
+
+If your {ml} indices were created earlier than the previous major version, they
+must be reindexed. In those circumstances, there must be no machine learning
+jobs running during the upgrade. 
+
+In all other circumstances, there is no requirement to close your {ml} jobs. 
+There are, however, advantages to doing so. If you choose to leave your jobs
+running during the upgrade, they are affected when you stop the {ml} nodes. The
+jobs move to another {ml} node and restore the model states. This scenario has
+the least disruption to the active {ml} jobs but incurs the highest load on the
+cluster.
+
+To close all {ml} jobs before you upgrade, see
+{stack-ov}/stopping-ml.html[Stopping {ml}]. This method persists the model
+state at the moment of closure, which means that when you open your jobs after
+the upgrade, they use the exact same model. This scenario takes the most time,
+however, especially if you have many jobs or jobs with large model states.  
+
+To temporarily halt the tasks associated with your {ml} jobs and {dfeeds} and
+prevent new jobs from opening, use the <<ml-set-upgrade-mode,set upgrade mode API>>:
+
+[source,js]
+--------------------------------------------------
+POST _ml/set_upgrade_mode?enabled=true
+--------------------------------------------------
+// CONSOLE
+
+This method does not persist the absolute latest model state, rather it uses the
+last model state that was automatically saved. By halting the tasks, you avoid
+incurring the cost of managing active jobs during the upgrade and it's quicker
+than stopping {dfeeds} and closing jobs. 
\ No newline at end of file
diff --git a/docs/reference/upgrade/cluster_restart.asciidoc b/docs/reference/upgrade/cluster_restart.asciidoc
index 4c229e373f5..a8552a82bb8 100644
--- a/docs/reference/upgrade/cluster_restart.asciidoc
+++ b/docs/reference/upgrade/cluster_restart.asciidoc
@@ -26,8 +26,11 @@ recovery.
 include::synced-flush.asciidoc[]
 --
 
-. *Stop any machine learning jobs that are running.* See
-{xpack-ref}/stopping-ml.html[Stopping Machine Learning].
+. *Stop any machine learning jobs that are running.* 
++
+--
+include::close-ml.asciidoc[]
+--
 
 . *Shutdown all nodes.*
 +
@@ -132,3 +135,7 @@ GET _cat/recovery
 --
 
 . *Restart machine learning jobs.*
++
+--
+include::open-ml.asciidoc[]
+--
diff --git a/docs/reference/upgrade/open-ml.asciidoc b/docs/reference/upgrade/open-ml.asciidoc
new file mode 100644
index 00000000000..b9b6b772bbe
--- /dev/null
+++ b/docs/reference/upgrade/open-ml.asciidoc
@@ -0,0 +1,13 @@
+[testenv="platinum"]
+If you closed all {ml} jobs before the upgrade, you must open them. Use {kib} or
+the <<ml-open-job,open jobs API>>. 
+
+Alternatively, if you temporarily halted the tasks associated with your {ml} jobs,
+use the <<ml-set-upgrade-mode,set upgrade mode API>> to return them to active
+states:
+
+[source,js]
+--------------------------------------------------
+POST _ml/set_upgrade_mode?enabled=false
+--------------------------------------------------
+// CONSOLE
diff --git a/docs/reference/upgrade/rolling_upgrade.asciidoc b/docs/reference/upgrade/rolling_upgrade.asciidoc
index dff3895ac4c..e62bd9348f1 100644
--- a/docs/reference/upgrade/rolling_upgrade.asciidoc
+++ b/docs/reference/upgrade/rolling_upgrade.asciidoc
@@ -43,8 +43,11 @@ include::synced-flush.asciidoc[]
 
 --
 
-. *Stop any machine learning jobs that are running.* See
-{xpack-ref}/stopping-ml.html[Stopping Machine Learning].
+. *Stop any machine learning jobs that are running.*
++
+--
+include::close-ml.asciidoc[]
+--
 
 . [[upgrade-node]] *Shut down a single node*.
 +
@@ -160,6 +163,11 @@ for each node that needs to be updated.
 --
 
 . *Restart machine learning jobs.*
++
+--
+include::open-ml.asciidoc[]
+--
+
 
 [IMPORTANT]
 ====================================================