Skip to content

Commit 686db1b

Browse files
gabriel-rhgabriel-rh
authored
Merge pull request #92351 from gabriel-rh/standalone-logging-logx-about
migrate logx about content, with modules and snippets
2 parents 344b906 + 3086991 commit 686db1b

File tree

5 files changed

+383
-0
lines changed

5 files changed

+383
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,5 @@ Distros: openshift-logging
55
Topics:
66
- Name: OpenShift Logging overview
77
File: about-logging
8+
- Name: Logging
9+
File: log6x-about

‎about/log6x-about.adoc‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
include::_attributes/common-attributes.adoc[]
3+
[id="log6x-about-6-1"]
4+
= Logging 6.1
5+
:context: logging-6x-6.1
6+
7+
toc::[]
8+
9+
The `ClusterLogForwarder` custom resource (CR) is the central configuration point for log collection and forwarding.
10+
11+
[id="inputs-and-outputs_6-1_{context}"]
12+
== Inputs and outputs
13+
14+
Inputs specify the sources of logs to be forwarded. Logging provides the following built-in input types that select logs from different parts of your cluster:
15+
16+
* `application`
17+
* `receiver`
18+
* `infrastructure`
19+
* `audit`
20+
21+
You can also define custom inputs based on namespaces or pod labels to fine-tune log selection.
22+
23+
Outputs define the destinations where logs are sent. Each output type has its own set of configuration options, allowing you to customize the behavior and authentication settings.
24+
25+
[id="receiver-input-type_6-1_{context}"]
26+
== Receiver input type
27+
The receiver input type enables the Logging system to accept logs from external sources. It supports two formats for receiving logs: `http` and `syslog`.
28+
29+
The `ReceiverSpec` field defines the configuration for a receiver input.
30+
31+
[id="pipelines-and-filters_6-1_{context}"]
32+
== Pipelines and filters
33+
34+
Pipelines determine the flow of logs from inputs to outputs. A pipeline consists of one or more input refs, output refs, and optional filter refs. You can use filters to transform or drop log messages within a pipeline. The order of filters matters, as they are applied sequentially, and earlier filters can prevent log messages from reaching later stages.
35+
36+
[id="operator-behavior_6-1_{context}"]
37+
== Operator behavior
38+
39+
The Cluster Logging Operator manages the deployment and configuration of the collector based on the `managementState` field of the `ClusterLogForwarder` resource:
40+
41+
- When set to `Managed` (default), the Operator actively manages the logging resources to match the configuration defined in the spec.
42+
- When set to `Unmanaged`, the Operator does not take any action, allowing you to manually manage the logging components.
43+
44+
[id="validation_6-1_{context}"]
45+
== Validation
46+
Logging includes extensive validation rules and default values to ensure a smooth and error-free configuration experience. The `ClusterLogForwarder` resource enforces validation checks on required fields, dependencies between fields, and the format of input values. Default values are provided for certain fields, reducing the need for explicit configuration in common scenarios.
47+
48+
[id="quick-start_6-1_{context}"]
49+
== Quick start
50+
51+
OpenShift Logging supports two data models:
52+
53+
* ViaQ (General Availability)
54+
* OpenTelemetry (Technology Preview)
55+
56+
You can select either of these data models based on your requirement by configuring the `lokiStack.dataModel` field in the `ClusterLogForwarder`. ViaQ is the default data model when forwarding logs to LokiStack.
57+
58+
[NOTE]
59+
====
60+
In future releases of OpenShift Logging, the default data model will change from ViaQ to OpenTelemetry.
61+
====
62+
63+
include::modules/log6x-quickstart-viaq.adoc[leveloffset=+2]
64+
65+
include::modules/log6x-quickstart-opentelemetry.adoc[leveloffset=+2]

‎modules/log6x-quickstart-opentelemetry.adoc‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/logging-6.0/log6x-about.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="quick-start-opentelemetry_{context}"]
7+
= Quick start with OpenTelemetry
8+
9+
:FeatureName: The OpenTelemetry Protocol (OTLP) output log forwarder
10+
include::snippets/technology-preview.adoc[]
11+
12+
To configure OTLP ingestion and enable the OpenTelemetry data model, follow these steps:
13+
14+
.Prerequisites
15+
* Cluster administrator permissions
16+
17+
.Procedure
18+
19+
. Install the {clo}, {loki-op}, and {coo-first} from OperatorHub.
20+
21+
. Create a `LokiStack` custom resource (CR) in the `openshift-logging` namespace:
22+
+
23+
[source,yaml]
24+
----
25+
apiVersion: loki.grafana.com/v1
26+
kind: LokiStack
27+
metadata:
28+
name: logging-loki
29+
namespace: openshift-logging
30+
spec:
31+
managementState: Managed
32+
size: 1x.extra-small
33+
storage:
34+
schemas:
35+
- effectiveDate: '2024-10-01'
36+
version: v13
37+
secret:
38+
name: logging-loki-s3
39+
type: s3
40+
storageClassName: gp3-csi
41+
tenants:
42+
mode: openshift-logging
43+
----
44+
+
45+
[NOTE]
46+
====
47+
Ensure that the `logging-loki-s3` secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see "Secrets and TLS Configuration".
48+
====
49+
50+
. Create a service account for the collector:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc create sa collector -n openshift-logging
55+
----
56+
57+
. Allow the collector's service account to write data to the `LokiStack` CR:
58+
+
59+
[source,terminal]
60+
----
61+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector
62+
----
63+
+
64+
[NOTE]
65+
====
66+
The `ClusterRole` resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.
67+
====
68+
69+
. Allow the collector's service account to collect logs:
70+
+
71+
[source,terminal]
72+
----
73+
$ oc project openshift-logging
74+
----
75+
+
76+
[source,terminal]
77+
----
78+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z collector
79+
----
80+
+
81+
[source,terminal]
82+
----
83+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector
84+
----
85+
+
86+
[source,terminal]
87+
----
88+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector
89+
----
90+
+
91+
[NOTE]
92+
====
93+
The example binds the collector to all three roles (application, infrastructure, and audit). By default, only application and infrastructure logs are collected. To collect audit logs, update your `ClusterLogForwarder` configuration to include them. Assign roles based on the specific log types required for your environment.
94+
====
95+
96+
. Create a `UIPlugin` CR to enable the *Log* section in the *Observe* tab:
97+
+
98+
[source,yaml]
99+
----
100+
apiVersion: observability.openshift.io/v1alpha1
101+
kind: UIPlugin
102+
metadata:
103+
name: logging
104+
spec:
105+
type: Logging
106+
logging:
107+
lokiStack:
108+
name: logging-loki
109+
----
110+
111+
. Create a `ClusterLogForwarder` CR to configure log forwarding:
112+
+
113+
[source,yaml]
114+
----
115+
apiVersion: observability.openshift.io/v1
116+
kind: ClusterLogForwarder
117+
metadata:
118+
name: collector
119+
namespace: openshift-logging
120+
annotations:
121+
observability.openshift.io/tech-preview-otlp-output: "enabled" # <1>
122+
spec:
123+
serviceAccount:
124+
name: collector
125+
outputs:
126+
- name: loki-otlp
127+
type: lokiStack # <2>
128+
lokiStack:
129+
target:
130+
name: logging-loki
131+
namespace: openshift-logging
132+
dataModel: Otel # <3>
133+
authentication:
134+
token:
135+
from: serviceAccount
136+
tls:
137+
ca:
138+
key: service-ca.crt
139+
configMapName: openshift-service-ca.crt
140+
pipelines:
141+
- name: my-pipeline
142+
inputRefs:
143+
- application
144+
- infrastructure
145+
outputRefs:
146+
- loki-otlp
147+
----
148+
<1> Use the annotation to enable the `Otel` data model, which is a Technology Preview feature.
149+
<2> Define the output type as `lokiStack`.
150+
<3> Specifies the OpenTelemetry data model.
151+
+
152+
[NOTE]
153+
====
154+
You cannot use `lokiStack.labelKeys` when `dataModel` is `Otel`. To achieve similar functionality when `dataModel` is `Otel`, refer to "Configuring LokiStack for OTLP data ingestion".
155+
====
156+
157+
.Verification
158+
* Verify that OTLP is functioning correctly by going to *Observe* -> *OpenShift Logging* -> *LokiStack* -> *Writes* in the OpenShift web console, and checking *Distributor - Structured Metadata*.

‎modules/log6x-quickstart-viaq.adoc‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * observability/logging/logging-6.0/log6x-about.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="quick-start-viaq_{context}"]
7+
= Quick start with ViaQ
8+
9+
To use the default ViaQ data model, follow these steps:
10+
11+
.Prerequisites
12+
* You have access to an {product-title} cluster with `cluster-admin` permissions.
13+
* You installed the {oc-first}.
14+
* You have access to a supported object store. For example, AWS S3, Google Cloud Storage, {azure-short}, Swift, Minio, or {rh-storage}.
15+
16+
.Procedure
17+
18+
. Install the `{clo}`, `{loki-op}`, and `{coo-first}` from OperatorHub.
19+
20+
. Create a `LokiStack` custom resource (CR) in the `openshift-logging` namespace:
21+
+
22+
[source,yaml]
23+
----
24+
apiVersion: loki.grafana.com/v1
25+
kind: LokiStack
26+
metadata:
27+
name: logging-loki
28+
namespace: openshift-logging
29+
spec:
30+
managementState: Managed
31+
size: 1x.extra-small
32+
storage:
33+
schemas:
34+
- effectiveDate: '2024-10-01'
35+
version: v13
36+
secret:
37+
name: logging-loki-s3
38+
type: s3
39+
storageClassName: gp3-csi
40+
tenants:
41+
mode: openshift-logging
42+
----
43+
+
44+
[NOTE]
45+
====
46+
Ensure that the `logging-loki-s3` secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see Secrets and TLS Configuration.
47+
====
48+
49+
. Create a service account for the collector:
50+
+
51+
[source,terminal]
52+
----
53+
$ oc create sa collector -n openshift-logging
54+
----
55+
56+
. Allow the collector's service account to write data to the `LokiStack` CR:
57+
+
58+
[source,terminal]
59+
----
60+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector -n openshift-logging
61+
----
62+
+
63+
[NOTE]
64+
====
65+
The `ClusterRole` resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.
66+
====
67+
68+
. To collect logs, use the service account of the collector by running the following commands:
69+
+
70+
[source,terminal]
71+
----
72+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z collector -n openshift-logging
73+
----
74+
+
75+
[source,terminal]
76+
----
77+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector -n openshift-logging
78+
----
79+
+
80+
[source,terminal]
81+
----
82+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector -n openshift-logging
83+
----
84+
+
85+
[NOTE]
86+
====
87+
The example binds the collector to all three roles (application, infrastructure, and audit), but by default, only application and infrastructure logs are collected. To collect audit logs, update your `ClusterLogForwarder` configuration to include them. Assign roles based on the specific log types required for your environment.
88+
====
89+
90+
. Create a `UIPlugin` CR to enable the *Log* section in the *Observe* tab:
91+
+
92+
[source,yaml]
93+
----
94+
apiVersion: observability.openshift.io/v1alpha1
95+
kind: UIPlugin
96+
metadata:
97+
name: logging
98+
spec:
99+
type: Logging
100+
logging:
101+
lokiStack:
102+
name: logging-loki
103+
----
104+
105+
. Create a `ClusterLogForwarder` CR to configure log forwarding:
106+
+
107+
[source,yaml]
108+
----
109+
apiVersion: observability.openshift.io/v1
110+
kind: ClusterLogForwarder
111+
metadata:
112+
name: collector
113+
namespace: openshift-logging
114+
spec:
115+
serviceAccount:
116+
name: collector
117+
outputs:
118+
- name: default-lokistack
119+
type: lokiStack
120+
lokiStack:
121+
authentication:
122+
token:
123+
from: serviceAccount
124+
target:
125+
name: logging-loki
126+
namespace: openshift-logging
127+
tls:
128+
ca:
129+
key: service-ca.crt
130+
configMapName: openshift-service-ca.crt
131+
pipelines:
132+
- name: default-logstore
133+
inputRefs:
134+
- application
135+
- infrastructure
136+
outputRefs:
137+
- default-lokistack
138+
----
139+
+
140+
[NOTE]
141+
====
142+
The `dataModel` field is optional and left unset (`dataModel: ""`) by default. This allows the Cluster Logging Operator (CLO) to automatically select a data model. Currently, the CLO defaults to the ViaQ model when the field is unset, but this will change in future releases. Specifying `dataModel: ViaQ` ensures the configuration remains compatible if the default changes.
143+
====
144+
145+
.Verification
146+
* Verify that logs are visible in the *Log* section of the *Observe* tab in the {product-title} web console.

‎snippets/technology-preview.adoc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
// When including this file, ensure that {FeatureName} is set immediately before
2+
// the include. Otherwise it will result in an incorrect replacement.
3+
4+
[IMPORTANT]
5+
====
6+
[subs="attributes+"]
7+
{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
8+
9+
For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
10+
====
11+
// Undefine {FeatureName} attribute, so that any mistakes are easily spotted
12+
:!FeatureName:

0 commit comments

Comments
 (0)