Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[8.1] Improve docs for unknown saved object types (#125253) #125310

Merged
merged 1 commit into from
Feb 10, 2022
Merged

[8.1] Improve docs for unknown saved object types (#125253) #125310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions docs/setup/upgrade/upgrade-migrations.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

Each time you upgrade {kib}, an upgrade migration is performed to ensure that all <<managing-saved-objects,saved objects>> 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}.

Expand All @@ -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)
Expand All @@ -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.
Expand Down Expand Up @@ -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:
Expand Down
10 changes: 2 additions & 8 deletions docs/setup/upgrade/upgrade-standard.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]
===========================================
Expand All @@ -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 <<breaking-changes,breaking changes>> documentation
Expand Down