URL:

Upgrading to Logging 6

Description

ISSUE 1
=======
The "Upgrading to Logging 6.0" tries to describe how to transition from Logging 5.y to Logging 6. This transition from Logging 5.y to Logging 6 has not a mandatory path like 5.8 > 5.9 > 6.0 > 6.1 > 6.2. Then, it's possible to follow 5.8 > 6.1 or 5.9 > 6.2.

Checking this validation path where it's not mandatory to go through 6.0, the "Upgrading to Logging 6.0" shouldn't be a section inside the "Logging 6.0" only and the title could be "Upgrading to Logging 6" instead of being "Upgrading to Logging 6.0".

A possible option could be to have a section for "upgrading from Logging 5 to Logging 6" out of Logging 6.0, 6.1, 6.2...

ISSUE 2
=======
It's missed a logical order of steps to be followed for upgrading from Logging 5 to Logging 6 where they could be something like below (some of the steps could have a different order, but Red Hat should recommend one)

1. Migrate the storage from Elasticsearch to Loki if it's used the Red Hat Managed Log storage if it was not done before
2. Upgrade the Cluster Logging Operator to Logging 6 (not clear if it should be upgraded or really uninstalled)
3. Create the clusterLogForwarder resource using the Logging 6 API
4. Delete the collectors using the Cluster Logging 5 API
5. Delete the CRD "ClusterLogging.logging.openshift.io" and "clusterLogForwarder.logging.openshift.io
6. Uninstall the Elasticsearch Operator if not longer used for other components as Service Mesh, Jaeger, etc as detailed in Uninstalling Elasticsearch deleting also the CRD "elasticsearches.logging.openshift.io" and "kibanas.logging.openshift.io"
7. Deletion of the legacy serviceAccount logcollector is not reused in Logging 6
8. Delete the ConsolePlugin before installing the UIPlugin
9. Install the COO UI Plugin
10. Uninstall the Elasticsearch Operator is not used for Service Mesh, Jaeger, Kiali, etc
 

ISSUE 3
======
The most of the sections in "Upgrading to Logging 6.0" are not probably something related to the Upgrade itself, an example is the section "Using the oc explain command".

It seems that it's tried in the current "Upgrading to Logging 6.0" two things:

• Show differences between how the configuration was in Logging 5 and how it's Logging 6, but it's not clear in the documentation
• Some isolated steps not sorted for upgrading and missing others steps

EXPECTED
It should be expected when reading the "Upgrading to Logging 6.0" section:

• Differences between Logging 5 and Logging 6 for recreating the ClusterLogForwarder resource
• Sorted steps for Upgrading. An example of this is the article: "How to transition the collectors and the default log store from Red Hat OpenShift Logging 5 to 6 " for the collectors

 
IMPACT

Currently, it's not possible to do the upgrade from Logging 5 to Logging 6 without the intervention of Red Hat Support as not clear steps and explanations of the steps needed. All the OpenShift Admins opening support cases for this transition are redirected to the article "How to transition the collectors and the default log store from Red Hat OpenShift Logging 5 to 6" that tries to remediate the missing documentation  

A second impact observed when upgrading from Logging 5 to Logging 6 is that even if in both the collector type is Vector, the path to the Vector checkpoints is changed and the impact is the same that the described in https://issues.redhat.com/browse/OBSDA-540 . Then, a big disclaimer about this behaviour should exist and also, steps for workarounding the impact as it's possible to move the checkpoints to the definitive location.

DISCLAIMER
Even, if it's used Vector in Logging v5, when upgrading to v6, the checkpoints are moved to a different path having a big impact in different levels. It's the same impact reported when migrating from Fluentd to Vector in https://issues.redhat.com/browse/OBSDA-540. Then or:

• It's added a disclaimer indicating the impact
• or it should be provided the steps for moving the Vector checkpoints path