Merge pull request #85726 from max-cx/OBSDOCS-1126

OBSDOCS-1126: LokistackSchemaUpgradesRequired in the upgrade process to Logging 5.9

Author: bergerhoffer

modules/logging-loki-cli-install.adoc

@@ -160,8 +160,8 @@ spec:
   size: 1x.small # <3>
   storage:
     schemas:
-    - version: v12
-      effectiveDate: "2022-06-01"
+    - version: v13
+      effectiveDate: "<yyyy>-<mm>-<dd>"
     secret:
       name: logging-loki-s3 # <4>
       type: s3 # <5>

modules/logging-loki-gui-install.adoc

@@ -86,8 +86,8 @@ spec:
   size: 1x.small # <3>
   storage:
     schemas:
-    - version: v12
-      effectiveDate: "2022-06-01"
+    - version: v13
+      effectiveDate: "<yyyy>-<mm>-<dd>"
     secret:
       name: logging-loki-s3 # <4>
       type: s3 # <5>

modules/logging-upgrading-clo.adoc

@@ -22,12 +22,12 @@ To update the {clo} to a new major release version, you must modify the update c
 
 . Click the *Red Hat OpenShift Logging* Operator.
 
-. Click *Subscription*. In the *Subscription details* section, click the *Update channel* link. This link text might be *stable* or *stable-5.y*, depending on your current update channel.
+. Click *Subscription*. In the *Subscription details* section, click the *Update channel* link. This link text might be *stable* or *stable-5.9*, depending on your current update channel.
 
-. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-5.y*, and click *Save*. Note the `cluster-logging.v5.y.z` version.
+. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-5.9*, and click *Save*. Note the `cluster-logging.v5.9.<z>` version.
 
-.Verification
-
-. Wait for a few seconds, then click *Operators* -> *Installed Operators*. Verify that the {clo} version matches the latest `cluster-logging.v5.y.z` version.
+. Wait for a few seconds, and then go to *Operators* -> *Installed Operators* to verify that the {clo} version matches the latest `cluster-logging.v5.9.<z>` version.
 
 . On the *Operators* -> *Installed Operators* page, wait for the *Status* field to report *Succeeded*.
+
+. Check if the `LokiStack` custom resource contains the `v13` schema version and add it if it is missing. For correctly adding the `v13` schema version, see "Upgrading the LokiStack storage schema".

modules/logging-upgrading-loki-schema.adoc

@@ -0,0 +1,45 @@
+// Module included in the following assemblies:
+//
+// * observability/logging/cluster-logging-upgrading.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="logging-upgrading-loki-schema_{context}"]
+= Upgrading the LokiStack storage schema
+
+If you are using the {clo} with the {loki-op}, the {clo} 5.9 or later supports the `v13` schema version in the `LokiStack` custom resource. Upgrading to the `v13` schema version is recommended because it is the schema version to be supported going forward.
+
+.Procedure
+
+* Add the `v13` schema version in the `LokiStack` custom resource as follows:
++
+[source,yaml]
+----
+apiVersion: loki.grafana.com/v1
+kind: LokiStack
+# ...
+spec:
+# ...
+  storage:
+    schemas:
+    # ...
+      version: v12 # <1>
+    - effectiveDate: "<yyyy>-<mm>-<future_dd>" # <2>
+      version: v13
+# ...
+----
+<1> Do not delete. Data persists in its original schema version. Keep the previous schema versions to avoid data loss.
+<2> Set a future date that has not yet started in the Coordinated Universal Time (UTC) time zone.
++
+[TIP]
+====
+To edit the `LokiStack` custom resource, you can run the `oc edit` command:
+
+[source,terminal]
+----
+$ oc edit lokistack <name> -n openshift-logging
+----
+====
+
+.Verification
+
+* On or after the specified `effectiveDate` date, check that there is no *LokistackSchemaUpgradesRequired* alert in the web console in *Administrator* -> *Observe* -> *Alerting*.

modules/logging-upgrading-loki.adoc

@@ -26,8 +26,8 @@ To update the {loki-op} to a new major release version, you must modify the upda
 
 . In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-5.y*, and click *Save*. Note the `loki-operator.v5.y.z` version.
 
-.Verification
-
 . Wait for a few seconds, then click *Operators* -> *Installed Operators*. Verify that the {loki-op} version matches the latest `loki-operator.v5.y.z` version.
 
 . On the *Operators* -> *Installed Operators* page, wait for the *Status* field to report *Succeeded*.
+
+. Check if the `LokiStack` custom resource contains the `v13` schema version and add it if it is missing. For correctly adding the `v13` schema version, see "Upgrading the LokiStack storage schema".

observability/logging/cluster-logging-upgrading.adoc

@@ -28,4 +28,6 @@ include::modules/logging-upgrading-clo.adoc[leveloffset=+1]
 
 include::modules/logging-upgrading-loki.adoc[leveloffset=+1]
 
+include::modules/logging-upgrading-loki-schema.adoc[leveloffset=+1]
+
 include::modules/cluster-logging-upgrading-elasticsearch.adoc[leveloffset=+1]