search

Graylog2 / documentation

Archived Graylog documentation. See https://docs.graylog.org/ for the new documentation.
http://archivedocs.graylog.org/
Other
146 stars 248 forks source link

Request for improvements to "Upgrading Graylog" pages. #1220

Closed tellistone closed 2 years ago

tellistone commented 2 years ago

Case for improvement

The "Upgrading Graylog" page (https://docs.graylog.org/docs/upgrade) and its subpages does not (in my view) present information in a logical order, and some critical information is either missing or on other pages. My ancedotal experience from Support is that many users are nervous about the upgrade process, and those with Enterprise Support generally raise tickets seeking guidance through the upgrade process, or asking simple questions with answers that should already been conveyed by the documentation.

From the perspective of an administrator of an Enterprise Graylog platform, particularly a production environment in which the SLA on dropping messages or downtime is severe, the upgrade process needs to be as clear and defined as possible. If the upgrade process throws up a prompt, it is not unreasonable for the administrator to expect the correct response for that prompt to be already provided in the documentation so it can be part of their upgrade process runbook ahead of time. It is undesirable to hit a situation during an upgrade process where a user needs to make a decision that was not anticipated by the documentation. It is also undesirable to be writing a runbook for an upgrade process, and not have a definitive per-version list pre-requsities and breaking configuration changes.

The upgrade process documentation should minimize the need for the user to make decisions or do reading on other pages, it should be self contained. In my view, the upgrade process documentation should be as comprehensive as the exemplary pages describing how to install Graylog, for example here - https://docs.graylog.org/docs/ubuntu - which even a first-year computer science student can follow by rote and succeed.

I think these pages should be restructured to convey the answers to the questions users normally have about upgrading, in the order that they normally want the information. Making it easier for users to upgrade Graylog will have the trickle down effect of more users upgrading - meaning more users running an up to date, optimised and relatively bug free version of the product.

Find a list of Enterprise Support tickets raised over the last quarter that relate to the Upgrade process at the bottom of this ticket.

What does an administrator upgrading Graylog want to know?

From my experience, this is the information that I think should be first conveyed by https://docs.graylog.org/docs/upgrade

  1. The first thing a user typically wants to know if their upgrade path - how do I get from my current version, to the latest version, in the smallest number of steps.

Common questions: "Can we do it all in one, or does it have to be rolling?" "Do we need to check that Graylog still works between each upgrade step?"

To my understanding the upgrade path looks something like 3.0.x -> 3.1.x -> 3.3.x -> 4.0.x -> 4.1.x ->4.2.x. The documentation does not make this clear.

  1. Next, the user wants to know the minimum, and maximum, Elasticsearch and MongoDB version that works with each of those version steps. This could easily be conveyed with a table.

  2. Next, the user wants to know the upgrade path of their Elasticsearch and MongoDB installs (if applicable). This could be provided through links to the appropriate documentation for each product. Given this information doesn't change, it would be more user friendly to paraphrase the details from this documentation into the Graylog documentation pages. These may need to be upgraded in step with major version upgrades of Graylog in order for the upgrade to succeed, paritcularly if the user tests that Graylog is working (runs it) before proceeding to the next step.

  3. When the user runs a command to look at their installed Graylog packages. Eg. Debian/Ubuntu: apt list --installed | egrep "graylog" RHEL/CentOS: yum list installed | egrep "graylog"

They will likely see a number of packages, for example:

graylog-enterprise-plugins-3.3.4-1.noarch graylog-enterprise-integrations-plugins-3.3.4-1.noarch graylog-server-3.3.4-1.noarch graylog-integrations-plugins-3.3.4-1.noarch

For each install method, the user needs to know whether any such plugins and integrations are upgraded seperately, or upgraded automatically by the main package, and whether these need to be upgraded in step with the main version, or can be jumped direct to the latest. If these are upgraded seperately, the user needs instructions and/or a link to download the packages.

  1. For each version of Graylog in the upgrade path, the user needs to know in clear terms the mandatory or "breaking" configuration changes, so checks for these can be included in their upgrade runbook.

    • if a configuration key is added to a configuration file, and part of the Graylog stack does not work with it missing.
    • if the default install value of a configuration key is changed, and should be changed in the correspndong configuration file during the upgrade.
    • if particular configuration values no longer work/are not supported, or if the way they work changes.

  2. The user ideally wants a runbook - an equivalent of https://docs.graylog.org/docs/ubuntu but for the upgrade process - tailored for the type of upgrade they are doing. Which actions to perform in which order, depending on what type of install they are doing, with answers to any prompts suggested. We have seen users accidentally overwrite their configuration files during an upgrade because they answered a prompt incorrectly.

In the documentation for the install process, we offer a page per method that looks like this:

Screenshot 2021-10-20 at 13 04 52

We should provide the same for the upgrade process for each install type.

Users ask a lot of questions around the order that the process is performed in, that would be easily resolved by having a runbook they can view.

Perhaps could have a dropdown at the top of the page(s) that sets the version, which is then reflected in the text of the page.

  1. When the user has figured out their process, for many types of installs the user then wants to find the package files. Where to get these is far from clear when on the main upgrade page.

On the main page - https://docs.graylog.org/docs/upgrade - there should be a clearly visible link to the repository for downloads. Eg. https://packages.graylog2.org/packages

  1. The per-version upgrade pages - for example https://docs.graylog.org/docs/graylog-4-1 - should independantly list the minimum + maximum compatible MongoDB and Elasticsearch version near the top of the page.

Also near the top of the page there should be a links to download the different formats of the package from https://packages.graylog2.org/packages

  1. If the minimum version of MongoDB or Elasticsearch changes with a given version, this should be explicitly noted on its per-version upgrade page. Ideally a link to instructions to upgrading to that version of MongoDB/Elasticsearch would also be present.

  2. We should include instructions to upgrade the Graylog Fowarder in here.

Page restructure suggestion

Currently the pages look like this:

-Upgrading Graylog -----Upgrading to Graylog 2.0.x -----Upgrading to Graylog 2.1.x -----Upgrading to Graylog 2.2.x -----Upgrading to Graylog 2.3.x -----Upgrading to Graylog 2.4.x -----Upgrading to Graylog 2.5.x -----Upgrading to Graylog 3.0.x -----Upgrading to Graylog 3.1.x -----Upgrading to Graylog 3.2.x -----Upgrading to Graylog 3.3.x -----Upgrading to Graylog 4.0.x -----Upgrading to Graylog 4.1.x -----Upgrading to Graylog 4.2.x -----Upgrading Elastisearch ----------Elasticsearch Reindexing Notes ----------Elasticsearch 6 Upgrade Notes ----------Elasticsearch 7 Upgrade Notes ----------Elasticsearch Rolling Upgrade Notes

With the changes above, I'd imagine they could look like this:

-Upgrading Graylog -----Upgrade Process ----------Operating System Packages ----------Chef, Puppet, Ansible ----------Docker ----------Manual upgrade ----------Ubuntu upgrade ----------Debian upgrade ----------SLES upgrade ----------CentOS upgrade -----Version-specific Install Notes ----------Upgrading to Graylog 2.0.x ----------Upgrading to Graylog 2.1.x ----------Upgrading to Graylog 2.2.x ----------Upgrading to Graylog 2.3.x ----------Upgrading to Graylog 2.4.x ----------Upgrading to Graylog 2.5.x ----------Upgrading to Graylog 3.0.x ----------Upgrading to Graylog 3.1.x ----------Upgrading to Graylog 3.2.x ----------Upgrading to Graylog 3.3.x ----------Upgrading to Graylog 4.0.x ----------Upgrading to Graylog 4.1.x ----------Upgrading to Graylog 4.2.x -----Upgrading Elastisearch ----------Elasticsearch Reindexing Notes ----------Elasticsearch 6 Upgrade Notes ----------Elasticsearch 7 Upgrade Notes ----------Elasticsearch Rolling Upgrade Notes -----Upgrading Graylog Fowarder

Upgrade-Related Enterprise Support tickets raised last quarter

To support the case that the weakness of this documentation is causing isssues, find below Enterprise Support tickets raised last quarter.

Asking for clarification on Upgrade process HS-619694232 HS-605250450 HS-602941526 HS-597603393 HS-591156617 HS-552915236 HS-533427879 HS-513532993 HS-504873473 HS-482228365 HS-474713750 HS-436350889 HS-375643938

Problems caused by Upgrade process HS-622241161 HS-610791768 HS-562198358 HS-546948651 HS-533469107 HS-520614040 HS-516255408 HS-471190529 HS-469703856 HS-462247199 HS-445682979 HS-411331702 HS-396324258

dulanism commented 2 years ago

Closing this issue, since