Skip to content

Commit bcaeabe

Browse files
theashiottheashiot
committed
OBSDOCS-1701: Upgrading to Logging 6 steps
1 parent b3bbfd4 commit bcaeabe

9 files changed

+650
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3035,6 +3035,8 @@ Topics:
30353035
File: log6x-release-notes-6.2
30363036
- Name: About logging 6.2
30373037
File: log6x-about-6.2
3038+
- Name: Updating logging
3039+
File: log6x-cluster-logging-upgrading-6.2
30383040
- Name: Installing Logging
30393041
File: 6x-cluster-logging-deploying-6.2
30403042
- Name: Configuring log forwarding

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

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-04-23
3+
:_mod-docs-content-type: CONCEPT
4+
5+
[id="changes-to-cluster-logging-and-forwarding_{context}"]
6+
= Changes to Cluster logging and forwarding
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+
== Management, resource allocation, and workload scheduling
16+
17+
Configuration for management state, resource requests and limits, tolerations, and node selection is now part of the new `ClusterLogForwarder` API.
18+
19+
.Logging 5.x configuration
20+
[source,yaml]
21+
----
22+
apiVersion: "logging.openshift.io/v1"
23+
kind: "ClusterLogging"
24+
spec:
25+
managementState: "Managed"
26+
collection:
27+
resources:
28+
limits: {}
29+
requests: {}
30+
nodeSelector: {}
31+
tolerations: {}
32+
----
33+
34+
.Logging 6 configuration
35+
[source,yaml]
36+
----
37+
apiVersion: "observability.openshift.io/v1"
38+
kind: ClusterLogForwarder
39+
spec:
40+
managementState: Managed
41+
collector:
42+
resources:
43+
limits: {}
44+
requests: {}
45+
nodeSelector: {}
46+
tolerations: {}
47+
----
48+
49+
== Input specifications
50+
51+
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.
52+
53+
=== Application Inputs
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+
=== Input receivers
102+
103+
Changes to input receivers include:
104+
105+
* Explicit configuration of the type at the receiver level.
106+
* Port settings moved to the receiver level.
107+
108+
.5.x input receivers
109+
[source,yaml]
110+
----
111+
apiVersion: "logging.openshift.io/v1"
112+
kind: ClusterLogForwarder
113+
spec:
114+
inputs:
115+
- name: an-http
116+
receiver:
117+
http:
118+
port: 8443
119+
format: kubeAPIAudit
120+
- name: a-syslog
121+
receiver:
122+
type: syslog
123+
syslog:
124+
port: 9442
125+
----
126+
127+
.6.x input receivers
128+
[source,yaml]
129+
----
130+
apiVersion: "observability.openshift.io/v1"
131+
kind: ClusterLogForwarder
132+
spec:
133+
inputs:
134+
- name: an-http
135+
type: receiver
136+
receiver:
137+
type: http
138+
port: 8443
139+
http:
140+
format: kubeAPIAudit
141+
- name: a-syslog
142+
type: receiver
143+
receiver:
144+
type: syslog
145+
port: 9442
146+
----
147+
148+
== Output specifications
149+
150+
High-level changes to output specifications include:
151+
152+
* URL settings moved to each output type specification.
153+
* Tuning parameters moved to each output type specification.
154+
* Separation of TLS configuration from authentication.
155+
* Explicit configuration of keys and secret/configmap for TLS and authentication.
156+
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. Examples in the following sections provide details on how to configure *ClusterLogForwarder* secrets to forward to existing Red Hat managed log storage solutions.
160+
161+
.Logging 6.x output using service accounu token
162+
[source,yaml]
163+
----
164+
...
165+
spec:
166+
outputs:
167+
- name: my-output
168+
type: http
169+
http:
170+
url: https://my-secure-output:8080
171+
authentication:
172+
token:
173+
from: serviceAccount
174+
tls:
175+
ca:
176+
key: service-ca.crt
177+
configMapName: openshift-service-ca.crt
178+
...
179+
----
180+
181+
.Logging 6.x output authentication and TLS example
182+
[source,yaml]
183+
----
184+
...
185+
spec:
186+
outputs:
187+
- name: my-output
188+
type: http
189+
http:
190+
url: https://my-secure-output:8080
191+
authentication:
192+
password:
193+
key: pass
194+
secretName: my-secret
195+
username:
196+
key: user
197+
secretName: my-secret
198+
tls:
199+
ca:
200+
key: ca-bundle.crt
201+
secretName: collector
202+
certificate:
203+
key: tls.crt
204+
secretName: collector
205+
key:
206+
key: tls.key
207+
secretName: collector
208+
...
209+
----
210+
211+
== Filters and pipeline configuration
212+
213+
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.
214+
215+
.5.x filters
216+
[source,yaml]
217+
----
218+
...
219+
spec:
220+
pipelines:
221+
- name: app-logs
222+
detectMultilineErrors: true
223+
parse: json
224+
labels:
225+
foo: bar
226+
...
227+
----
228+
229+
.6.x filters and pipelines spec
230+
[source,yaml]
231+
----
232+
...
233+
spec:
234+
filters:
235+
- name: my-multiline
236+
type: detectMultilineException
237+
- name: my-parse
238+
type: parse
239+
- name: my-labels
240+
type: openshiftLabels
241+
openshiftLabels:
242+
foo: bar
243+
pipelines:
244+
- name: app-logs
245+
filterRefs:
246+
- my-multiline
247+
- my-parse
248+
- my-labels
249+
...
250+
----
251+
252+
[NOTE]
253+
====
254+
`Drop`, `Prune`, and `KubeAPIAudit` filters remain unchanged.
255+
====
256+
257+
== Validation and status
258+
259+
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.
260+
261+
Instances of the `ClusterLogForwarder.observability.openshift.io` must satisfy the following conditions before the operator deploys the log collector:
262+
263+
* Resource Status Conditions: Authorized, Valid, Ready
264+
265+
* Spec Validations: Filters, Inputs, Outputs, Pipelines
266+
267+
All must evaluate to the status value of `True`.
268+
269+
270+
271+
////
272+
[role="_additional-resources"]
273+
.Additional resources
274+
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
275+
* xref:some-module_{context}[]
276+
////

‎modules/log6x-changes-to-log-storage.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-04-23
3+
:_mod-docs-content-type: CONCEPT
4+
5+
[id="changes-to-log-storage_{context}"]
6+
= Changes to Log Storage
7+
8+
The only managed log storage solution available in this release is a Lokistack, managed by the `loki-operator` Operator. This solution, previously available as the preferred alternative to the managed Elasticsearch offering, remains unchanged in its deployment process.
9+
10+
////
11+
[role="_additional-resources"]
12+
.Additional resources
13+
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
14+
* xref:some-module_{context}[]
15+
////

‎modules/log6x-changes-to-log-visualization.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:_newdoc-version: 2.18.4
2+
:_template-generated: 2025-04-23
3+
:_mod-docs-content-type: CONCEPT
4+
5+
[id="changes-to-log-visualization_{context}"]
6+
= Changes to Log Visualization
7+
8+
The OpenShift console UI plugin for log visualization has been moved to the `cluster-observability-operator` Operator from the `cluster-logging-operator` Operator.
9+
10+
////
11+
[role="_additional-resources"]
12+
.Additional resources
13+
* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
14+
* xref:some-module_{context}[]
15+
////

‎modules/log6x-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. This link text might be *stable* or *stable-{logging-version}*, depending on your current update channel.
26+
27+
. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-{logging-version}*, and click *Save*. Note the `cluster-logging.{logging-v}.<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.{logging-v}.<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/log6x-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-6.y*, depending on your current update channel.
26+
27+
. In the *Change Subscription Update Channel* window, select the latest major version update channel, *stable-5.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.v6.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".

0 commit comments

Comments
 (0)