[DOCS] Clarified the upgrade path from 6.last (elastic#124769)

The upgrade path info related to upgrading to 7.n from 6.8 is confusing/contradictory. While you can technically upgrade from 6.7 to 7.0, upgrading from 6.8 to 7.0 is not supported. You must upgrade to 7.1 or later from 6.8. While there was a warning about this, the versions specified in later sections were misleading/incorrect. Co-authored-by: Kibana Machine <[email protected]> Co-authored-by: James Rodewig <[email protected]>
kibanamachine · Feb 7, 2022 · f170470 · f170470
1 parent 5cc6b2b
commit f170470
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 29 deletions.
diff --git a/docs/management/upgrade-assistant/index.asciidoc b/docs/management/upgrade-assistant/index.asciidoc
@@ -10,12 +10,11 @@ The assistant identifies deprecated settings in your configuration,
 enables you to see if you are using deprecated features,
 and guides you through the process of resolving issues.
 
+IMPORTANT: To upgrade to 8.0 or later, **you must first upgrade to {version}**.
+
 If you have indices that were created prior to 7.0,
 you can use the assistant to reindex them so they can be accessed from 8.0. 
 
-IMPORTANT: To see the most up-to-date deprecation information before 
-upgrading to 8.0, upgrade to the latest 7.n release.
-
 [discrete]
 === Required permissions
 

diff --git a/docs/setup/upgrade.asciidoc b/docs/setup/upgrade.asciidoc
@@ -23,7 +23,7 @@ ifeval::[ "{version}" != "{minor-version}.0" ]
 |Upgrade to {version}
 endif::[]
 
-|7.0–7.13
+|7.0–7.16
 |Upgrade to {version}
 
 |6.8
@@ -49,10 +49,9 @@ a|
 . Upgrade to {version}
 |====
 
-[WARNING]
-====
-The upgrade path from 6.8 to 7.0 is *not* supported.
-====
+// tag::7.0-upgrade-warning[]
+WARNING: Upgrading from 6.8 to 7.0 is *not* supported. Upgrade directly to {version} instead.
+// end::7.0-upgrade-warning[]
 
 [float]
 [[upgrade-before-you-begin]]
@@ -73,55 +72,59 @@ Before you upgrade {kib}:
   the same Elasticseach index is unsupported. Upgrading while older {kib}
   instances are running can cause data loss or upgrade failures.
 
-To identify the changes you need to make to upgrade, and to enable you to
-perform an Elasticsearch rolling upgrade with no downtime, you must upgrade to
-6.7 before you upgrade to 7.0.
-
 For a comprehensive overview of the upgrade process, refer to
 *{stack-ref}/upgrading-elastic-stack.html[Upgrading the Elastic Stack]*.
 
 
 [float]
 [[upgrade-5x-earlier]]
-=== Upgrade from 5.x or earlier
-{es} can read indices created in the previous major version. Before you upgrade
-to 7.0.0, you must reindex or delete any indices created in 5.x or earlier.
-For more information, refer to
+=== Upgrade from 5.6 or earlier
+To identify the changes you need to make to upgrade, and to enable you to
+perform an Elasticsearch rolling upgrade with no downtime, you must upgrade to
+6.8 before you upgrade to {version}.
+
+{es} {version} can't read indices created in 5.6 or earlier versions. Before you
+upgrade from 6.8 to {version}, you must reindex or delete these indices. For more information, refer to
 {stack-ref}/upgrading-elastic-stack.html#oss-stack-upgrade[Upgrading the Elastic Stack].
 
 When your reindex is complete, follow the <<upgrade-standard, Standard upgrade>>
 instructions.
 
 [float]
 [[upgrade-6x]]
-=== Upgrade from 6.x
+=== Upgrade from 6.7 or earlier
 
-The recommended path is to upgrade to 6.8 before upgrading to 7.0. This makes it
-easier to identify the required changes, and enables you to use the Upgrade
-Assistant to prepare for your upgrade to 7.0.
+The recommended path is to upgrade to 6.8 before upgrading to {version}. This
+makes it easier to identify the required changes and enables you to use the
+Upgrade Assistant to prepare for your upgrade.
 
-TIP: The ability to import {kib} 6.x saved searches, visualizations, and
-dashboards is supported.
+include::upgrade.asciidoc[tag=7.0-upgrade-warning]
+
+You can import {kib} 6.x saved searches, visualizations, and
+dashboards in {version}.
 
 [float]
 [[upgrade-67]]
 === Upgrade from 6.8
-To help you prepare for your upgrade to 7.0, 6.8 includes an https://www.elastic.co/guide/en/kibana/6.8/upgrade-assistant.html[Upgrade Assistant]
-To access the assistant, go to *Management > 7.0 Upgrade Assistant*.
+To help you prepare for your upgrade to {version}, 6.8 includes an
+https://www.elastic.co/guide/en/kibana/6.8/upgrade-assistant.html[Upgrade
+Assistant]. To access the assistant, go to *Management > 7.0 Upgrade Assistant*.
+
+include::upgrade.asciidoc[tag=7.0-upgrade-warning]
 
 After you have addressed any issues that were identified by the Upgrade
-Assistant, <<upgrade-standard,upgrade to 7.0>>.
+Assistant, <<upgrade-standard,upgrade to {version}>>.
 
 [float]
 === Known issues
 
 [float]
 ==== "shard failed" error when viewing {beats} dashboards in {kib}
-After upgrading to {es} 7.0, any indices created by {beats} 6.6 or older will not
+After upgrading to {es} {version}, any indices created by {beats} 6.6 or older will not
 work in {kib} dashboards until the `index.query.default_field` setting is added
 to each index. Indices created in {beats} 6.7 or later are unaffected.
 To add the setting to the index, you can use the 7.0
-{kibana-ref}/upgrade-assistant.html[Upgrade Assistant], or
+{kibana-ref-all}/6.8/upgrade-assistant.html[Upgrade Assistant] before upgrading, or
 //{beats-ref}/upgrading.html#dashboard-shard-failed[
 add the setting manually
 //]

diff --git a/docs/setup/upgrade/upgrade-migrations.asciidoc b/docs/setup/upgrade/upgrade-migrations.asciidoc
@@ -135,13 +135,13 @@ For {kib} versions prior to 7.5.1, if the task manager index is set to `.tasks`
 
 If {kib} terminates unexpectedly while migrating a saved object index it will automatically attempt to perform the migration again once the process has restarted. Do not delete any saved objects indices to attempt to fix a failed migration. Unlike previous versions, {kib} version 7.12.0 and later does not require deleting any indices to release a failed migration lock.
 
-If upgrade migrations fail repeatedly, follow the advice in (preventing migration failures)[preventing-migration-failures]. Once the root cause for the migration failure has been addressed, {kib} will automatically retry the migration without any further intervention. If you're unable to resolve a failed migration following these steps, please contact support.
+If upgrade migrations fail repeatedly, follow the advice in <<preventing-migration-failures,preventing migration failures>>. Once the root cause for the migration failure has been addressed, {kib} will automatically retry the migration without any further intervention. If you're unable to resolve a failed migration following these steps, please contact support.
 
 [float]
 [[upgrade-migrations-rolling-back]]
 ==== Rolling back to a previous version of {kib}
 
-If you've followed the advice in (preventing migration failures)[preventing-migration-failures] and (resolving migration failures)[resolve-migrations-failures] and {kib} is still not able to upgrade successfully, you might choose to rollback {kib} until you're able to identify and fix the root cause.
+If you've followed the advice in <<preventing-migration-failures,preventing migration failures>> and <<resolve-migrations-failures,resolving migration failures>> and {kib} is still not able to upgrade successfully, you might choose to rollback {kib} until you're able to identify and fix the root cause.
 
 WARNING: Before rolling back {kib}, ensure that the version you wish to rollback to is compatible with your {es} cluster. If the version you're rolling back to is not compatible, you will have to also rollback {es}. +
 Any changes made after an upgrade will be lost when rolling back to a previous version.