Add upgrading guide docs #5068
Add upgrading guide docs #5068
Conversation
Part of / related to elastic#4737.
libbeat/docs/upgrading.asciidoc
Outdated
| recommend copying the `.filebeat` file to `data/registry`. | ||
| 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. However, that is not always |
There was a problem hiding this comment.
Change to: ...working, but deprecated them.
There was a problem hiding this comment.
Change to: 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.
libbeat/docs/upgrading.asciidoc
Outdated
| functionality. More precisely, the Topbeat functionality is roughly equivalent | ||
| to the "system" module in Metricbeat. | ||
| While the all-in-one configuration is still fully supported, we recommend moving | ||
| to the new layout at upgrade time. This typically means starting of with the new |
There was a problem hiding this comment.
...means staring off with... [fix typo]
libbeat/docs/upgrading.asciidoc
Outdated
| to the "system" module in Metricbeat. | ||
| While the all-in-one configuration is still fully supported, we recommend moving | ||
| to the new layout at upgrade time. This typically means starting of with the new | ||
| default configuration and modify it with the custom settings that you had in |
There was a problem hiding this comment.
....and modifying it....
libbeat/docs/upgrading.asciidoc
Outdated
| While the all-in-one configuration is still fully supported, we recommend moving | ||
| to the new layout at upgrade time. This typically means starting of with the new | ||
| default configuration and modify it with the custom settings that you had in | ||
| your old files. |
There was a problem hiding this comment.
When I get the PR for modules.d merged, we should link to the new docs. hopefully will get those merged soon.
libbeat/docs/upgrading.asciidoc
Outdated
| - cpu | ||
| 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, not for using it as |
There was a problem hiding this comment.
I'd make this two sentences:
We recommend using this file as a reference only. It's not intended to be used in production.
libbeat/docs/upgrading.asciidoc
Outdated
| 3. Start the new version of the Beat | ||
| And the corresponding Elasticsearch template is named `metricbeat-6.0.0`. This | ||
| means that each version starts a new index and it is guaranteed that the correct | ||
| template is applied. This means that starting with the 6.0 version, you |
There was a problem hiding this comment.
I wouldn't start two sentences in a row with "this means". Also I think there might be a little detail missing that users might infer, but there's a chance they won't. How about:
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.
libbeat/docs/upgrading.asciidoc
Outdated
|
|
||
| ==== Migrate configuration files | ||
| It is recommended to first fully upgrade Elasticsearch and Kibana to version |
There was a problem hiding this comment.
I prefer the directness of using "we" in recommendations like this one:
We recommend that you fully upgrade Elasticsearch and Kibana to version 6.0 before upgrading Beats.
libbeat/docs/upgrading.asciidoc
Outdated
| Beats 5.0 comes with several backwards incompatible configuration changes. | ||
| However, we provide a script that can automatically fixup the most common | ||
| settings in your configuration files. | ||
| If you upgrade Elasticsearch before Beats, it's important to apply the 5.6 |
There was a problem hiding this comment.
The wording here makes it sound like our recommended approach (to update ES/Kibana first) is more cumbersome than upgrading the Beat first. So maybe we should describe the requirements based on our recommended approach and then tell users what to do if they aren't ready to upgrade ES/Kibana. TBH, I'm not sure you need to even mention the template here since you are going to send users to the section about upgrading to 5.6 (might simplify the messaging). How about changing the whole section (lines 34-42) to say:
--
We recommend that you fully upgrade Elasticsearch and Kibana to version 6.0 before upgrading Beats. If you are on a 5.x version lower than 5.6, please follow the <<upgrading-to-5.6>> section before doing the Elasticsearch upgrade.
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.
There was a problem hiding this comment.
Your version sounds great, thanks!
libbeat/docs/upgrading.asciidoc
Outdated
| For the `.deb` and `.rpm` packages, look under the | ||
| `/usr/share/<beatname>/scripts/` folder, for example: | ||
| The upgrade procedure assumes that you have Beats version 5.6 installed. If you | ||
| are on a previous 5.x version of the Beats, please upgrade to version 5.6 first. |
There was a problem hiding this comment.
...5.x version of Beats... (remove "the")
libbeat/docs/upgrading.asciidoc
Outdated
|
|
||
| For example, this is the input section of the Topbeat configuration file: | ||
| Beats 6.0 introduce a new command to test the configuration file, via the `test` |
There was a problem hiding this comment.
Since you are using Beats 6.0 as a product name, use the singular form of the verb. I'd also condense this a bit and say:
Beats 6.0 introduces a new test command for testing the configuration file. For example:
|
|
||
| [source,shell] | ||
| ------------------------------------------------------------------------------ | ||
| > ./scripts/migrate_beat_config_1_x_to_5_0.py packetbeat.yml | ||
| Backup file created: packetbeat.yml.bak | ||
| curl -XPUT -H'Content-Type: application/json' http://localhost:9200/_template/metricbeat -d @metricbeat.template.json |
There was a problem hiding this comment.
Why not using the setup command for that? in Beats 6.0, it's ./metricbeat setup --template
There was a problem hiding this comment.
The user is on Beats 5.6 at this point.
libbeat/docs/upgrading.asciidoc
Outdated
| with the upgraded version. You can also use the `--dry` option, which doesn't | ||
| modify the input file, but outputs the upgraded version to stdout instead. | ||
| 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 |
There was a problem hiding this comment.
why not using the export command for that? In Beats 6.0, it's ./metricbeat export template.
There was a problem hiding this comment.
Same as above, we're still on 5.6 at that step.
|
|
||
| # Per filesystem stats | ||
| - filesystem | ||
| We recommend re-importing the Kibana dashboards after the Beats and Kibana |
There was a problem hiding this comment.
I would say explicitly, that upgrading the Kibana doesn't require dashboards upgrade, but if the user is interested in the new version of the dashboards that are shipped with 6.0, then it can reimport them.
There was a problem hiding this comment.
I added a sentence to explain why we recommend that.
|
Thanks @dedemorton and @monicasarbu, I've incorporated your feedback. |
* Add upgrading guide docs Part of / related to elastic#4737.
dedemorton
removed
the
needs_backport
…#5103) * [Docs] Document how to use modules.d directory (elastic#4973) * [Docs] Document how to use modules.d directory * Add changes from review * Add upgrading guide docs (elastic#5068) * Add upgrading guide docs Part of / related to elastic#4737.
Part of / related to #4737.
Also part of #4540.