[DOCS] Add ML limitation and troubleshooting (elastic/x-pack-elasticsearch#3929)

Original commit: elastic/x-pack-elasticsearch@bfabcbb456

docs/en/ml/limitations.asciidoc

@@ -167,7 +167,7 @@ updated then the {dfeed} subsequently runs with the new permissions that are
 associated with the roles. However, if the user's roles are adjusted after
 creating or updating the {dfeed}, the {dfeed} continues to run with the
 permissions that were associated with the original roles. For more information,
-see <<ml-dfeeds>>. 
+see <<ml-dfeeds>>.
 
 [float]
 === Forecasts cannot be created for population jobs
@@ -189,3 +189,10 @@ create a forecast:
 
 If you try to create a forecast for this type of job, an error occurs. For more
 information about any of these functions, see <<ml-functions>>.
+
+[float]
+=== Jobs must be stopped before upgrades
+
+You must stop any {ml} jobs that are running before you start the upgrade
+process. For more information, see <<stopping-ml>> and
+{stack-ref}/upgrading-elastic-stack.html[Upgrading the Elastic Stack].

docs/en/ml/troubleshooting.asciidoc

@@ -84,3 +84,33 @@ Create jobs in {kib} or ensure that you create jobs with valid identifiers when
 you use the {ml} APIs. For more information about valid identifiers, see
 {ref}/ml-put-job.html[Create Jobs API] or
 {ref}/ml-job-resource.html[Job Resources].
+
+[[ml-upgradedf]]
+
+=== Upgraded nodes fail to start due to {dfeed} issues
+
+This problem occurs when you have a {dfeed} that contains search or query
+domain specific language (DSL) that was discontinued. For example, if you
+created a {dfeed} query in 5.x using search syntax that was deprecated in 5.x
+and removed in 6.0, you must fix the {dfeed} before you upgrade to 6.0.
+
+*Symptoms:*
+
+* If {ref}/logging.html#deprecation-logging[deprecation logging] is enabled
+before the upgrade, deprecation messages are generated when the {dfeeds} attempt
+to retrieve data.
+* After the upgrade, nodes fail to start and the error indicates that they
+failed to read the local state.
+
+*Resolution:*
+
+Before you upgrade, identify the problematic search or query DSL. In 5.6.5 and
+later, the Upgrade Assistant detects these scenarios. If you cannot fix the DSL
+before the upgrade, you must delete the {dfeed} then re-create it with valid DSL
+after the upgrade.
+
+If you do not fix or delete the {dfeed} before the upgrade, in order to successfully
+start the failing nodes you must downgrade the nodes then fix the problem per
+above.
+
+See also {stack-ref}/upgrading-elastic-stack.html[Upgrading the Elastic Stack].