mirror of
https://github.com/elastic/logstash.git
synced 2025-04-23 06:08:19 -04:00
108 lines
4.8 KiB
Text
108 lines
4.8 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.
|
||
===========================================
|
||
|
||
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].
|
||
|
||
See the following topics for information about upgrading Logstash:
|
||
|
||
* <<upgrading-using-package-managers>>
|
||
* <<upgrading-using-direct-download>>
|
||
* <<upgrading-logstash-5.0>>
|
||
* <<upgrading-logstash-pqs>>
|
||
|
||
[[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-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.
|
||
|
||
[[upgrading-logstash-pqs]]
|
||
=== Upgrading with the Persistent Queue Enabled
|
||
|
||
The following applies only if you are upgrading Logstash and have the persistent
|
||
queue enabled.
|
||
|
||
[[drain-pq]]
|
||
==== Drain the Persistent Queue
|
||
|
||
If you use the persistent queue, we strongly recommend that you drain or delete
|
||
it 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.
|
||
|