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

Add instructions for upgrading PQ pre-6.3.0

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

52
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.
===========================================
@ -18,8 +19,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-logstash-pqs>>
[[upgrading-using-package-managers]]
=== Upgrading Using Package Managers
@ -46,20 +47,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
@ -95,3 +82,38 @@ 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-logstash-pqs]]
=== Upgrading Persistent Queue
The following applies only if you are upgrading from Logstash version 6.2.x or
earlier with the persistent queue enabled.
We regret to say that due to several serialization issues in Logstash 6.2.x and
earlier, users will have to take some extra steps when upgrading Logstash with
the persistent queue enabled. While we strive to maintain backward compatibility
within a given major release, these bugs require 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 version 6.2.x or earlier 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 (using CTRL+C or SIGTERM), 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 so that these steps
won’t be required for future upgrades.