diff --git a/docs/setup/upgrade/upgrade-migrations.asciidoc b/docs/setup/upgrade/upgrade-migrations.asciidoc index 059ae47d2e476a..f75251089bf558 100644 --- a/docs/setup/upgrade/upgrade-migrations.asciidoc +++ b/docs/setup/upgrade/upgrade-migrations.asciidoc @@ -4,8 +4,8 @@ Each time you upgrade {kib}, an upgrade migration is performed to ensure that all <> are compatible with the new version. -NOTE: To help you prepare for the upgrade to 7.0.0, 6.7.0 includes an https://www.elastic.co/guide/en/kibana/6.7/upgrade-assistant.html[*Upgrade Assistant*]. -To access the assistant, go to *Management > 7.0 Upgrade Assistant*. +NOTE: To help you prepare for the upgrade to 8.0.0, 7.17.0 includes an https://www.elastic.co/guide/en/kibana/7.17/upgrade-assistant.html[*Upgrade Assistant*]. +To access the assistant, go to *Stack Management > Upgrade Assistant*. WARNING: {kib} 7.12.0 and later uses a new migration process and index naming scheme. Before you upgrade, read the documentation for your version of {kib}. @@ -32,7 +32,6 @@ adds a write block to the outdated index. Table 1 lists the saved objects indice [options="header"] |======================= |Upgrading from version | Outdated index (alias) -| 6.0.0 through 6.4.x | `.kibana` `.kibana_task_manager_7.12.0_001` (`.kibana_task_manager` alias) | 6.5.0 through 7.3.x | `.kibana_N` (`.kibana` alias) @@ -58,6 +57,28 @@ complete the upgrade migration before bringing up the remaining instances. ==== Preventing migration failures Review the common causes of {kib} upgrade failures and how to prevent them. +[float] +====== Documents found for unknown saved object types +Migrations will fail if saved objects belong to an unknown +saved object type. Unknown saved objects are typically caused by +to the {es} index, or by disabling a plugin that had previously +created a saved object. + +We recommend using the https://www.elastic.co/guide/en/kibana/7.17/upgrade-assistant.html[Upgrade Assistant] +to discover and remedy any unknown saved object types. {kib} version 7.17.0 deployments containing unknown saved +object types will also log the following warning message: + +[source,sh] +-------------------------------------------- +CHECK_UNKNOWN_DOCUMENTS Upgrades will fail for 8.0+ because documents were found for unknown saved object types. To ensure that upgrades will succeed in the future, either re-enable plugins or delete these documents from the ".kibana_7.17.0_001" index after the current upgrade completes. +-------------------------------------------- + +If you fail to remedy this, your upgrade to 8.0+ will fail with a message like: +[source,sh] +-------------------------------------------- +Unable to complete saved object migrations for the [.kibana] index: Migration failed because documents were found for unknown saved object types. To proceed with the migration, please delete these documents from the ".kibana_7.17.0_001" index. +-------------------------------------------- + [float] ===== timeout_exception or receive_timeout_transport_exception There is a known issue in 7.12.0 for users who tried the {fleet} beta. @@ -122,9 +143,6 @@ Matching index templates that specify `settings.refresh_interval` or `mappings` To make sure the index templates won't apply to new `.kibana*` indices, narrow down the {data-sources} of any user-defined index templates. -NOTE: In {kib} 6.5.0 and earlier, {kib} creates a `kibana_index_template:.kibana` index template -and uses a `.kibana` index pattern. You do not need to change or remove the index template. - [float] ===== An unhealthy {es} cluster Problems with your {es} cluster can prevent {kib} upgrades from succeeding. Ensure that your cluster has: diff --git a/docs/setup/upgrade/upgrade-standard.asciidoc b/docs/setup/upgrade/upgrade-standard.asciidoc index b01759b4f3511d..6854ead7531a8b 100644 --- a/docs/setup/upgrade/upgrade-standard.asciidoc +++ b/docs/setup/upgrade/upgrade-standard.asciidoc @@ -1,8 +1,8 @@ [[upgrade-standard]] === Standard upgrade -NOTE: 6.7 includes an https://www.elastic.co/guide/en/kibana/6.7/upgrade-assistant.html[Upgrade Assistant] -to help you prepare for your upgrade to 7.0. To access the assistant, go to *Management > 7.0 Upgrade Assistant*. +NOTE: 7.17 includes an https://www.elastic.co/guide/en/kibana/7.17/upgrade-assistant.html[Upgrade Assistant] +to help you prepare for your upgrade to 8.0. To access the assistant, go to *Stack Management > Upgrade Assistant*. [IMPORTANT] =========================================== @@ -29,12 +29,6 @@ Different versions of {kib} running against the same {es} index, such as during . Use `rpm` or `dpkg` to install the new package. All files should be placed in their proper locations and config files should not be overwritten. + -[NOTE] --- -{kib} 4.x used a different config location than 5.0+, so if you're upgrading -from 4.x, you will need to copy the configurations from your old config -(`/opt/kibana/config/kibana.yml`) to your new config -(`/etc/kibana/kibana.yml`). Make sure you remove or update any configurations that are indicated in the <> documentation