Upgrading Kibana

Important

Before upgrading Kibana:

  • Consult the breaking changes docs.
  • Test upgrades in a dev environment before upgrading your production servers.
  • Backup your data using the Elasticsearch 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:

Upgrade From Upgrade To Supported Upgrade Type

3.x

5.x

New installation

4.0 or 4.1

5.x

Standard upgrade & reindex

4.x >= 4.2

5.x

Standard upgrade

5.0.0 pre GA

5.x

Standard upgrade & reindex

5.x

5.y

Standard upgrade (where y > x)

Important

Reindex is required if you ever upgraded from Kibana 4.1 or 4.0

Even if you’re running Kibana version 4.2 or higher, if you have previously upgraded from Kibana 4.0 or 4.1, you will need to do a Standard upgrade & reindex when upgrading to 5.x.

This is due to the Elasticsearch requirement that any index that was initially created before Elasticsearch 2.0 must be reindexed even if it’s currently working in Elasticsearch 2.x.

You only need to do this once when moving to 5.x.

Note

Saved searches, visualizations, and dashboards created in Kibana 4.x are generally compatible with 5.x.

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.

If you haven’t already, consult this 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 Elasticsearch Query DSL, make sure to check the Elasticsearch breaking changes documentation and take the necessary remediation steps as per those instructions.

Upgrading using a deb or rpm package

  1. Stop the existing Kibana process using the appropriate command for your system.
  2. 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 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 documentation otherwise Kibana will fail to start.

  3. Upgrade any plugins by removing the existing plugin and reinstalling the appropriate version using the kibana-plugin script. Check out the plugins documentation for more information.
  4. Start the new Kibana process using the appropriate command for your system.

Upgrading using a zip or tar.gz archive

  1. Extract the zip or tar.gz archive to a new directory to be sure that you don’t overwrite the config or data directories.
  2. 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 documentation otherwise Kibana will fail to start.
  3. Copy the files from the data directory from your old installation to your new installation.
  4. Install the appropriate versions of all your plugins for your new installation using the kibana-plugin script. Check out the plugins documentation for more information.
  5. Stop the old Kibana process.
  6. Start the new Kibana process.

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 Reindex to upgrade guide.

Note

The Elasticsearch Migration Plugin creates a versioned .kibana index as well as an 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 Standard Upgrade instructions.

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 installation instructions to install Kibana from scratch, and then manually recreate your searches, visualizations, and dashboards.