diff --git a/docs/developer/architecture/core/logging-configuration-migration.asciidoc b/docs/developer/architecture/core/logging-configuration-migration.asciidoc index 4a9d03d3b5312..aefb81b37d4b6 100644 --- a/docs/developer/architecture/core/logging-configuration-migration.asciidoc +++ b/docs/developer/architecture/core/logging-configuration-migration.asciidoc @@ -1,6 +1,5 @@ -[discrete] [[logging-config-changes]] -=== Logging configuration changes +== Logging configuration changes WARNING: {kib} 8.0.0 and later uses a new logging system. Before you upgrade, read the documentation for your {kib} version. @@ -43,4 +42,3 @@ WARNING: {kib} 8.0.0 and later uses a new logging system. Before you upgrade, re | error | `{ message, name, stack }` | `{ message, name, stack, code, signal }` |=== - diff --git a/docs/setup/upgrade.asciidoc b/docs/setup/upgrade.asciidoc index 3069d78cc692e..db9d302709092 100644 --- a/docs/setup/upgrade.asciidoc +++ b/docs/setup/upgrade.asciidoc @@ -42,7 +42,7 @@ complete the upgrade migration before bringing up the remaining instances. [[preventing-migration-failures]] === Preparing for migration -There are extra steps you can follow to ensure you are ready for migration. +Take these extra steps to ensure you are ready for migration. [float] ==== Ensure your {es} cluster is healthy diff --git a/docs/setup/upgrade/resolving-migration-failures.asciidoc b/docs/setup/upgrade/resolving-migration-failures.asciidoc index 454dfe948fe4e..5b590c359cc69 100644 --- a/docs/setup/upgrade/resolving-migration-failures.asciidoc +++ b/docs/setup/upgrade/resolving-migration-failures.asciidoc @@ -5,7 +5,7 @@ Migrating {kib} primarily involves migrating saved object documents to be compat with the new version. [float] -==== Resolve saved object migration failures +==== Saved object migration failures If {kib} unexpectedly terminates while migrating a saved object index, {kib} automatically attempts to perform the migration again when the process restarts. Do not delete any saved objects indices to @@ -21,14 +21,14 @@ If you're unable to resolve a failed migration, contact Support. [float] [[upgrade-migrations-old-indices]] -==== Handle old `.kibana_N` indices +==== Old `.kibana_N` indices After the migrations complete, multiple {kib} indices are created in {es}: (`.kibana_1`, `.kibana_2`, `.kibana_7.12.0` etc). {kib} only uses the index that the `.kibana` and `.kibana_task_manager` aliases point to. The other {kib} indices can be safely deleted, but are left around as a matter of historical record, and to facilitate rolling {kib} back to a previous version. [float] -==== Handle known issues with {fleet} beta +==== Known issues with {fleet} beta If you see a`timeout_exception` or `receive_timeout_transport_exception` error, it might be from a known known issue in 7.12.0 if you tried the {fleet} beta. Upgrade migrations fail because of a large number of documents in the `.kibana` index, @@ -45,7 +45,7 @@ For instructions on how to mitigate the known issue, refer to https://github.com [float] -==== Handle corrupt saved objects +==== Corrupt saved objects To find and remedy problems caused by corrupt documents, we highly recommend testing your {kib} upgrade in a development cluster, especially when there are custom integrations that create saved objects in your environment. @@ -87,13 +87,13 @@ The dashboard with the `e3c5fc71-ac71-4805-bcab-2bcc9cc93275` ID that belongs to [float] [[unknown-saved-object-types]] -==== Handle documents for unknown saved objects +==== Documents for unknown saved objects 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 {kibana-ref-all}/7.17/upgrade-assistant.html[Upgrade Assistant] +We recommend using the {kibana-ref-all}/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: @@ -110,7 +110,7 @@ Unable to complete saved object migrations for the [.kibana] index: Migration fa -------------------------------------------- [float] -==== Handle incompatible settings or mappings +==== Incompatible settings or mappings Matching index templates that specify `settings.refresh_interval` or `mappings` are known to interfere with {kib} upgrades. This can happen when index templates are defined manually. @@ -118,7 +118,7 @@ This can happen when index templates are defined manually. To make sure the index templates won't apply to new `.kibana*` indices, narrow down the {data-sources} of any user-defined index templates. [float] -==== Handle incompatible `xpack.tasks.index` configuration setting +==== Incompatible `xpack.tasks.index` configuration setting In {kib} 7.5.0 and earlier, when the task manager index is set to `.tasks` with the configuration setting `xpack.tasks.index: ".tasks"`, upgrade migrations fail. In {kib} 7.5.1 and later, the incompatible configuration diff --git a/docs/setup/upgrade/rollback-migration.asciidoc b/docs/setup/upgrade/rollback-migration.asciidoc index 1b87d0f335b8c..c0cb126b37825 100644 --- a/docs/setup/upgrade/rollback-migration.asciidoc +++ b/docs/setup/upgrade/rollback-migration.asciidoc @@ -18,7 +18,13 @@ To roll back after a failed upgrade migration, you must also rollback the saved . Before proceeding, {ref}/snapshots-take-snapshot.html[take a snapshot] that contains the `kibana` feature state. By default, snapshots include the `kibana` feature state. . To make sure no {kib} instances are performing an upgrade migration, shut down all {kib} instances. -. To delete all saved object indices, use `DELETE /.kibana*`. +. To delete all saved object indices, enter: ++ +[source,sh] +-------------------------------------------- +DELETE /.kibana* +-------------------------------------------- + . {ref}/snapshots-restore-snapshot.html[Restore] the `kibana` feature state from the snapshot. . Start all {kib} instances on the older version you want to rollback to. @@ -30,12 +36,29 @@ To roll back after a failed upgrade migration, you must also rollback the saved . Delete the version-specific indices created by the failed upgrade migration. + For example, to rollback from a failed upgrade -to v7.12.0, use `DELETE /.kibana_7.12.0_*,.kibana_task_manager_7.12.0_*`. +to v7.12.0, enter: ++ +[source,sh] +-------------------------------------------- +DELETE /.kibana_7.12.0_*,.kibana_task_manager_7.12.0_* +-------------------------------------------- + . Inspect the output of `GET /_cat/aliases`. + If the `.kibana` or `.kibana_task_manager` aliases are missing, you must create them manually. Find the latest index from the output of `GET /_cat/indices` and create the missing alias to point to the latest index. -For example, if the `.kibana` alias is missing, and the latest index is `.kibana_3`, create a new alias using `POST /.kibana_3/_aliases/.kibana`. -. To remove the write block from the roll back indices, use -`PUT /.kibana,.kibana_task_manager/_settings {"index.blocks.write": false}` -. Start {kib} on the older version you want to rollback to. +For example, if the `.kibana` alias is missing, and the latest index is `.kibana_3`, create a new alias using: ++ +[source,sh] +-------------------------------------------- +POST /.kibana_3/_aliases/.kibana +-------------------------------------------- + +. To remove the write block from the roll back indices, enter: ++ +[source,sh] +-------------------------------------------- +PPUT /.kibana,.kibana_task_manager/_settings {"index.blocks.write": false} +-------------------------------------------- + +. Start {kib} on the older version you want to roll back to. diff --git a/docs/setup/upgrade/saved-objects-migration.asciidoc b/docs/setup/upgrade/saved-objects-migration.asciidoc index cc4406f8cdd1f..5d84ece1c3c9f 100644 --- a/docs/setup/upgrade/saved-objects-migration.asciidoc +++ b/docs/setup/upgrade/saved-objects-migration.asciidoc @@ -25,7 +25,9 @@ the most up-to-date saved object indices. When you start a new {kib} installation, an upgrade migration is performed before starting plugins or serving HTTP traffic. Before you upgrade, shut down old nodes to prevent losing acknowledged writes. To reduce the likelihood of old nodes losing acknowledged writes, {kib} 7.12.0 and later -adds a write block to the outdated index. Table 1 lists the saved objects indices used by previous {kib} versions. +adds a write block to the outdated index. + +The following tables lists the saved objects indices used by previous {kib} versions. .Saved object indices and aliases per {kib} version [options="header"]