[DOCS] Updates 7.0 upgrade guide (#34121)
This commit is contained in:
Sarah Hersh
Sarah Hersh
parent
5cad03f445
commit
ae2c72bbcc
|
|
@ -1,3 +1,4 @@
|
|||
[role="xpack"]
|
||||
[[upgrade-assistant]]
|
||||
== Upgrade Assistant
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
Depending on which version of {kib} you're upgrading from, the upgrade process to 7.0
|
||||
will vary.
|
||||
|
||||
[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>>
|
||||
|=======================================================================
|
||||
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
|
||||
|
||||
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).
|
||||
|
||||
*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>>.
|
||||
|
||||
NOTE: Saved searches, visualizations, and dashboards created in Kibana 4.x or 5.x
|
||||
can be generally imported into 6.x.
|
||||
|
||||
include::upgrade/upgrade-standard.asciidoc[]
|
||||
|
||||
include::upgrade/upgrade-standard-reindex.asciidoc[]
|
||||
|
||||
include::upgrade/upgrade-new-install.asciidoc[]
|
||||
|
||||
include::upgrade/upgrade-migrations.asciidoc[]
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
[[upgrade-new-install]]
|
||||
=== New Installation
|
||||
|
||||
Kibana 4.0 introduced a major architectural overhaul. As a result, the
|
||||
underlying `.kibana` schema changed so significantly that upgrading from Kibana
|
||||
3.x requires recreating all visualizations, dashboards, etc.
|
||||
|
||||
If you're upgrading from 3.x, please follow the
|
||||
<<install,installation instructions>> to install Kibana from scratch, and then
|
||||
manually recreate your searches, visualizations, and dashboards.
|
||||
|
|
@ -1,25 +0,0 @@
|
|||
[[upgrade-standard-reindex]]
|
||||
=== Standard Upgrade with Reindex
|
||||
|
||||
You must perform a reindex in Elasticsearch whenever you're upgrading Kibana
|
||||
that has an existing `.kibana` index created prior to Elasticsearch 2.0.
|
||||
|
||||
This is the case if you're upgrading directly from Kibana 4.1 or 4.0 as well as
|
||||
when your existing install of Kibana 4.2+ was previously upgraded from 4.1 or
|
||||
4.0.
|
||||
|
||||
Reindexing is the process of creating a new index with updated syntax and
|
||||
mappings directly from an existing index. While it is possible to do this
|
||||
manually, we recommend using the Elasticsearch Migration Plugin as described
|
||||
in the Elasticsearch
|
||||
{ref}/reindex-upgrade.html#reindex-upgrade[Reindex to upgrade] guide.
|
||||
|
||||
NOTE: The Elasticsearch Migration Plugin creates a versioned `.kibana` index
|
||||
as well as an {ref}/indices-aliases.html[index alias] that points to it.
|
||||
Kibana 5.0 supports this index alias, but if you want to run Kibana 4.x while
|
||||
this Elastic stack upgrade is underway, you'll need to configure your Kibana
|
||||
4.x install to point to the versioned index using the `kibana.index`
|
||||
configuration in your `kibana.yml` file.
|
||||
|
||||
Once your reindex is complete, you can follow the
|
||||
<<upgrade-standard, Standard Upgrade>> instructions.
|
||||
|
|
@ -1,40 +1,40 @@
|
|||
[[upgrade-standard]]
|
||||
=== Standard Upgrade
|
||||
=== Standard upgrade
|
||||
|
||||
A standard upgrade is the most straightforward way to upgrade Kibana, and it's
|
||||
possible when you're upgrading from Kibana version 4.2 or higher.
|
||||
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*.
|
||||
|
||||
If you haven't already, consult this <<upgrade,table>> to verify that standard
|
||||
upgrade is supported for your version of Kibana.
|
||||
|
||||
NOTE: If you've saved and/or exported objects in Kibana that rely on the
|
||||
<<search,Elasticsearch Query DSL>>, make sure to check the Elasticsearch
|
||||
[IMPORTANT]
|
||||
===========================================
|
||||
If you've saved and/or exported objects in {kib} that rely on the
|
||||
<<search,Elasticsearch Query DSL>>, make sure to check the {es}
|
||||
{ref}/breaking-changes.html[breaking changes] documentation and take the
|
||||
necessary remediation steps as per those instructions.
|
||||
===========================================
|
||||
|
||||
[float]
|
||||
==== Upgrading using a `deb` or `rpm` package
|
||||
|
||||
. Stop the existing Kibana process using the appropriate command for your
|
||||
. Stop the existing {kib} process using the appropriate command for your
|
||||
system.
|
||||
. 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]
|
||||
--
|
||||
Kibana 4.x used a different config location than 5.0+, so if you're upgrading
|
||||
{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
|
||||
otherwise Kibana will fail to start.
|
||||
otherwise {kib} will fail to start.
|
||||
--
|
||||
. Upgrade any plugins by removing the existing plugin and reinstalling the
|
||||
appropriate version using the `kibana-plugin` script. Check out the
|
||||
<<kibana-plugins,plugins>> documentation for more information.
|
||||
. Start the new Kibana process using the appropriate command for your system.
|
||||
. Start the new {kib} process using the appropriate command for your system.
|
||||
|
||||
[float]
|
||||
==== Upgrading using a `zip` or `tar.gz` archive
|
||||
|
|
@ -43,7 +43,7 @@ otherwise Kibana will fail to start.
|
|||
don't overwrite the `config` or `data` directories. +
|
||||
+
|
||||
--
|
||||
IMPORTANT: If you use {monitoring}, you must re-use the data directory when you
|
||||
IMPORTANT: If you use {monitor-features}, you must re-use the data directory when you
|
||||
upgrade {kib}. Otherwise, the {kib} instance is assigned a new persistent UUID
|
||||
and becomes a new instance in the monitoring data.
|
||||
|
||||
|
|
@ -51,11 +51,11 @@ and becomes a new instance in the monitoring data.
|
|||
. Copy the files from the `config` directory from your old installation to your
|
||||
new installation. Make sure you remove or update any configurations that are
|
||||
indicated in the <<breaking-changes,breaking changes>> documentation
|
||||
otherwise Kibana will fail to start.
|
||||
otherwise {kib} will fail to start.
|
||||
. Copy the files from the `data` directory from your old installation to your
|
||||
new installation.
|
||||
. Install the appropriate versions of all your plugins for your new
|
||||
installation using the `kibana-plugin` script. Check out the
|
||||
<<kibana-plugins,plugins>> documentation for more information.
|
||||
. Stop the old Kibana process.
|
||||
. Start the new Kibana process.
|
||||
. Stop the old {kib} process.
|
||||
. Start the new {kib} process.
|
||||
|
|
|
|||
Loading…
Reference in a new issue