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

Improve docs for unknown saved object types #125253

Merged
merged 9 commits into from
Feb 10, 2022
Merged

Improve docs for unknown saved object types #125253

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
f30f768
Revert "Revert "Docs for preventing migrations failing for unknown sa…
rudolf Feb 10, 2022
63bb500
Fix links and versions for note to use UA
rudolf Feb 10, 2022
9935388
Migration docs: remove content related to 6.x versions
rudolf Feb 10, 2022
7568d4b
Upgrade docs, remove content for upgrading from v4/v5
rudolf Feb 10, 2022
4306e7f
Merge branch 'main' into unknown-so-types-docs
rudolf Feb 10, 2022
8ae5cdb
Link to 7.17 upgrade assistant
rudolf Feb 10, 2022
03c762c
Merge branch 'unknown-so-types-docs' of https://github.com/rudolf/kib…
rudolf Feb 10, 2022
0b1fe7e
Apply suggestions from code review
rudolf Feb 10, 2022
24e2fc9
Update docs/setup/upgrade/upgrade-migrations.asciidoc
rudolf Feb 10, 2022
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
31 changes: 25 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*].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this note needed? Given the edits, it says the same thing as the first paragraph of the file. Instead, you could put the link to Upgrade Assistant in the first paragraph.

To access the assistant, go to *Management > Upgrade Assistant*.
rudolf marked this conversation as resolved.
Show resolved Hide resolved

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,29 @@ 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 were found for unknown saved object types
rudolf marked this conversation as resolved.
Show resolved Hide resolved
Migrations will fail if saved objects were found which belong to an unknown
rudolf marked this conversation as resolved.
Show resolved Hide resolved
saved object type. This could be caused by writing malformed documents directly
rudolf marked this conversation as resolved.
Show resolved Hide resolved
to the Elasticsearch index, or by disabling a plugin that had previously
rudolf marked this conversation as resolved.
Show resolved Hide resolved
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. In addition to the
upgrade assistant, {kib} version 7.17.0 deployments containing unknown saved
rudolf marked this conversation as resolved.
Show resolved Hide resolved
rudolf marked this conversation as resolved.
Show resolved Hide resolved
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 +144,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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This content is no long in the doc.

You might also want to look at Upgrade Kibana in the Installation and Upgrade Guide. This doc contains a note about saved object migrations.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed offline there's a discrepancy in our docs between 7.x and 8.x and the structure isn't optimal for 8.x but I will address that in a follow-up

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rudolf @gchaps and I restructured the docs in #125288.


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-8.0.0,breaking changes>> documentation
Expand Down