Upgrading Logstash to 6.0

edit

Before upgrading Logstash, remember to read the breaking changes.

If you are installing Logstash with other components in the Elastic Stack, also see the Elastic Stack installation and upgrade documentation.

Handling Document Types in Elasticsearch 6.0+

edit

As of Elasticsearch 6.0, document types are on the way out, and only a single mapping type per index is supported. For Logstash users this means transitioning to using the type field inside of the document instead of the document type. The effect is the same, but the usage is slightly different. This may mean reconfiguring existing Kibana dashboards to use the new type field instead of the document type.

If you are using the default mapping templates in Logstash, you will need to upgrade your mapping templates. To do this, after migrating Elasticsearch to 6.0, you must override the existing template with the 6.x template. This can be done by ensuring that all configured Elasticsearch outputs have the following setting specified: template_overwrite => true.

When to Upgrade

edit

Fresh installations can and should start with the same version across the Elastic Stack.

Elasticsearch 6.0 does not require Logstash 6.0. An Elasticsearch 6.0 cluster will happily receive data from a Logstash 5.x instance via the default HTTP communication layer. This provides some flexibility to decide when to upgrade Logstash relative to an Elasticsearch upgrade. It may or may not be convenient for you to upgrade them together, and it is not required to be done at the same time as long as Elasticsearch is upgraded first.

You should upgrade in a timely manner to get the performance improvements that come with Logstash 6.0, but do so in the way that makes the most sense for your environment.

When Not to Upgrade

edit

If any Logstash plugin that you require is not compatible with Logstash 6.0, then you should wait until it is ready before upgrading.

Although we make great efforts to ensure compatibility, Logstash 6.0 is not completely backwards compatible. As noted in the Elastic Stack upgrade guide, Logstash 6.0 should not be upgraded before Elasticsearch 6.0. This is both practical and because some Logstash 6.0 plugins may attempt to use features of Elasticsearch 6.0 that did not exist in earlier versions.