Skip to content

Add upgrade docs #11378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Apr 2, 2019
Merged

Add upgrade docs #11378

Changes from 6 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
c1a40bf
Add upgrade docs
dedemorton Mar 21, 2019
ee0c7df
Apply suggestions from code review
dedemorton Mar 21, 2019
f37783b
Add more detail based on review feedback
dedemorton Mar 28, 2019
e8edc64
A few clarifications
dedemorton Mar 29, 2019
10877a9
Remove old file
dedemorton Mar 29, 2019
9c5aa4f
Rename file to original name
dedemorton Mar 29, 2019
043f7b8
More changes from review
dedemorton Mar 30, 2019
6faa6d5
Add changes from review before moving stuff around
dedemorton Apr 1, 2019
cc8b429
Move some content and clean it up
dedemorton Apr 1, 2019
5c914b3
Merge branch 'master' into update_migration_info
dedemorton Apr 1, 2019
4fb0acd
Add more fixes from the review
dedemorton Apr 2, 2019
2657b48
Add more changes based on review comments
dedemorton Apr 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 152 additions & 96 deletions libbeat/docs/upgrading.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,160 +1,216 @@
[[upgrading]]
== Upgrading

This section gives general recommendations for upgrading the Beats:
This section gives general recommendations for upgrading {beats} shippers:

* <<upgrading-minor-versions>>
* <<upgrading-5-to-6>>
* <<upgrading-6-to-7>>
* <<upgrade-mapping-template>>

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].
{stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide].

[[upgrading-minor-versions]]
=== Upgrade between minor versions

As a general rule, upgrading between minor versions (e.g. 6.x to 6.y, where x <
y) can be done by simply installing the new release and restarting the Beat
process, because the Beats keep backwards compatibility when it comes to
configuration and exported fields. Please review the <<release-notes,release
notes>> for potential exceptions.
As a general rule, you can upgrade between minor versions (for example, 7.x to
7.y, where x < y) by simply installing the new release and restarting the Beat
process. {beats} typically maintain backwards compatibility for configuration
settings and exported fields. Please review the
<<release-notes,release notes>> for potential exceptions.

Upgrading between non-consecutive major versions (e.g. 1.x to 6.x) is not
supported. If you are on version 1.x of the Beats, we recommend first upgrading
to 5.6.
Upgrading between non-consecutive major versions (e.g. 5.x to 7.x) is not
supported.

[[upgrading-5-to-6]]
=== Upgrade from 5.x to 6.x
[[upgrading-6-to-7]]
=== Upgrade from 6.x to 7.x

Before upgrading your Beats, please review the <<breaking-changes, breaking
changes>> doc.
Before upgrading your {beats}, review the <<breaking-changes,breaking changes>>.

// TODO: link to the stack upgrade docs
//
// If you are planning an upgrade of the full stack (Elasticsearch, Kibana, or
// Logstash, in addition to Beats), please read the stack upgrade guide.
If you're upgrading other products in the stack, also read the
{stack-ref}/index.html[Elastic Stack Installation and Upgrade Guide].

We recommend that you fully upgrade {es} and {kib} to version 7.0
before upgrading {beats}. If you're on Beats 6.0 through 6.6,
<<upgrading-to-6.7,upgrade to Beats 6.7>> *before* doing the {es} upgrade.
Copy link

@cjcenizal cjcenizal Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really minor, but when I was reading the generated doc, I saw this link and immediately thought to open it in a new tab because it looks like a link to a related resource. However, it's a link to the anchor tag a few lines down. Does it help the user that much or do we think that they'll find the content naturally and intuitively without the link? It might be worth removing it if so. Just a thought.

image

Copy link
Contributor Author

@dedemorton dedemorton Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yah that's a valid point. I'll remove the link.


We recommend that you fully upgrade Elasticsearch and Kibana to version 6.0
before upgrading Beats. If you are on a Beats 5.x version lower than 5.6, please
follow the <<upgrading-to-5.6>> section *before* doing the Elasticsearch
upgrade.
Upgrading between non-consecutive major versions (e.g. 5.x to 7.x) is not
supported.

If you're not ready to upgrade Elasticsearch and Kibana to 6.0, that's alright.
Beats version 6.0 works with Elasticsearch and Kibana version 5.6, so you can
upgrade Beats now and the rest of the stack later.
// REVIEWERS: I think it's worth begin redundant here ^^ because users often
// don't read topics in the order we expect.

[[upgrading-to-5.6]]
==== Upgrade to 5.6
[[upgrading-to-6.7]]
==== Upgrade to Beats 6.7 before upgrading to 7.0

The upgrade procedure assumes that you have Beats version 5.6 installed. If you
are on a previous 5.x version of Beats, please upgrade to version 5.6 first.
The reason is that the Elasticsearch mapping template in 5.6 was modified to be
compatible with Elasticsearch 6.0 (by removing the `_all` settings).
The upgrade procedure assumes that you have {beats} 6.7 installed. If you're on
a previous 6.x version of {beats}, upgrade to version 6.7 first. This is
required because the {es} mapping template in 6.7 was modified to be compatible
with {es} 7.0 (the `_type` setting changed from `doc` to `_doc`).

For this reason, after upgrading to 5.6, you need to make sure that the 5.6
template is loaded. You can do this by temporarily enabling the
`output.elasticsearch.template.overwrite` setting, for example with Metricbeat:
After upgrading to 6.7, make sure the 6.7 template gets loaded. You can do this
by temporarily enabling the `output.elasticsearch.template.overwrite` setting,
for example with Metricbeat:

[source,shell]
------------------------------------------------------------------------------
----
metricbeat -e -E output.elasticsearch.template.overwrite=true
------------------------------------------------------------------------------
----

Alternatively, you can manually force loading the template:
Or you can manually force loading the template:

[source,shell]
------------------------------------------------------------------------------
----
curl -XPUT -H'Content-Type: application/json' http://localhost:9200/_template/metricbeat -d @metricbeat.template.json
Copy link
Contributor

@ruflin ruflin Apr 2, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should not recommend this as users must put in the correct version for the template. Already this example is wihtout the version so we rather remove it completely and force users to use the beat directly to load it which will to the right thing.

Copy link

@cjcenizal cjcenizal Apr 2, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're going to drop this, it might be worth adding a note that it's no longer recommended:

Note: In previous versions, we advised users to create the Metricbeat index template from the command line. This is no longer recommended. Use the metricbeat command outlined above.

Copy link
Contributor Author

@dedemorton dedemorton Apr 2, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ruflin Do we want to remove this section from the getting started, too? https://www.elastic.co/guide/en/beats/packetbeat/current/packetbeat-template.html#load-template-manually-alternate

Copy link
Contributor

@ruflin ruflin Apr 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes

Copy link
Contributor

@ruflin ruflin Apr 3, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At least there we have version numbers but I would rather recommend loading it with running the beat TBH.

------------------------------------------------------------------------------
----

To check the template version, open the {kib} Console and run:

[source,js]
----
GET /_template/metricbeat
----
// CONSOLE

To check which version of the template is loaded, open Kibana Console, call `GET
/_template/metricbeat`, and look for the version string. Note that you need to
do this for each Beat type that you are running (e.g. Filebeat, Metricbeat,
Packetbeat).
Look for the version string in the response. Repeat this step for every Beat
running in your environment.

*Metricbeat and Filebeat users:* If you use {beats} central management,
make sure you migrate the {beats} central management index to 6.7 before you
upgrade to 7.0.

// REVIEWERS: Not sure I should mention this here ^^. I didn't link directly
// to the 6.7 breaking changes docs here because I'm concerned about users
// getting into the wrong upgrade docs and being confused.

[[migrate-config-files]]
==== Migrate configuration files

Beats 6.0 comes with several backwards incompatible configuration changes.
Please review the <<breaking-changes-6.0>> document. Where possible, we kept the
old configuration options working, but deprecated them. However, deprecation
was not always possible, so if you use any of the settings mentioned in the
Breaking Changes section of the release notes, make sure you understand the
alternatives that we provide.
// REVIEWERS: What changes do users need to make to their config files? Will we
// offer any kind of migration tooling to make this easier?

{beats} 7.0 comes with several backwards incompatible configuration changes.
Before upgrading, review the <<breaking-changes-7.0>> document. Where possible,
we kept the old configuration options working, but deprecated them. However,
deprecation was not always possible, so if you use any of the settings mentioned
in the Breaking Changes section of the release notes, make sure you understand
the alternatives that we provide.

===== modules.d configuration layout
[[enable-ecs-compatibility]]
==== Enable compatibility layer for Elastic Common Schema (ECS) fields

Starting with the 6.0 version, Filebeat and Metricbeat are moving to a directory
layout for configuration, where each module is configured in its own
configuration file.
Starting with 7.0, the fields exported by {beats} conform to the
{ecs-ref}/index.html[Elastic Common Schema (ECS)]. Many of the exported fields
have been renamed. See {beats-ref}/breaking-changes-7.0.html[Breaking
changes in 7.0] for the full list of changed names.

While the all-in-one configuration is still fully supported, we recommend moving
to the new layout at upgrade time. This typically means starting off with the new
default configuration and modifying it with the custom settings that you had in
your old files.
To help you transition to the new fields, we provide a compatibility layer in
the form of ECS-compatible field aliases. To use the aliases, set
`migration.6_to_7.enabled: true` in the Beat's configuration file *before* you
run Beats 7.0 to ingest data for the first time.

// TODO: link to the docs on modules.d
The compatibility layer enables you to use 6.x dashboards and visualizations
with indices created by {beats} 7.0 or later.

===== New command `test config` command
// TODO: Describe how to wipe out old data and overwrite the template for
// situations where users ingest data before realizing they need to set the
// migration flag.
//
// I do wonder why this flag is not the default, but maybe it creates a lot of
// extra noise for users who don't want compatibility?

==== Upgrade dashboards

We recommend that you reload the {kib} dashboards after upgrading {kib} and
{beats}. This way, you can take advantage of the new {beats} dashboards created
for the 7.0 release.

Beats 6.0 introduces a new test command for testing the configuration file. For
example:
Reloading the dashboards will overwrite any manual changes that you've
made. To avoid overwriting existing dashboards, save them under a new ID before
proceeding.

To reload the dashboards, run the `setup` command with the `--dashboards`
option specified. For example:

[source,shell]
------------------------------------------------------------------------------
metricbeat test config
------------------------------------------------------------------------------
----
metricbeat setup --dashboards
----

The old `-configtest` flag is still available, but deprecated.
Also, if you plan to run {beats} 6.7 and 7.0 in parallel, set
`migration.6_to_7.enabled: true` to make 6.x dashboards compatible with 7.0
{beats} indices *before* you start ingesting data. For more information, see
<<enable-ecs-compatibility>>.

===== Reference configuration files
==== Configure {ls} to use versioned templates and indices

The `<beatname>.full.yml` file, which contains all the non-deprecated
configuration options is renamed to `<beatname>.reference.yml` starting with
Beats 6.0. We recommend using this file as a reference only. It's not intended
to be used in production.
Before upgrading to 7.0, make sure {ls} uses versioned templates and indices.
Copy link

@cjcenizal cjcenizal Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it's implied, but maybe it's worth explicitly stating, "If you're using Logstash to ingest your Beats data..." so that people won't think LS is required for upgrading.

Copy link

@cjcenizal cjcenizal Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, what does "versioned templates" mean in this case? The link below goes to plugins-inputs-beats.html which currently only mentions versioned indices.

Copy link

@cjcenizal cjcenizal Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CC @ruflin ^

Copy link
Contributor Author

@dedemorton dedemorton Mar 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm modifying this section a bit to show the settings (including manage_template => false, which let's Beats manage the template).

Otherwise, after you upgrade, {ls} will stop ingesting data because of field
conflicts.

==== Dashboard upgrades
For the recommended {ls} configuration, see the
{logstash-ref}/plugins-inputs-beats.html[{beats} input plugin] documentation.

We recommend re-importing the Kibana dashboards after the Beats and Kibana
upgrades are complete. This way, you will take advantage of the new Beats
dashboards created for the 6.0 release.
[[migrate-filebeat-registry]]
==== Migrate Filebeat registry to use new format

See <<breaking-changes-import-dashboards>> in the Breaking Changes
documentation.
Starting with the 7.0 version, {filebeat} stores the registry in a directory
structure. If Filebeat finds an old registry file at the path set by
`filebeat.registry.path`, it will automatically migrate the registry file to the
new format. If the registry file is at a different location, set
`filebeat.registry.migrate_file` to point to the file.

NOTE: If you've modified the Beats dashboards manually, reimporting them will
overwrite your changes. Consider saving your dashboards under new IDs, so
that the reimport doesn't overwrite them.
[role="xpack"]
[[ilm-on]]
==== Check privileges for index lifecycle management (on by default in 7.0)

==== Heartbeat package names
// REVIEWERS: not sure if this is worth pointing out in the upgrade docs but
// I think the default changing is going to confuse some users.

The DEB and RPM packages for Heartbeat are now named `heartbeat-elastic` to
avoid conflicts with a different `heartbeat` project. The `.deb` and `.rpm`
file names haven't changed, just the package name in the repositories.
Staring with {beats} 7.0, index lifecycle management is on by default when
sending data to {beats} clusters that support it. Make sure {beats} users have
the privileges needed to use index lifecycle management, or disable index
lifecycle management. The following privileges are required:

* To set up index lifecycle policies: `manage_ilm` and `monitor` on cluster
* To send data to a secured cluster when index lifecycle management is enabled:
`manage_index_templates` and `monitor` on cluster, and `index` and `manage` on
{beats} indices.

// REVIEWERS: The privileges shown here are based on testing I did for
// https://github.com/elastic/beats/pull/11329, but I am still waiting for
// more review comments on that PR.

To disable index lifecycle management, set `setup.ilm.enabled: false` in the
{beats} configuration file.

// TODO: Add a section that describes what to do if you've configured an output
// other than Elasticsearch.

[[upgrade-mapping-template]]
=== Upgrade the Elasticsearch mapping template
=== Upgrade the {es} mapping template

Starting with Beats 6.0, the mapping templates and the default index names are
versioned. For example, Metricbeat 6.0.0 creates indices like this:
// REVIEWERS: Does this topic really belong on its own rather than as a
// sub-topic? Do we want to tell users to set

[source,shell]
Mapping templates and the default index names are versioned. For example,
Metricbeat {stack-version} typically creates indices like this:

["source","sh",subs="attributes"]
------------------------------------------------------------------------------
metricbeat-6.0.0-2017-08-31
metricbeat-{stack-version}-{localdate}
------------------------------------------------------------------------------

And the corresponding Elasticsearch template is named `metricbeat-6.0.0`.
And the corresponding {es} template is named +metricbeat-{stack-version}+.

This means that each version of the Beat creates a new index, and it is
guaranteed that the correct template for that version is applied. With these
guaranteed that the correct template for that version is applied. With these
changes in place, you generally don't have to do anything to upgrade the mapping
template when you move to a new version.

One exception is when upgrading from 5.x, in which case you should make sure to
read the <<upgrading-to-5.6>> section.
// REVIEWERS: I'm not sure what the following paragraph means. Why would this
// result in downtime?

If downtime is not acceptable, another possible approach is to configure a
different index pattern in the new Beat version, but this will likely require
adjustments to your Kibana dashboards.
adjustments to your {kib} dashboards.