57 lines
3.6 KiB
Plaintext
57 lines
3.6 KiB
Plaintext
[[upgrade-migrations]]
|
|
=== Troubleshooting saved object migrations
|
|
|
|
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 {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 {kib} version 6.5+, {kib} will migrate into `.kibana_1` and set `.kibana` up as an index alias.
|
|
|
|
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 {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 {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 {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 {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 {kib} instances
|
|
|
|
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 {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. You must restart {kib} to re-trigger the migration.
|
|
|
|
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.
|
|
|
|
|