-
Notifications
You must be signed in to change notification settings - Fork 8.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[DOCS] Updates 7.0 upgrade guide (#34121)
- Loading branch information
Showing
6 changed files
with
79 additions
and
92 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
[role="xpack"] | ||
[[upgrade-assistant]] | ||
== Upgrade Assistant | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,45 +1,61 @@ | ||
[[upgrade]] | ||
== Upgrading Kibana | ||
== Upgrading {kib} | ||
|
||
|
||
[IMPORTANT] | ||
=========================================== | ||
Before upgrading Kibana: | ||
Before upgrading {kib}: | ||
* Consult the <<breaking-changes,breaking changes>> docs. | ||
* Test upgrades in a dev environment before upgrading your production servers. | ||
* Backup your data using the Elasticsearch | ||
{ref}/modules-snapshots.html[snapshots] feature. | ||
* Backup your data using the {es} {ref}/modules-snapshots.html[snapshots] feature. | ||
You **cannot roll back** to an earlier version unless you have a backup of | ||
your data. | ||
* If you are using custom plugins, check that a compatible version is | ||
available. | ||
=========================================== | ||
|
||
Depending on which version of Kibana you're upgrading from, the upgrade process | ||
will vary. Please consult the following table to determine which process you | ||
should follow: | ||
|
||
[cols="1<m,1<m,3",options="header",] | ||
|======================================================================= | ||
|Upgrade From |Upgrade To |Supported Upgrade Type | ||
|3.x |5.x |<<upgrade-new-install,New installation>> | ||
|4.0 or 4.1 |5.x |<<upgrade-standard-reindex,Standard upgrade & reindex>> | ||
|4.x >= 4.2 |5.x |<<upgrade-standard,Standard upgrade>> | ||
|5.0.0 pre GA |5.x |<<upgrade-standard-reindex,Standard upgrade & reindex>> | ||
|5.x |5.y |<<upgrade-standard,Standard upgrade>> (where `y > x`) | ||
|5.x |6.x |<<upgrade-standard,Standard upgrade>> | ||
// & <<migrating-6.0-index,Reindex transformation>> | ||
|6.x |6.y |<<upgrade-standard,Standard upgrade>> (where `y > x`) | ||
|6.x |7.x |<<upgrade-standard,Standard upgrade>> | ||
|======================================================================= | ||
|
||
NOTE: Saved searches, visualizations, and dashboards created in Kibana 4.x or 5.x | ||
can be generally imported into 6.x. | ||
Depending on which version of {kib} you're upgrading from, the upgrade process to 7.0 | ||
will vary. | ||
|
||
include::upgrade/upgrade-standard.asciidoc[] | ||
The recommended path is to upgrade to 6.7 before upgrading to 7.0. | ||
This makes it easier to identify the changes you need to make to upgrade and enables | ||
you to perform a rolling upgrade with no downtime. | ||
|
||
Please see | ||
*{stack-ref}/upgrading-elastic-stack.html[Upgrading the Elastic Stack]* for a | ||
comprehensive overview of the upgrade process. | ||
|
||
[float] | ||
==== Upgrading from 5.x or earlier | ||
{es} can read indices created in the previous major version. If you have indices | ||
created in 5.x or before, you must reindex or delete them before upgrading to 7.0.0. | ||
See {stack-ref}/upgrading-elastic-stack.html#oss-stack-upgrade[Upgrading the Elastic Stack] | ||
for more information. | ||
|
||
Once your reindex is complete, you can follow the <<upgrade-standard, Standard upgrade>> | ||
instructions. | ||
|
||
[float] | ||
==== Upgrading from 6.x | ||
|
||
include::upgrade/upgrade-standard-reindex.asciidoc[] | ||
The recommended path is to upgrade to 6.7 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 (see below). | ||
|
||
include::upgrade/upgrade-new-install.asciidoc[] | ||
*Note:* Saved searches, visualizations, and dashboards created in {kib} 6.x | ||
can be generally imported into 7.x. | ||
|
||
[float] | ||
==== Upgrading from 6.7 | ||
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*. | ||
|
||
After you have addressed any issues that were identified by the Upgrade Assistant, | ||
<<upgrade-standard,upgrade to 7.0>>. | ||
|
||
|
||
include::upgrade/upgrade-standard.asciidoc[] | ||
|
||
include::upgrade/upgrade-migrations.asciidoc[] | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,48 +1,53 @@ | ||
[[upgrade-migrations]] | ||
=== Saved object migrations | ||
=== Troubleshooting saved object migrations | ||
|
||
Every time Kibana is upgraded it checks to see if all saved objects, such as dashboards, visualizations, and index patterns, are compatible with the new version. If any objects need to be updated, then the automatic saved object migration process is kicked off. | ||
Every time {kib} is upgraded it checks to see if all saved objects, such as dashboards, visualizations, and index patterns, are compatible with the new version. If any objects need to be updated, then the automatic saved object migration process is kicked off. | ||
|
||
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*. | ||
|
||
[float] | ||
[[upgrade-migrations-process]] | ||
==== How the process works | ||
|
||
Saved objects are stored in an index named `.kibana_N`, where `N` is a number that increments over time as Kibana is upgraded. The index alias `.kibana` points to the latest up-to-date index for a given install. | ||
Saved objects are stored in an index named `.kibana_N`, where `N` is a number that increments over time as {kib} is upgraded. The index alias `.kibana` points to the latest up-to-date index for a given install. | ||
|
||
NOTE: Prior to 6.5.0, saved objects were stored directly in an index named `.kibana`, so the first time you upgrade to Kibana version 6.5+, Kibana will migrate into `.kibana_1` and set `.kibana` up as an index alias. | ||
NOTE: Prior to 6.5.0, saved objects were stored directly in an index named `.kibana`, so the first time you upgrade to {kib} version 6.5+, {kib} will migrate into `.kibana_1` and set `.kibana` up as an index alias. | ||
|
||
While Kibana is starting up and before serving any HTTP traffic, it checks to see if any internal mapping changes or data transformations for existing saved objects are required. | ||
While {kib} is starting up and before serving any HTTP traffic, it checks to see if any internal mapping changes or data transformations for existing saved objects are required. | ||
|
||
When changes are necessary, a new incremental `.kibana_N` index is created with updated mappings, then the saved objects are loaded in batches from the existing index, transformed to whatever extent necessary, and added to this new index. | ||
|
||
Once the objects are migrated, the `.kibana` index alias is updated to point to the new index, and Kibana finishes starting up and serving HTTP traffic. | ||
Once the objects are migrated, the `.kibana` index alias is updated to point to the new index, and {kib} finishes starting up and serving HTTP traffic. | ||
|
||
[float] | ||
[[upgrade-migrations-old-indices]] | ||
==== Handling old `.kibana` indices | ||
|
||
After migrations have run, there will be multiple Kibana indices in Elasticsearch: (`.kibana_1`, `.kibana_2`, etc). Kibana only uses the index that the `.kibana` alias points to. The other Kibana indices can be safely deleted, but are left around as a matter of historical record, and to facilitate rolling Kibana back to a previous version. | ||
After migrations have run, there will be multiple {kib} indices in {es}: (`.kibana_1`, `.kibana_2`, etc). {kib} only uses the index that the `.kibana` alias points 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] | ||
[[upgrade-migrations-errors]] | ||
==== Handling errors during saved object migrations | ||
|
||
If Kibana terminates unexpectedly while migrating a saved object index, some additional work may be required in order to get Kibana to re-attempt the migration. | ||
If {kib} terminates unexpectedly while migrating a saved object index, some additional work may be required in order to get {kib} to re-attempt the migration. | ||
|
||
For example, if the `.kibana` alias is pointing to `.kibana_4`, and there is a `.kibana_5` index in Elasticsearch, the `.kibana_5` index will need to be deleted. Kibana will never attempt to overwrite an existing index. | ||
For example, if the `.kibana` alias is pointing to `.kibana_4`, and there is a `.kibana_5` index in {es}, the `.kibana_5` index will need to be deleted. {kib} will never attempt to overwrite an existing index. | ||
|
||
[float] | ||
[[upgrade-migrations-multiple-instances]] | ||
==== Support for multiple kibana instances | ||
==== Support for multiple {kib} instances | ||
|
||
If you're running multiple Kibana instances for a single index behind a load balancer, it's important that you stop all instances before upgrading, so you do not have multiple different versions of Kibana trying to perform saved object migrations. | ||
If you're running multiple {kib} instances for a single index behind a load balancer, it's important that you stop all instances before upgrading, so you do not have multiple different versions of {kib} trying to perform saved object migrations. | ||
|
||
The first instance that triggers saved object migrations will run the entire process. Any other instances started up while a migration is running will log a message and then wait until saved object migration has completed before they start serving HTTP traffic. | ||
|
||
[float] | ||
[[upgrade-migrations-rolling-back]] | ||
==== Rolling back to a previous version of Kibana | ||
==== Rolling back to a previous version of {kib} | ||
|
||
When rolling {kib} back to a previous version, point the `.kibana` alias to the appropriate {kib} index. When you have the previous version running again, delete the more recent `.kibana_N` index or indices so that future upgrades are based on the current {kib} index. | ||
|
||
WARNING: Rolling back to a previous {kib} version can result in saved object data loss if you had successfully upgraded and made changes to saved objects before rolling back. | ||
|
||
When rolling Kibana back to a previous version, point the `.kibana` alias to the appropriate Kibana index. When you have the previous version running again, delete the more recent `.kibana_N` index or indices so that future upgrades are based on the current Kibana index. | ||
|
||
WARNING: Rolling back to a previous Kibana version can result in saved object data loss if you had successfully upgraded and made changes to saved objects before rolling back. |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters