Upgrade from 5.x to 6.x

edit

Before upgrading your Beats, please review the breaking changes doc.

We recommend that you fully upgrade Elasticsearch and Kibana to version 6.0 before upgrading Beats. If you are on a Beats 5.x version lower than 5.6, please follow the Upgrade to 5.6 section before doing the Elasticsearch upgrade.

If you’re not ready to upgrade Elasticsearch and Kibana to 6.0, that’s alright. Beats version 6.0 works with Elasticsearch and Kibana version 5.6, so you can upgrade Beats now and the rest of the stack later.

Upgrade to 5.6

edit

The upgrade procedure assumes that you have Beats version 5.6 installed. If you are on a previous 5.x version of Beats, please upgrade to version 5.6 first. The reason is that the Elasticsearch mapping template in 5.6 was modified to be compatible with Elasticsearch 6.0 (by removing the _all settings).

For this reason, after upgrading to 5.6, you need to make sure that the 5.6 template is loaded. You can do this by temporarily enabling the output.elasticsearch.template.overwrite setting, for example with Metricbeat:

metricbeat -e -E output.elasticsearch.template.overwrite=true

Alternatively, you can manually force loading the template:

curl -XPUT -H'Content-Type: application/json'  http://localhost:9200/_template/metricbeat -d @metricbeat.template.json

To check which version of the template is loaded, open Kibana Console, call GET /_template/metricbeat, and look for the version string. Note that you need to do this for each Beat type that you are running (e.g. Filebeat, Metricbeat, Packetbeat).

Migrate configuration files

edit

Beats 6.0 comes with several backwards incompatible configuration changes. Please review the Breaking changes in 6.0 document. Where possible, we kept the old configuration options working, but deprecated them. However, deprecation was not always possible, so if you use any of the settings mentioned in the Breaking Changes section of the release notes, make sure you understand the alternatives that we provide.

modules.d configuration layout

edit

Starting with the 6.0 version, Filebeat and Metricbeat are moving to a directory layout for configuration, where each module is configured in its own configuration file.

While the all-in-one configuration is still fully supported, we recommend moving to the new layout at upgrade time. This typically means starting off with the new default configuration and modifying it with the custom settings that you had in your old files.

New command test config command

edit

Beats 6.0 introduces a new test command for testing the configuration file. For example:

metricbeat test config

The old -configtest flag is still available, but deprecated.

Reference configuration files

edit

The <beatname>.full.yml file, which contains all the non-deprecated configuration options is renamed to <beatname>.reference.yml starting with Beats 6.0. We recommend using this file as a reference only. It’s not intended to be used in production.

Dashboard upgrades

edit

We recommend re-importing the Kibana dashboards after the Beats and Kibana upgrades are complete. This way, you will take advantage of the new Beats dashboards created for the 6.0 release.

See Changes for importing the Kibana dashboards in the Breaking Changes documentation.

If you’ve modified the Beats dashboards manually, reimporting them will overwrite your changes. Consider saving your dashboards under new IDs, so that the reimport doesn’t overwrite them.

Heartbeat package names

edit

The DEB and RPM packages for Heartbeat are now named heartbeat-elastic to avoid conflicts with a different heartbeat project. The .deb and .rpm file names haven’t changed, just the package name in the repositories.