Skip to content

Commit 2ea6dd0

Browse files
gabriel-rhgabriel-rh
authored
Merge pull request #92457 from gabriel-rh/standalone-logging-first-pass
standalone logging docs - first pass at base 6.0 docs
2 parents 686db1b + 5fd0fa8 commit 2ea6dd0

File tree

60 files changed

+3381
-376
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

60 files changed

+3381
-376
lines changed

‎_attributes/common-attributes.adoc

+7
Original file line numberDiff line numberDiff line change
@@ -378,3 +378,10 @@ endif::openshift-origin[]
378378
379379
:LoggingProductName: OpenShift Logging
380380
:LoggingProductShortName: Logging
381+
382+
383+
:ocp-product-title: OpenShift Container Platform
384+
:ocp-product-version: 4.13
385+
:dedicated-product-title: OpenShift Dedicated
386+
:aro-product-title: Azure Red Hat OpenShift
387+
:rosa-product-title: Red Hat OpenShift Service on AWS

‎_topic_maps/_topic_map.yml

+28-3
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,32 @@ Name: About OpenShift Logging
33
Dir: about
44
Distros: openshift-logging
55
Topics:
6-
- Name: OpenShift Logging overview
6+
- Name: Logging overview
77
File: about-logging
8-
- Name: Logging
9-
File: log6x-about
8+
- Name: Cluster logging support
9+
File: cluster-logging-support
10+
- Name: Visualization for logging
11+
File: logging-visualization
12+
---
13+
Name: Installing
14+
Dir: installing
15+
Distros: openshift-logging
16+
Topics:
17+
- Name: Installing logging
18+
File: installing-logging
19+
---
20+
Name: Configuring
21+
Dir: configuring
22+
Distros: openshift-logging
23+
Topics:
24+
- Name: Configuring log forwarding
25+
File: configuring-log-forwarding
26+
- Name: Configuring LokiStack storage
27+
File: configuring-lokistack-storage
28+
---
29+
Name: Upgrading
30+
Dir: upgrading
31+
Distros: openshift-logging
32+
Topics:
33+
- Name: Upgrading to Logging 6.0
34+
File: upgrading-to-logging-60

‎about/about-logging.adoc

+169-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,175 @@
1-
:_content-type: ASSEMBLY
1+
:_mod-docs-content-type: ASSEMBLY
22
include::_attributes/common-attributes.adoc[]
33
[id="about-logging"]
4-
= {LoggingProductName} overview
4+
= {product-title} overview
55
:context: about-logging
66

77
toc::[]
88

9-
Welcome to logging
9+
The `ClusterLogForwarder` custom resource (CR) is the central configuration point for log collection and forwarding.
10+
11+
== Inputs and Outputs
12+
13+
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:
14+
15+
* `application`
16+
* `receiver`
17+
* `infrastructure`
18+
* `audit`
19+
20+
You can also define custom inputs based on namespaces or pod labels to fine-tune log selection.
21+
22+
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.
23+
24+
25+
== Receiver Input Type
26+
The receiver input type enables the Logging system to accept logs from external sources. It supports two formats for receiving logs: `http` and `syslog`.
27+
28+
The `ReceiverSpec` field defines the configuration for a receiver input.
29+
30+
== Pipelines and Filters
31+
32+
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.
33+
34+
== Operator Behavior
35+
36+
The Cluster Logging Operator manages the deployment and configuration of the collector based on the `managementState` field:
37+
38+
- When set to `Managed` (default), the Operator actively manages the logging resources to match the configuration defined in the spec.
39+
- When set to `Unmanaged`, the Operator does not take any action, allowing you to manually manage the logging components.
40+
41+
== Validation
42+
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.
43+
44+
== Quick Start
45+
46+
.Prerequisites
47+
* You have access to an {ocp-product-title} cluster with `cluster-admin` permissions.
48+
* You installed the {oc-first}.
49+
* You have access to a supported object store. For example, AWS S3, Google Cloud Storage, {azure-short}, Swift, Minio, or {rh-storage}.
50+
51+
.Procedure
52+
53+
. Install the `{clo}`, `{loki-op}`, and `{coo-first}` from OperatorHub.
54+
55+
. Create a secret to access an existing object storage bucket:
56+
+
57+
.Example command for AWS
58+
[source,terminal,subs="+quotes"]
59+
----
60+
$ oc create secret generic logging-loki-s3 \
61+
--from-literal=bucketnames="<bucket_name>" \
62+
--from-literal=endpoint="<aws_bucket_endpoint>" \
63+
--from-literal=access_key_id="<aws_access_key_id>" \
64+
--from-literal=access_key_secret="<aws_access_key_secret>" \
65+
--from-literal=region="<aws_region_of_your_bucket>" \
66+
-n openshift-logging
67+
----
68+
69+
. Create a `LokiStack` custom resource (CR) in the `openshift-logging` namespace:
70+
+
71+
[source,yaml]
72+
----
73+
apiVersion: loki.grafana.com/v1
74+
kind: LokiStack
75+
metadata:
76+
name: logging-loki
77+
namespace: openshift-logging
78+
spec:
79+
managementState: Managed
80+
size: 1x.extra-small
81+
storage:
82+
schemas:
83+
- effectiveDate: '2022-06-01'
84+
version: v13
85+
secret:
86+
name: logging-loki-s3
87+
type: s3
88+
storageClassName: gp3-csi
89+
tenants:
90+
mode: openshift-logging
91+
----
92+
93+
. Create a service account for the collector:
94+
+
95+
[source,shell]
96+
----
97+
$ oc create sa collector -n openshift-logging
98+
----
99+
100+
. Bind the `ClusterRole` to the service account:
101+
+
102+
[source,shell]
103+
----
104+
$ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector -n openshift-logging
105+
----
106+
107+
. Create a `UIPlugin` to enable the Log section in the Observe tab:
108+
+
109+
[source,yaml]
110+
----
111+
apiVersion: observability.openshift.io/v1alpha1
112+
kind: UIPlugin
113+
metadata:
114+
name: logging
115+
spec:
116+
type: Logging
117+
logging:
118+
lokiStack:
119+
name: logging-loki
120+
----
121+
122+
. Add additional roles to the collector service account:
123+
+
124+
[source,shell]
125+
----
126+
$ oc adm policy add-cluster-role-to-user collect-application-logs -z collector -n openshift-logging
127+
----
128+
+
129+
[source,terminal]
130+
----
131+
$ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector -n openshift-logging
132+
----
133+
+
134+
[source,terminal]
135+
----
136+
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector -n openshift-logging
137+
----
138+
139+
. Create a `ClusterLogForwarder` CR to configure log forwarding:
140+
+
141+
[source,yaml]
142+
----
143+
apiVersion: observability.openshift.io/v1
144+
kind: ClusterLogForwarder
145+
metadata:
146+
name: collector
147+
namespace: openshift-logging
148+
spec:
149+
serviceAccount:
150+
name: collector
151+
outputs:
152+
- name: default-lokistack
153+
type: lokiStack
154+
lokiStack:
155+
target:
156+
name: logging-loki
157+
namespace: openshift-logging
158+
authentication:
159+
token:
160+
from: serviceAccount
161+
tls:
162+
ca:
163+
key: service-ca.crt
164+
configMapName: openshift-service-ca.crt
165+
pipelines:
166+
- name: default-logstore
167+
inputRefs:
168+
- application
169+
- infrastructure
170+
outputRefs:
171+
- default-lokistack
172+
----
173+
174+
.Verification
175+
* Verify that logs are visible in the *Log* section of the *Observe* tab in the {ocp-product-title} web console.

‎about/cluster-logging-support.adoc

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cluster-logging-support"]
3+
= Cluster logging support
4+
include::_attributes/common-attributes.adoc[]
5+
:context: cluster-logging-support
6+
7+
toc::[]
8+
9+
include::snippets/logging-supported-config-snip.adoc[]
10+
include::snippets/logging-compatibility-snip.adoc[]
11+
include::snippets/logging-loki-statement-snip.adoc[]
12+
13+
{logging-uc} {for} is an opinionated collector and normalizer of application, infrastructure, and audit logs. It is intended to be used for forwarding logs to various supported systems.
14+
15+
{logging-uc} is not:
16+
17+
* A high scale log collection system
18+
* Security Information and Event Monitoring (SIEM) compliant
19+
* A "bring your own" (BYO) log collector configuration
20+
* Historical or long term log retention or storage
21+
* A guaranteed log sink
22+
* Secure storage - audit logs are not stored by default
23+
24+
[id="cluster-logging-support-CRDs_{context}"]
25+
== Supported API custom resource definitions
26+
27+
The following table describes the supported {logging-uc} APIs.
28+
29+
include::snippets/logging-api-support-states-snip.adoc[]
30+
31+
include::modules/cluster-logging-maintenance-support-list-6x.adoc[leveloffset=+1]
32+
include::modules/unmanaged-operators.adoc[leveloffset=+1]
33+
34+
//[id="support-exception-for-coo-logging-ui-plugin_{context}"]
35+
//== Support exception for the Logging UI Plugin
36+
//
37+
//Until the approaching General Availability (GA) release of the Cluster Observability Operator (COO), which is currently in link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview] (TP), Red{nbsp}Hat provides support to customers who are using Logging 6.0 or later with the COO for its Logging UI Plugin on {ocp-product-title} 4.14 or later. This support exception is temporary as the COO includes several independent features, some of which are still TP features, but the Logging UI Plugin is ready for GA.
38+
//
39+
40+
[id="cluster-logging-support-must-gather_{context}"]
41+
== Collecting {logging} data for Red Hat Support
42+
43+
When opening a support case, it is helpful to provide debugging information about your cluster to Red{nbsp}Hat Support.
44+
45+
You can use the link:https://docs.openshift.com/container-platform/latest/support/gathering-cluster-data.html#gathering-cluster-data[must-gather tool] to collect diagnostic information for project-level resources, cluster-level resources, and each of the {logging} components.
46+
For prompt support, supply diagnostic information for both {ocp-product-title} and {logging}.
47+
48+
include::modules/cluster-logging-must-gather-about.adoc[leveloffset=+2]
49+
include::modules/cluster-logging-must-gather-collecting.adoc[leveloffset=+2]

‎about/log6x-about.adoc

-65
This file was deleted.

‎about/logging-visualization.adoc

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="logging-visualization"]
3+
= Visualization for logging
4+
include::_attributes/common-attributes.adoc[]
5+
:context: logging-visualization
6+
7+
toc::[]
8+
9+
Visualization for logging is provided by deploying the link:https://docs.openshift.com/container-platform/latest/observability/cluster_observability_operator/ui_plugins/logging-ui-plugin.adoc#logging-ui-plugin[Logging UI Plugin] of the link:https://docs.openshift.com/container-platform/latest/observability/cluster_observability_operator/cluster-observability-operator-overview.adoc#cluster-observability-operator-overview[Cluster Observability Operator], which requires Operator installation.

‎configuring/_attributes

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../_attributes/

0 commit comments

Comments
 (0)