diff --git a/docs/static/breaking-changes.asciidoc b/docs/static/breaking-changes.asciidoc index e7837edaf..aa4bd5a3e 100644 --- a/docs/static/breaking-changes.asciidoc +++ b/docs/static/breaking-changes.asciidoc @@ -1,11 +1,27 @@ [[breaking-changes]] == Breaking Changes -This section discusses the changes that you need to be aware of when migrating to Logstash 6.0.0 from the previous major releases. +We strive to maintain backward compatibility between minor versions (6.x to 6.y, +for example) so that you can upgrade without changing any configuration files. +Breaking changes are usually introduced only between major versions (such as 5.x +to 6.y). On occasion, we are forced to break compatibility within a given major release +to ensure correctness of operation. + +This section covers the changes that you need to be aware of when migrating to +Logstash 6.0.0 and later. + +NOTE: Migrating directly between non-consecutive major versions (1.x to +6.x) is not recommended. + +See these topics for a description of breaking changes: + +* <> +* <> See also <>. [float] +[[breaking-pq]] === Breaking change across PQ versions prior to Logstash 6.3.0 If you are upgrading from Logstash 6.2.x or any earlier version (including 5.x) @@ -13,38 +29,44 @@ and have the persistent queue enabled, we strongly recommend that you drain or delete the persistent queue before you upgrade. See <> for information and instructions. -We are working to resolve issues with data incompatibilities in our 6.3.0 -release so that additional steps won't be required for future upgrades. +We are working to resolve issues with data incompatibilities so that additional +steps won't be required for future upgrades. [float] -=== Changes in Logstash Core +[[breaking-6.0]] +=== Breaking changes in 6.0 + +Here are the breaking changes for 6.0. + +[float] +==== Changes in Logstash Core These changes can impact any instance of Logstash and are plugin agnostic, but only if you are using the features that are impacted. [float] -==== Application Settings +===== Application Settings * The setting `config.reload.interval` has been changed to use time value strings such as `5m`, `10s` etc. Previously, users had to convert this to a millisecond time value themselves. [float] -==== RPM/Deb package changes +===== RPM/Deb package changes * For `rpm` and `deb` release artifacts, config files that match the `*.conf` glob pattern must be in the conf.d folder, or the files will not be loaded. [float] -==== Command Line Interface behavior +===== Command Line Interface behavior * The `-e` and `-f` CLI options are now mutually exclusive. This also applies to the corresponding long form options `config.string` and `path.config`. This means any configurations provided via `-e` will no longer be appended to the configurations provided via `-f`. * Configurations provided with `-f` or `config.path` will not be appended with `stdin` input and `stdout` output automatically. [float] -=== Plugin Changes +==== Plugin Changes [float] -==== Elasticsearch output changes +===== Elasticsearch output changes * The default `document_type` has changed from `logs` to `doc` for consistency with Beats. Furthermore, users are advised that Elasticsearch 6.0 deprecates doctypes, and 7.0 will remove them. @@ -54,7 +76,7 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o The new mapping template has been updated to reflect that. If you are using a custom mapping template you may need to update it to reflect that. [float] -==== Kafka input changes +===== Kafka input changes * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later. ** Please refer to <> documentation for information about Kafka compatibility with Logstash. @@ -63,21 +85,21 @@ These changes can impact any instance of Logstash and are plugin agnostic, but o * The `ssl` option is now obsolete. [float] -==== Kafka output changes +===== Kafka output changes * Upgraded Kafka client support to v0.11.0.0, which only supports Kafka brokers v0.10.x or later. ** Please refer to <> documentation for information about Kafka compatibility with Logstash. * The options `block_on_buffer_full`, `ssl`, and `timeout_ms` are now obsolete. [float] -==== Beats input changes +===== Beats input changes * Logstash will no longer start when <> is used with the Beats input plugin. ** It is recommended to use the multiline support in Filebeat as a replacement - see https://www.elastic.co/guide/en/beats/filebeat/current/multiline-examples.html[configuration options available in Filebeat] for details. * The options `congestion_threshold` and `target_field_for_codec` are now obsolete. [float] -==== List of plugins bundled with Logstash +===== List of plugins bundled with Logstash The following plugins were removed from the 6.0 default bundle based on usage data. You can still install these plugins manually: diff --git a/docs/static/upgrading.asciidoc b/docs/static/upgrading.asciidoc index 8bfa8feca..e3bddfcf2 100644 --- a/docs/static/upgrading.asciidoc +++ b/docs/static/upgrading.asciidoc @@ -127,6 +127,7 @@ 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-pq]] ==== Drain the Persistent Queue If you are upgrading from Logstash 6.2.x or an earlier version and use the persistent @@ -144,5 +145,5 @@ 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. +We are working to resolve issues with data incompatibilities so that these steps +won’t be required for future upgrades.