Skip to content

Commit 256d9ab

Browse files
theashiottheashiot
committed
OBSDOCS-1701: Upgrading to Logging 6 steps Final
1 parent b72eacf commit 256d9ab

10 files changed

+384
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3045,6 +3045,8 @@ Topics:
30453045
File: log6x-configuring-lokistack-otlp-6.2
30463046
- Name: Visualization for logging
30473047
File: log6x-visual-6.2
3048+
- Name: Updating Logging
3049+
File: cluster-logging-upgrading
30483050
- Name: Logging 6.1
30493051
Dir: logging-6.1
30503052
Topics:

‎modules/log-upgrade/6x-logging-upgrading-clo.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/cluster-logging-upgrading.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="logging-upgrading-clo_{context}"]
7+
= Updating the {clo}
8+
9+
To update the {clo} to a new major release version, you must modify the update channel for the Operator subscription.
10+
11+
.Prerequisites
12+
13+
* You have installed the {clo}.
14+
* You have administrator permissions.
15+
* You have access to the {product-title} web console and are viewing the *Administrator* perspective.
16+
17+
.Procedure
18+
19+
. Navigate to *Operators* -> *Installed Operators*.
20+
21+
. Select the *openshift-logging* project.
22+
23+
. Click the *Red Hat OpenShift Logging* Operator.
24+
25+
. Click *Subscription*. In the *Subscription details* section, click the *Update channel* link.
26+
27+
. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-6.x*, and click *Save*. Note the `cluster-logging.v6.y.z` version.
28+
29+
. 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.
30+
31+
. On the *Operators* -> *Installed Operators* page, wait for the *Status* field to report *Succeeded*.
32+
33+
. 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/log-upgrade/6x-logging-upgrading-loki.adoc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/cluster-logging-upgrading.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="logging-upgrading-loki_{context}"]
7+
= Updating the {loki-op}
8+
9+
To update the {loki-op} to a new major release version, you must modify the update channel for the Operator subscription.
10+
11+
.Prerequisites
12+
13+
* You have installed the {loki-op}.
14+
* You have administrator permissions.
15+
* You have access to the {product-title} web console and are viewing the *Administrator* perspective.
16+
17+
.Procedure
18+
19+
. Navigate to *Operators* -> *Installed Operators*.
20+
21+
. Select the *openshift-operators-redhat* project.
22+
23+
. Click the *{loki-op}*.
24+
25+
. 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.
26+
27+
. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-6.y*, and click *Save*. Note the `loki-operator.v6.y.z` version.
28+
29+
. 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.
30+
31+
. On the *Operators* -> *Installed Operators* page, wait for the *Status* field to report *Succeeded*.
32+
33+
. 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/log-upgrade/6x-uninstall-es-operator.adoc

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/cluster-logging-uninstall.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="uninstall-es-operator_{context}"]
7+
= Uninstalling Elasticsearch
8+
9+
You can unintall Elasticsearch by using the {product-title} web console.
10+
11+
.Prerequisites
12+
13+
* You have administrator permissions.
14+
* You have access to the *Administrator* perspective of the {product-title} web console.
15+
* If you have not already removed the {clo} and related resources, you must remove references to Elasticsearch from the `ClusterLogging` custom resource.
16+
17+
.Procedure
18+
19+
. Go to the *Administration* -> *Custom Resource Definitions* page, and click *Elasticsearch*.
20+
21+
. On the *Custom Resource Definition Details* page, click *Instances*.
22+
23+
. Click the Options menu {kebab} next to the instance, and then click *Delete Elasticsearch*.
24+
25+
. Go to the *Administration* -> *Custom Resource Definitions* page.
26+
27+
. Click the Options menu {kebab} next to *Elasticsearch*, and select *Delete Custom Resource Definition*.
28+
29+
. Delete the object storage secret.
30+
31+
. Go to the *Operators* -> *Installed Operators* page.
32+
33+
. Click the Options menu {kebab} next to the {es-op}, and then click *Uninstall Operator*.
34+
35+
. Optional: Delete the `openshift-operators-redhat` project.
36+
+
37+
[IMPORTANT]
38+
====
39+
Do not delete the `openshift-operators-redhat` project if other global Operators are installed in this namespace.
40+
====
41+
42+
.. Go to the *Home* -> *Projects* page.
43+
.. Click the Options menu {kebab} next to the *openshift-operators-redhat* project, and then click *Delete Project*.
44+
.. Confirm the deletion by typing `openshift-operators-redhat` in the dialog box, and then click *Delete*.

‎modules/log-upgrade/6x_creating-and-configuring-a-service-account-for-the-log-collector.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-05-20
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="creating-and-configuring-a-service-account-for-the-log-collector_{context}"]
6+
= Creating and configuring a service account for the log collector
7+
8+
Create a service account for the log collector and assign it the necessary roles and permissions to collect logs.
9+
10+
.Prerequisites
11+
12+
.Procedure
13+
14+
. Create a service account to be used by the log collector:
15+
+
16+
[source,terminal]
17+
----
18+
$ oc create sa logging-collector -n openshift-logging
19+
----
20+
21+
. Bind the `Cluster Role` role to the service account to be able to write the logs to the Red{nbsp}Hat LokiStack
22+
+
23+
[source,terminal]
24+
----
25+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z logging-collector -n openshift-logging
26+
----
27+
28+
. Assign the necessary permissions to the service account for the collector to be able to collect and forward logs.
29+
30+
.. Assign permission to collect and forward application logs by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z logging-collector -n openshift-logging
35+
----
36+
37+
.. Assign permission to collect and forward audit logs by running the following command:
38+
+
39+
[source,terminal]
40+
----
41+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z logging-collector -n openshift-logging
42+
----
43+
44+
.. Assign permission to collect and forward infrastructure logs by running the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-log
49+
s -z logging-collector -n openshift-logging
50+
----
51+
52+
////
53+
54+
.Verification
55+
[role="_additional-resources"]
56+
.Additional resources
57+
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
58+
* xref:some-module_{context}[]
59+
////

‎modules/log-upgrade/6x_deleting-red-hat-log-visualization.adoc

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-05-20
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="deleting-red-hat-log-visualization_{context}"]
6+
= Deleting Red{nbsp}Hat Log Visualization
7+
8+
When updating from Logging 5 to Logging 6, you must delete Red{nbsp}Hat Log Visualization before installing the UIPlugin.
9+
10+
.Prerequisites
11+
* You have administrator permissions.
12+
* You installed the {oc-first}.
13+
14+
.Procedure
15+
. Make each step an instruction.
16+
17+
.Verification
18+
Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
19+
20+
* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
21+
* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
22+
* Make each step an instruction.
23+
* Use an unnumbered bullet (*) if the verification includes only one step.
24+
25+
.Troubleshooting
26+
Delete this section if it does not apply to your module. Provide the user with troubleshooting steps.
27+
28+
* Make each step an instruction.
29+
* Use an unnumbered bullet (*) if the troubleshooting includes only one step.
30+
31+
.Next steps
32+
* Delete this section if it does not apply to your module.
33+
* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
34+
* Use an unnumbered bullet (*) if the list includes only one step.
35+
36+
NOTE: Do not use *Next steps* to provide a second list of instructions.
37+
38+
[role="_additional-resources"]
39+
.Additional resources
40+
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
41+
* xref:some-module_{context}[]
42+

‎modules/log-upgrade/6x_deleting-red-hat-openshift-logging-5-crds.adoc

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-05-20
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="deleting-red-hat-openshift-logging-5-crds_{context}"]
6+
= Deleting Red{nbsp}Hat OpenShift Logging 5 CRD
7+
8+
You must delete Red{nbsp}Hat OpenShift Logging 5 custom resource definitions (CRD), when upgrading to Logging 6.
9+
10+
11+
.Prerequisites
12+
* You have administrator permissions.
13+
* You installed the {oc-first}.
14+
15+
.Procedure
16+
* Delete `clusterlogforwarders.logging.openshift.io` and `clusterloggings.logging.openshift.io` CRD by running the following command:
17+
+
18+
[source,terminal]
19+
----
20+
$ oc delete crd clusterloggings.logging.openshift.io clusterlogforwarders.logging.openshift.io
21+
----
22+
23+
////
24+
.Verification
25+
////
26+

‎modules/log-upgrade/6x_deleting-the-clusterlogging-instance.adoc

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-05-20
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="deleting-the-clusterlogging-instance_{context}"]
6+
= Deleting the ClusterLogging instance
7+
8+
Delete the ClusterLogging instance because it is no longer needed in Logging 6.x.
9+
10+
.Prerequisites
11+
* You have administrator permissions.
12+
* You installed the {oc-first}.
13+
14+
.Procedure
15+
* Delete the ClusterLogging instance.
16+
+
17+
[source,terminal]
18+
----
19+
$ oc delete clusterlogging <CR name> -n <namespace>
20+
----
21+
22+
.Verification
23+
24+
. Verify that no collector pods are running by running the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ oc get pods -l component=collector -n <namespace>
29+
----
30+
31+
. Verify that no Check that no `clusterLogForwarder.logging.openshift.io` custom resource (CR) exists by running the following command:
32+
+
33+
[source,terminal]
34+
----
35+
$ oc get pods -l component=collector -n <namespace>
36+
----
37+
38+
[IMPORTANT]
39+
=====
40+
If any `clusterLogForwarder.logging.openshift.io` is listed, it belongs to the old 5.x Logging stack, and must be removed. Create a back up if the CRs and delete them before deploying any `clusterLogForwarder.observability.openshift.io` CR with the new APIversion.
41+
=====

‎modules/log-upgrade/6x_deploying-a-clusterlogforwarder-observability-custom-resource.adoc

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-05-20
3+
:_mod-docs-content-type: PROCEDURE
4+
5+
[id="deploying-a-clusterlogforwarder-observability-custom-resource_{context}"]
6+
= Deploying a ClusterLogForwarder observability custom resource
7+
8+
Deploying a ClusterLogForwarder observability custom resource (CR) by using the {oc-first} command.
9+
10+
.Prerequisites
11+
* You have administrator permissions.
12+
* You installed the {oc-first}.
13+
14+
.Procedure
15+
. Create a ClusterLogForwarder observability custom resource (CR).
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: observability.openshift.io/v1
20+
kind: ClusterLogForwarder
21+
metadata:
22+
name: collector
23+
namespace: openshift-logging
24+
spec:
25+
serviceAccount:
26+
name: collector
27+
outputs:
28+
- name: default-lokistack
29+
type: lokiStack
30+
lokiStack:
31+
target:
32+
name: <Name_of_LokiStack>
33+
namespace: openshift-logging
34+
authentication:
35+
token:
36+
from: serviceAccount
37+
tls:
38+
ca:
39+
key: service-ca.crt
40+
configMapName: openshift-service-ca.crt
41+
pipelines:
42+
- name: default-logstore
43+
inputRefs:
44+
- application
45+
- infrastructure
46+
outputRefs:
47+
- default-lokistack
48+
----
49+
50+
. Deply the CR by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
oc create -f <file_name>.yaml
55+
----
56+
57+
////
58+
.Verification
59+
Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
60+
61+
* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
62+
* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
63+
* Make each step an instruction.
64+
* Use an unnumbered bullet (*) if the verification includes only one step.
65+
66+
////

0 commit comments

Comments
 (0)