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

Add instructions for upgrading PQ pre-6.3.0

Browse source 
Fixes #9580
This commit is contained in:
Karen Metts 2018-05-15 15:25:00 -04:00 • committed by karen.metts
parent 57cee65757
commit e1a2f72caa
1 changed files with 36 additions and 15 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/static/upgrading.asciidoc vendored
View file

@ -6,6 +6,7 @@
Before upgrading Logstash:
* Consult the <<breaking-changes,breaking changes>> docs.
* Read the <<releasenotes>>.
* Test upgrades in a development environment before upgrading your production cluster.
While upgrading Logstash:
@ -24,8 +25,8 @@ See the following topics for information about upgrading Logstash:
* <<upgrading-using-package-managers>>
* <<upgrading-using-direct-download>>
* <<upgrading-logstash-pqs>>
* <<upgrading-logstash-6.0>>
* <<upgrading-pq-pre63>>
[[upgrading-using-package-managers]]
=== Upgrading Using Package Managers
@ -52,20 +53,6 @@ This procedure downloads the relevant Logstash binaries directly from Elastic.
some Logstash plugins have changed in the 5.x release.
5. Restart your Logstash pipeline after updating your configuration file.
[[upgrading-logstash-pqs]]
=== Upgrading with Persistent Queues Enabled
Upgrading Logstash with persistent queues enabled is supported. The persistent
queue directory is self-contained and can be read by a new Logstash instance
running the same pipeline. You can safely shut down the original Logstash
instance, spin up a new instance, and set `path.queue` in the `logstash.yml`
<<logstash-settings-file,settings file>> to point to the original queue directory.
You can also use a mounted drive to make this workflow easier.
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-6.0]]
=== Upgrading Logstash to 6.0
@ -125,3 +112,37 @@ Although we make great efforts to ensure compatibility, Logstash 6.0 is not comp
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.
[[upgrading-pq-pre63]]
=== Upgrading Persistent Queue from Logstash 6.2.x and Earlier
The following applies only if you are upgrading from Logstash installations prior
to 6.3.0 with the persistent queue enabled.
We regret to say that due to several serialization issues prior to Logstash
6.3.0, users will have to take some extra steps when upgrading Logstash
instances with the persistent queue enabled. While we strive to maintain
backward compatibility within a given major release, these bugs forced us to
break that compatibility in version 6.3.0 to ensure correctness of operation.
For more technical details on this issue, please check our tracking github issue
for this matter, https://github.com/elastic/logstash/issues/9494[#9494].
==== Drain the Persistent Queue
If you are upgrading from Logstash 6.2.x or an earlier version and use the persistent
queue, we strongly recommend that you drain or delete the persistent queue
before you upgrade.
To drain the queue:
. In the logstash.yml file, set `queue.drain:true`.
. Restart Logstash for this setting to take effect.
. Shutdown Logstash, and wait for the queue to empty.
When the queue is empty:
. Complete the upgrade.
. Restart Logstash.
We are working to resolve issues with data incompatibilities in our 6.3.0
release so that these steps won’t be required for future upgrades.