mirror of
https://github.com/elastic/logstash.git
synced 2025-04-24 22:57:16 -04:00
103 lines
5 KiB
Text
103 lines
5 KiB
Text
[[upgrading-logstash]]
|
|
== Upgrading Logstash
|
|
|
|
[IMPORTANT]
|
|
===========================================
|
|
Before upgrading Logstash:
|
|
|
|
* Consult the <<breaking-changes,breaking changes>> docs.
|
|
* Test upgrades in a development environment before upgrading your production cluster.
|
|
|
|
While upgrading Logstash:
|
|
|
|
* If you use {monitoring}, you must re-use the data directory when you
|
|
upgrade Logstash. Otherwise, the Logstash node is assigned a new persistent UUID
|
|
and becomes a new node in the monitoring data.
|
|
===========================================
|
|
|
|
If you're upgrading other products in the stack, also read the
|
|
{stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide]. Want an
|
|
upgrade list that's tailored to your stack? Try out our
|
|
{upgrade_guide}[Interactive Upgrade Guide].
|
|
|
|
See the following topics for information about upgrading Logstash:
|
|
|
|
* <<upgrading-using-package-managers>>
|
|
* <<upgrading-using-direct-download>>
|
|
* <<upgrading-logstash-pqs>>
|
|
* <<upgrading-logstash-5.0>>
|
|
|
|
[[upgrading-using-package-managers]]
|
|
=== Upgrading Using Package Managers
|
|
|
|
This procedure uses <<package-repositories,package managers>> to upgrade Logstash.
|
|
|
|
1. Shut down your Logstash pipeline, including any inputs that send events to Logstash.
|
|
2. Using the directions in the _Package Repositories_ section, update your repository links to point to the 5.x repositories
|
|
instead of the previous version.
|
|
3. Run the `apt-get upgrade logstash` or `yum update logstash` command as appropriate for your operating system.
|
|
4. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command. Configuration options for
|
|
some Logstash plugins have changed in the 5.x release.
|
|
5. Restart your Logstash pipeline after updating your configuration file.
|
|
|
|
[[upgrading-using-direct-download]]
|
|
=== Upgrading Using a Direct Download
|
|
|
|
This procedure downloads the relevant Logstash binaries directly from Elastic.
|
|
|
|
1. Shut down your Logstash pipeline, including any inputs that send events to Logstash.
|
|
2. Download the https://www.elastic.co/downloads/logstash[Logstash installation file] that matches your host environment.
|
|
3. Unpack the installation file into your Logstash directory.
|
|
4. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command. Configuration options for
|
|
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-5.0]]
|
|
=== Upgrading Logstash to 5.0
|
|
|
|
Before upgrading Logstash, remember to read the <<breaking-changes,breaking changes>>.
|
|
|
|
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].
|
|
|
|
==== When to Upgrade
|
|
|
|
Fresh installations can and should start with the same version across the Elastic Stack.
|
|
|
|
Elasticsearch 5.0 does not require Logstash 5.0. An Elasticsearch 5.0 cluster will happily receive data from a
|
|
Logstash 2.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 5.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 5.0, then you should wait until it is ready
|
|
before upgrading.
|
|
|
|
Although we make great efforts to ensure compatibility, Logstash 5.0 is not completely backwards compatible. As noted
|
|
in the Elastic Stack upgrade guide, Logstash 5.0 should not be upgraded before Elasticsearch 5.0. This is both
|
|
practical and because some Logstash 5.0 plugins may attempt to use features of Elasticsearch 5.0 that did not exist
|
|
in earlier versions. For example, if you attempt to send the 5.x template to a cluster before Elasticsearch 5.0, then it
|
|
will not be able to use it and all indexing will fail likely fail. If you use your own, custom template with Logstash,
|
|
then this issue can be ignored.
|
|
|
|
Note the Elasticsearch Output Index Template change in the <<breaking-changes>> documentation for further insight into
|
|
this change and how it impacts operations.
|