From f89dfb21248b02b3f26bb9a671e548fdaa706a89 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Wed, 3 Apr 2019 11:04:38 -0400 Subject: [PATCH] Refine upgrade instructions for 7.0 Add recommendation to upgrade to 6.7 before 7.0 Fixes #10634 --- docs/static/upgrading.asciidoc | 113 +++++++++++++++++++++------------ 1 file changed, 74 insertions(+), 39 deletions(-) diff --git a/docs/static/upgrading.asciidoc b/docs/static/upgrading.asciidoc index 378660de2..24292d736 100644 --- a/docs/static/upgrading.asciidoc +++ b/docs/static/upgrading.asciidoc @@ -27,6 +27,36 @@ See the following topics for information about upgrading Logstash: * <> * <> +[float] +==== When to Upgrade + +Fresh installations can and should start with the same version across the Elastic Stack. + +Elasticsearch 7.0 does not require Logstash 7.0. An Elasticsearch 7.0 cluster +will happily receive data from earlier versions of Logstash 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 7.0, but do so in the way that makes the most sense for your +environment. + +[float] +==== When Not to Upgrade + +If any Logstash plugin that you require is not compatible with Logstash 7.0, then you should wait until it is ready +before upgrading. + +Although we make great efforts to ensure compatibility, Logstash 7.0 is not completely backwards compatible. As noted +in the Elastic Stack upgrade guide, Logstash 7.0 should not be upgraded before Elasticsearch 7.0. This is both +practical and because some Logstash 7.0 plugins may attempt to use features of Elasticsearch 7.0 that did not exist +in earlier versions. For example, if you attempt to send the 7.x template to a cluster before Elasticsearch 7.0, then +all indexing likely fail. If you use your own custom template with Logstash, +then this issue can be ignored. + + [[upgrading-using-package-managers]] === Upgrading Using Package Managers @@ -53,8 +83,6 @@ Configuration options for some Logstash plugins have changed in the 7.x release. 5. Restart your Logstash pipeline after updating your configuration file. - - [[upgrading-minor-versions]] === Upgrading between minor versions @@ -67,6 +95,50 @@ settings and exported fields. Please review the Upgrading between non-consecutive major versions (5.x to 7.x, for example) is not supported. + +[[upgrading-logstash-7.0]] +=== Upgrading Logstash to 7.0 + +coming[7.0.0] + +Before upgrading Logstash: + +* Read the <>. +* Read the <> docs. ++ +There you can find info on these topics and more: + +** Java execution engine enabled by default +** Field parser is more strict and how that affects processing +** Beats conforms to the Elastic Common Schema (ECS) and how that impacts {ls} + +//TO DO: ^^ Add links <> and <> and <> after breaking changes are merged + +If you are installing Logstash with other components in the Elastic Stack, also see the +{stack-ref}/index.html[Elastic Stack installation and upgrade documentation]. + +NOTE: Upgrading between non-consecutive major versions (5.x to 7.x, for example) is not +supported. We recommend that you upgrade to 6.x, and then upgrade to 7.x. + +[float] +[[upgrade-to-6.7-rec]] +==== Upgrade to {ls} 6.7 before upgrading to 7.0 + +If you haven't already, upgrade to version 6.7 before you upgrade to 7.0. If +you're using other products in the {stack}, upgrade {ls} as part of the +{stack-ref}/upgrading-elastic-stack.html[{stack} upgrade process]. + +TIP: Upgrading to {ls} 6.7 will give you a head-start on new 7.0 features, including +the java execution engine and the strict field reference parser, while you're still running 6.x. +This step helps reduce risk and makes roll backs easier if you hit +a snag. + +//TO DO: Add links [[field-ref-strict]] and [[java-exec-default]] after upgrade docs are merged + +Upgrading to 6.7 is required because the {es} index template was modified to +be compatible with {es} 7.0 (the `_type` setting changed from `doc` to `_doc`). + + [[upgrading-logstash-pqs]] === Upgrading with the Persistent Queue Enabled @@ -124,40 +196,3 @@ Keep in mind that only one Logstash instance can write to `path.queue`. You cannot have the original instance and the new instance writing to the queue at the same time. -[[upgrading-logstash-7.0]] -=== Upgrading Logstash to 7.0 - -Before upgrading Logstash, remember to read the <> docs and the <>. - -If you are installing Logstash with other components in the Elastic Stack, also see the -{stack-ref}/index.html[Elastic Stack installation and upgrade documentation]. - -NOTE: Upgrading between non-consecutive major versions (5.x to 7.x, for example) is not -supported. We recommend that you upgrade to 6.x, and then upgrade to 7.x. - -==== When to Upgrade - -Fresh installations can and should start with the same version across the Elastic Stack. - -Elasticsearch 7.0 does not require Logstash 7.0. An Elasticsearch 7.0 cluster -will happily receive data from earlier versions of Logstash 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 7.0, but do so in -the way that makes the most sense for your environment. - -==== When Not to Upgrade - -If any Logstash plugin that you require is not compatible with Logstash 7.0, then you should wait until it is ready -before upgrading. - -Although we make great efforts to ensure compatibility, Logstash 7.0 is not completely backwards compatible. As noted -in the Elastic Stack upgrade guide, Logstash 7.0 should not be upgraded before Elasticsearch 7.0. This is both -practical and because some Logstash 7.0 plugins may attempt to use features of Elasticsearch 7.0 that did not exist -in earlier versions. For example, if you attempt to send the 7.x template to a cluster before Elasticsearch 7.0, then -all indexing likely fail. If you use your own custom template with Logstash, -then this issue can be ignored.