github-mirrors/logstash
1
0
Fork 0
mirror of https://github.com/elastic/logstash.git synced 2025-04-24 14:47:19 -04:00
Code Issues Projects Releases Packages Wiki Activity

Refine upgrade instructions for 7.0

Browse source 
Add recommendation to upgrade to 6.7 before 7.0

Fixes #10634
This commit is contained in:
Karen Metts 2019-04-03 11:04:38 -04:00
parent 3befda9325
commit f89dfb2124
1 changed files with 74 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

113
docs/static/upgrading.asciidoc vendored
View file

@ -27,6 +27,36 @@ See the following topics for information about upgrading Logstash:
* <<upgrading-logstash-7.0>>
* <<upgrading-logstash-pqs>>
[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 <<releasenotes>>.
* Read the <<breaking-changes,breaking changes>> 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 <<java-exec-default>> and <<field-ref-strict>> and <<beats-ecs>> 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 <<breaking-changes,breaking
changes>> docs and the <<releasenotes>>.
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.