Update the Upgrading Using a Direct Download guide section. by andsel · Pull Request #13684 · elastic/logstash

andsel · 2022-01-26T15:28:41Z

PREVIEW: https://logstash_13684.docs-preview.app.elstc.co/guide/en/logstash/master/upgrading-using-direct-download.html

Release notes

[rn:skip]

What does this PR do?

During the time Logstash switched from a set of Ruby files plus one fat jar to multiple jars, with configuration files
and shell scripts that also needs to be updated. It's not anymore sufficient to suggest to unpack a new distribution
over an existing one. This is problematic when we add jars from version to version because drive to the pollution
of the classpath.

This commit redefines to steps to do this, in a safer way, backing up data and config folders.

Why is it important/What is the impact to the user?

Checklist

My code follows the style guidelines of this project
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
I have made corresponding change to the default configuration files (and/or docker env variables)
I have added tests that prove my fix is effective or that my feature works

Author's Checklist

[ ]

How to test this PR locally

Related issues

Use cases

Screenshots

Logs

During the time Logstash switched from a set of Ruby files plus one fat jar to multiple jars, with configuration files and shell scripts that also needs to be updated. It's not anymore sufficient to suggest to unpack a new distribution over an existing one. This is problematic when we add jars from version to version because drive to the pollution of the classpath. This commit redefines to steps to do this, in a safer way, backing up data and config folders.

karenzone

Minor formatting and wording suggestions for your consideration.
FYI: I usually try to validate procedures as part of a review. I did not test these steps.

karenzone · 2022-01-27T01:19:21Z

docs/static/upgrading.asciidoc

 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.


Suggested change

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.

. Shut down your Logstash pipeline, including any inputs that send events to Logstash.

. Download the https://www.elastic.co/downloads/logstash[Logstash installation file] that matches your host environment.

This notation sets up autonumbering. :-)

karenzone · 2022-01-27T01:23:12Z

docs/static/upgrading.asciidoc

+3. Backup your `config/` and `data/` folders in a temporary space.
+4. Remove your Logstash directory.
+5. Unpack the installation file into the same folder your existing Logstash directory was present.
+6. Restore the `config/` and `data/` folders that was previously saved, overwriting the folders created during the unpack operation.
+7. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command.


Suggested change

3. Backup your `config/` and `data/` folders in a temporary space.

4. Remove your Logstash directory.

5. Unpack the installation file into the same folder your existing Logstash directory was present.

6. Restore the `config/` and `data/` folders that was previously saved, overwriting the folders created during the unpack operation.

7. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command.

. Backup your `config/` and `data/` folders in a temporary space.

. Delete your Logstash directory.

. Unpack the installation file into the folder that contained the Logstash directory that you just deleted.

. Restore the `config/` and `data/` folders that were previously saved, overwriting the folders created during the unpack operation.

. Test your configuration file with the `logstash --config.test_and_exit -f <configuration-file>` command.

karenzone · 2022-01-27T01:23:26Z

docs/static/upgrading.asciidoc

 Configuration options for
 some Logstash plugins have changed in the 7.x release.
-5. Restart your Logstash pipeline after updating your configuration file.
+8. Restart your Logstash pipeline after updating your configuration file.


Suggested change

8. Restart your Logstash pipeline after updating your configuration file.

. Restart your Logstash pipeline after updating your configuration file.

andsel · 2022-01-27T08:36:17Z

Thanks @karenzone
I've integrated you suggestion and executed the steps upgrading a 7.4to a 7.16 and a 6.8 to 7.16, the steps listed were ok.
The only doubt I have, which is nor covered by the other update methods, is that if a user previously installed plugins that's not part of the distribution, he has to remember to manually reinstall those.

docs/static/upgrading.asciidoc

karenzone

I left one comment inline. Otherwise, builds cleanly and LGTM. Thanks for your work on this.

Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com>

…13684) During the time Logstash switched from a set of Ruby files plus one fat jar to multiple jars, with configuration files and shell scripts that also needs to be updated. It's not anymore sufficient to suggest to unpack a new distribution over an existing one. This is problematic when we add jars from version to version because drive to the pollution of the classpath. This commit redefines to steps to do this, in a safer way, backing up data and config folders. Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com (cherry picked from commit 30b9ad8)

… section. (#13684) (#13741) Clean backport of #13684 to branch `8.1` ---- Original comment During the time Logstash switched from a set of Ruby files plus one fat jar to multiple jars, with configuration files and shell scripts that also needs to be updated. It's not anymore sufficient to suggest to unpack a new distribution over an existing one. This is problematic when we add jars from version to version because drive to the pollution of the classpath. This commit redefines to steps to do this, in a safer way, backing up data and config folders. Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com (cherry picked from commit 30b9ad8)

… section. (#13684) (#13742) Clean backport of #13684 to branch `8.0` ---- Original comment During the time Logstash switched from a set of Ruby files plus one fat jar to multiple jars, with configuration files and shell scripts that also needs to be updated. It's not anymore sufficient to suggest to unpack a new distribution over an existing one. This is problematic when we add jars from version to version because drive to the pollution of the classpath. This commit redefines to steps to do this, in a safer way, backing up data and config folders. Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com (cherry picked from commit 30b9ad8)

andsel added the docs label Jan 26, 2022

roaksoax added the status:needs-review label Jan 26, 2022

roaksoax assigned andsel Jan 26, 2022

andsel requested a review from karenzone January 26, 2022 17:21

karenzone reviewed Jan 27, 2022

View reviewed changes

Reworded and used automatic numbering of item in list of steps

140486b

andsel requested a review from karenzone January 27, 2022 08:36

andsel mentioned this pull request Feb 4, 2022

Doc: Update upgrade info for 8.0 in main #13705

Merged

karenzone reviewed Feb 9, 2022

View reviewed changes

docs/static/upgrading.asciidoc Outdated Show resolved Hide resolved

karenzone approved these changes Feb 9, 2022

View reviewed changes

Removed specific version citation

bfab290

Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com>

andsel merged commit 30b9ad8 into elastic:main Feb 9, 2022

andsel mentioned this pull request Feb 9, 2022

[backport 8.1]Update the Upgrading Using a Direct Download guide section. (#13684) #13741

Merged

andsel mentioned this pull request Feb 9, 2022

[backport 8.0] Update the Upgrading Using a Direct Download guide section. (#13684) #13742

Merged

roaksoax removed the status:needs-review label Feb 9, 2022

andsel added v8.0.1 v8.1.0 labels Feb 24, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the Upgrading Using a Direct Download guide section.#13684

Update the Upgrading Using a Direct Download guide section.#13684
andsel merged 3 commits intoelastic:mainfrom
andsel:fix/update_steps_to_upgrade_from_direct_download

andsel commented Jan 26, 2022 •

edited by karenzone

Loading

Uh oh!

karenzone left a comment

Uh oh!

karenzone Jan 27, 2022

Uh oh!

karenzone Jan 27, 2022

Uh oh!

karenzone Jan 27, 2022

Uh oh!

karenzone Jan 27, 2022

Uh oh!

andsel commented Jan 27, 2022

Uh oh!

Uh oh!

karenzone left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		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.

	8. Restart your Logstash pipeline after updating your configuration file.
	. Restart your Logstash pipeline after updating your configuration file.

Conversation

andsel commented Jan 26, 2022 • edited by karenzone Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release notes

What does this PR do?

Why is it important/What is the impact to the user?

Checklist

Author's Checklist

How to test this PR locally

Related issues

Use cases

Screenshots

Logs

Uh oh!

karenzone left a comment

Choose a reason for hiding this comment

Uh oh!

karenzone Jan 27, 2022

Choose a reason for hiding this comment

Uh oh!

karenzone Jan 27, 2022

Choose a reason for hiding this comment

Uh oh!

karenzone Jan 27, 2022

Choose a reason for hiding this comment

Uh oh!

karenzone Jan 27, 2022

Choose a reason for hiding this comment

Uh oh!

andsel commented Jan 27, 2022

Uh oh!

Uh oh!

karenzone left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

andsel commented Jan 26, 2022 •

edited by karenzone

Loading