Skip to content

Commit 863106d

Browse files
theashiottheashiot
committed
OBSDOCS-1701: Upgrading to Logging 6 steps standalone
1 parent 64e8d00 commit 863106d

13 files changed

+694
-467
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Name: Upgrading logging
4545
Dir: upgrading
4646
Distros: openshift-logging
4747
Topics:
48-
- Name: Upgrading to Logging 6.0
48+
- Name: Upgrading to Logging 6
4949
File: upgrading-to-logging-60
5050
---
5151
Name: Scheduling resources

‎modules/changes-to-cluster-logging-and-forwarding-in-logging-6.adoc‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-06-03
3+
:_mod-docs-content-type: CONCEPT
4+
5+
[id="changes-to-cluster-logging-and-forwarding-in-logging-6_{context}"]
6+
= Changes to cluster logging and forwarding in Logging 6
7+
8+
Log collection and forwarding configurations are now specified under the new link:https://github.com/openshift/cluster-logging-operator/blob/master/docs/reference/operator/api_observability_v1.adoc[API], part of the `observability.openshift.io` API group. The following sections highlight the differences from the old API resources.
9+
10+
[NOTE]
11+
====
12+
Vector is the only supported collector implementation.
13+
====
14+
15+
[id="management-resource-allocation-workload-scheduling_{context}"]
16+
== Management, resource allocation, and workload scheduling
17+
18+
Configuration for management state, resource requests and limits, tolerations, and node selection is now part of the new `ClusterLogForwarder` API.
19+
20+
.Logging 5.x configuration
21+
[source,yaml]
22+
----
23+
apiVersion: "logging.openshift.io/v1"
24+
kind: "ClusterLogging"
25+
spec:
26+
managementState: "Managed"
27+
collection:
28+
resources:
29+
limits: {}
30+
requests: {}
31+
nodeSelector: {}
32+
tolerations: {}
33+
----
34+
35+
.Logging 6 configuration
36+
[source,yaml]
37+
----
38+
apiVersion: "observability.openshift.io/v1"
39+
kind: ClusterLogForwarder
40+
spec:
41+
managementState: Managed
42+
collector:
43+
resources:
44+
limits: {}
45+
requests: {}
46+
nodeSelector: {}
47+
tolerations: {}
48+
----
49+
50+
[id="input-specification_{context}"]
51+
== Input specifications
52+
53+
The input specification is an optional part of the `ClusterLogForwarder` specification. Administrators can continue to use the predefined values `application`, `infrastructure`, and `audit` to collect these sources.
54+
55+
Namespace and container inclusions and exclusions have been consolidated into a single field.
56+
57+
.5.x application input with namespace and container includes and excludes
58+
[source,yaml]
59+
----
60+
apiVersion: "logging.openshift.io/v1"
61+
kind: ClusterLogForwarder
62+
spec:
63+
inputs:
64+
- name: application-logs
65+
type: application
66+
application:
67+
namespaces:
68+
- foo
69+
- bar
70+
includes:
71+
- namespace: my-important
72+
container: main
73+
excludes:
74+
- container: too-verbose
75+
----
76+
77+
.6.x application input with namespace and container includes and excludes
78+
[source,yaml]
79+
----
80+
apiVersion: "observability.openshift.io/v1"
81+
kind: ClusterLogForwarder
82+
spec:
83+
inputs:
84+
- name: application-logs
85+
type: application
86+
application:
87+
includes:
88+
- namespace: foo
89+
- namespace: bar
90+
- namespace: my-important
91+
container: main
92+
excludes:
93+
- container: too-verbose
94+
----
95+
96+
[NOTE]
97+
====
98+
"application", "infrastructure", and "audit" are reserved words and cannot be used as names when defining an input.
99+
====
100+
101+
Changes to input receivers include:
102+
103+
* Explicit configuration of the type at the receiver level.
104+
* Port settings moved to the receiver level.
105+
106+
.5.x input receivers
107+
[source,yaml]
108+
----
109+
apiVersion: "logging.openshift.io/v1"
110+
kind: ClusterLogForwarder
111+
spec:
112+
inputs:
113+
- name: an-http
114+
receiver:
115+
http:
116+
port: 8443
117+
format: kubeAPIAudit
118+
- name: a-syslog
119+
receiver:
120+
type: syslog
121+
syslog:
122+
port: 9442
123+
----
124+
125+
.6.x input receivers
126+
[source,yaml]
127+
----
128+
apiVersion: "observability.openshift.io/v1"
129+
kind: ClusterLogForwarder
130+
spec:
131+
inputs:
132+
- name: an-http
133+
type: receiver
134+
receiver:
135+
type: http
136+
port: 8443
137+
http:
138+
format: kubeAPIAudit
139+
- name: a-syslog
140+
type: receiver
141+
receiver:
142+
type: syslog
143+
port: 9442
144+
----
145+
146+
[id="output-specification_{context}"]
147+
== Output specifications
148+
149+
High-level changes to output specifications include:
150+
151+
* URL settings moved to each output type specification.
152+
* Tuning parameters moved to each output type specification.
153+
* Separation of TLS configuration from authentication.
154+
* Explicit configuration of keys and secret/config map for TLS and authentication.
155+
156+
[id="secrets-and-tls-configuration_{context}"]
157+
== Secrets and TLS configuration
158+
159+
Secrets and TLS configurations are now separated into authentication and TLS configuration for each output. They must be explicitly defined in the specification rather than relying on administrators to define secrets with recognized keys. Upgrading TLS and authorization configurations requires administrators to understand previously recognized keys to continue using existing secrets. The examples in this section illustrate how to configure `ClusterLogForwarder` secrets to forward to existing Red{nbsp}Hat managed log storage solutions.
160+
161+
.Logging 6.x output configuration using service account token and config map
162+
[source,yaml]
163+
----
164+
...
165+
spec:
166+
outputs:
167+
- lokiStack
168+
authentication:
169+
token:
170+
from: serviceAccount
171+
target:
172+
name: logging-loki
173+
namespace: openshift-logging
174+
name: my-lokistack
175+
tls:
176+
ca:
177+
configMapName: openshift-service-ca.crt
178+
key: service-ca.crt
179+
type: lokiStack
180+
...
181+
----
182+
183+
.Logging 6.x output authentication and TLS configuration using secrets
184+
[source,yaml]
185+
----
186+
...
187+
spec:
188+
outputs:
189+
- name: my-output
190+
type: http
191+
http:
192+
url: https://my-secure-output:8080
193+
authentication:
194+
password:
195+
key: pass
196+
secretName: my-secret
197+
username:
198+
key: user
199+
secretName: my-secret
200+
tls:
201+
ca:
202+
key: ca-bundle.crt
203+
secretName: collector
204+
certificate:
205+
key: tls.crt
206+
secretName: collector
207+
key:
208+
key: tls.key
209+
secretName: collector
210+
...
211+
----
212+
213+
[id="filters-and-pipeline-configuration_{context}"]
214+
== Filters and pipeline configuration
215+
216+
All attributes of pipelines in previous releases have been converted to filters in this release. Individual filters are defined in the `filters` spec and referenced by a pipeline.
217+
218+
.5.x filters
219+
[source,yaml]
220+
----
221+
...
222+
spec:
223+
pipelines:
224+
- name: app-logs
225+
detectMultilineErrors: true
226+
parse: json
227+
labels:
228+
<key>: <value>
229+
...
230+
----
231+
232+
.6.x filters and pipelines spec
233+
[source,yaml]
234+
----
235+
...
236+
spec:
237+
filters:
238+
- name: my-multiline
239+
type: detectMultilineException
240+
- name: my-parse
241+
type: parse
242+
- name: my-labels
243+
type: openshiftLabels
244+
openshiftLabels:
245+
<key>: <label>
246+
pipelines:
247+
- name: app-logs
248+
filterRefs:
249+
- my-multiline
250+
- my-parse
251+
- my-labels
252+
...
253+
----
254+
255+
[NOTE]
256+
====
257+
`Drop`, `Prune`, and `KubeAPIAudit` filters remain unchanged.
258+
====
259+
260+
== Validation and status
261+
262+
Most validations are now enforced when a resource is created or updated which provides immediate feedback. This is a departure from previous releases where all validation occurred post creation requiring inspection of the resource status location. Some validation still occurs post resource creation for cases where is not possible to do so at creation or update time.
263+
264+
Instances of the `ClusterLogForwarder.observability.openshift.io` resource must satisfy the following conditions before the operator deploys the log collector:
265+
266+
* Resource status conditions: Authorized, Valid, Ready
267+
268+
* Spec validations: Filters, Inputs, Outputs, Pipelines
269+
270+
All must evaluate to the status value of `True`.

‎modules/deleting-red-hat-log-visualization.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-06-03
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, 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+
16+
* Delete the logging view plugin by running the following command:
17+
+
18+
[source,terminal]
19+
----
20+
$ oc get consoleplugins logging-view-plugin && oc delete consoleplugins logging-view-plugin
21+
----

‎modules/deleting-red-hat-openshift-logging-5-crd.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-06-03
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+
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+
----

‎modules/deleting-the-clusterlogging-instance.adoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-06-03
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+
. Verify that no collector pods are running by running the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc get pods -l component=collector -n <namespace>
28+
----
29+
30+
. Verify that no `clusterLogForwarder.logging.openshift.io` custom resource (CR) exists by running the following command:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc get clusterlogforwarders.logging.openshift.io -A
35+
----
36+
37+
[IMPORTANT]
38+
=====
39+
If any `clusterLogForwarder.logging.openshift.io` CR is listed, it belongs to the old 5.x Logging stack, and must be removed. Create a backup of the CRs and delete them before deploying any `clusterLogForwarder.observability.openshift.io` CR with the new APIversion.
40+
=====

0 commit comments

Comments
 (0)