OBSDOCS-2305: PT1: Port the Log collection and forwarding chapter to 6.0

configuring/configuring-log-forwarding.adoc

@@ -106,6 +106,11 @@ The order of filterRefs matters, as they are applied sequentially. Earlier filte
 
 Filters are configured in an array under `spec.filters`. They can match incoming log messages based on the value of structured fields and modify or drop them.
 
+include::modules/cluster-logging-collector-log-forwarding-about.adoc[leveloffset=+1]
+
+include::modules/logging-create-clf.adoc[leveloffset=+1]
+
+include::modules/logging-delivery-tuning.adoc[leveloffset=+1]
 
 include::modules/enabling-multi-line-exception-detection.adoc[leveloffset=+2]
 
@@ -127,3 +132,4 @@ include::modules/input-spec-filter-labels-expressions.adoc[leveloffset=+2]
 include::modules/logging-content-filter-prune-records.adoc[leveloffset=+2]
 include::modules/input-spec-filter-audit-infrastructure.adoc[leveloffset=+1]
 include::modules/input-spec-filter-namespace-container.adoc[leveloffset=+1]
+

modules/cluster-logging-collector-log-forwarding-about.adoc

@@ -1,8 +1,12 @@
+// Module included in the following assemblies:
+//
+// * configuring/configuring-log-forwarding.adoc
+
 :_mod-docs-content-type: CONCEPT
 [id="cluster-logging-collector-log-forwarding-about_{context}"]
 = About forwarding logs to third-party systems
 
-To send logs to specific endpoints inside and outside your {ocp-product-title} cluster, you specify a combination of _outputs_ and _pipelines_ in a `ClusterLogForwarder` custom resource (CR). You can also use _inputs_ to forward the application logs associated with a specific project to an endpoint. Authentication is provided by a Kubernetes _Secret_ object.
+To send logs to specific endpoints inside and outside your {ocp-product-title} cluster, you specify a combination of outputs and pipelines in a `ClusterLogForwarder` custom resource (CR). You can also use inputs to forward the application logs associated with a specific project to an endpoint. Authentication is provided by a Kubernetes `Secret` object.
 
 _pipeline_:: Defines simple routing from one log type to one or more outputs, or which logs you want to send. The log types are one of the following:
 +
@@ -31,103 +35,55 @@ Note the following:
 
 * You can use multiple types of outputs in the `ClusterLogForwarder` custom resource (CR) to send logs to servers that support different protocols.
 
-The following example forwards the audit logs to a secure external Elasticsearch instance, the infrastructure logs to an insecure external Elasticsearch instance, the application logs to a Kafka broker, and the application logs from the `my-apps-logs` project to the internal Elasticsearch instance.
+The following example forwards the audit logs to a secure external Elasticsearch instance.
 
 .Sample log forwarding outputs and pipelines
 [source,yaml]
 ----
-apiVersion: "logging.openshift.io/v1"
 kind: ClusterLogForwarder
+apiVersion: observability.openshift.io/v1
 metadata:
-  name: <log_forwarder_name> <1>
-  namespace: <log_forwarder_namespace> <2>
+  name: instance
+  namespace: openshift-logging
 spec:
-  serviceAccountName: <service_account_name> <3>
+  serviceAccount:
+    name: logging-admin
   outputs:
-   - name: elasticsearch-secure <4>
-     type: "elasticsearch"
-     url: https://elasticsearch.secure.com:9200
-     secret:
-        name: elasticsearch
-   - name: elasticsearch-insecure <5>
-     type: "elasticsearch"
-     url: http://elasticsearch.insecure.com:9200
-   - name: kafka-app <6>
-     type: "kafka"
-     url: tls://kafka.secure.com:9093/app-topic
-  inputs: <7>
-   - name: my-app-logs
-     application:
-        namespaces:
-        - my-project
+    - name: external-es
+      type: elasticsearch
+      elasticsearch:
+        url: 'https://example-elasticsearch-secure.com:9200'
+        version: 8  # <1>
+        index: '{.log_type||"undefined"}'  # <2>
+        authentication:
+          username:
+            key: username
+            secretName: es-secret  # <3>
+          password:
+            key: password
+            secretName: es-secret  # <3>
+      tls:
+        ca:                        # <4>
+          key: ca-bundle.crt
+          secretName: es-secret
+        certificate:
+          key: tls.crt
+          secretName: es-secret
+        key:
+          key: tls.key
+          secretName: es-secret
   pipelines:
-   - name: audit-logs <8>
-     inputRefs:
-      - audit
-     outputRefs:
-      - elasticsearch-secure
-      - default
-     labels:
-       secure: "true" <9>
-       datacenter: "east"
-   - name: infrastructure-logs <10>
-     inputRefs:
-      - infrastructure
-     outputRefs:
-      - elasticsearch-insecure
-     labels:
-       datacenter: "west"
-   - name: my-app <11>
-     inputRefs:
-      - my-app-logs
-     outputRefs:
-      - default
-   - inputRefs: <12>
-      - application
-     outputRefs:
-      - kafka-app
-     labels:
-       datacenter: "south"
+    - name: my-logs
+      inputRefs:
+        - application
+        - infrastructure
+      outputRefs:
+        - external-es
 ----
-<1> In legacy implementations, the CR name must be `instance`. In multi log forwarder implementations, you can use any name.
-<2> In legacy implementations, the CR namespace must be `openshift-logging`. In multi log forwarder implementations, you can use any namespace.
-<3> The name of your service account. The service account is only required in multi log forwarder implementations if the log forwarder is not deployed in the `openshift-logging` namespace.
-<4> Configuration for an secure Elasticsearch output using a secret with a secure URL.
-** A name to describe the output.
-** The type of output: `elasticsearch`.
-** The secure URL and port of the Elasticsearch instance as a valid absolute URL, including the prefix.
-** The secret required by the endpoint for TLS communication. The secret must exist in the `openshift-logging` project.
-<5> Configuration for an insecure Elasticsearch output:
-** A name to describe the output.
-** The type of output: `elasticsearch`.
-** The insecure URL and port of the Elasticsearch instance as a valid absolute URL, including the prefix.
-<6> Configuration for a Kafka output using a client-authenticated TLS communication over a secure URL:
-** A name to describe the output.
-** The type of output: `kafka`.
-** Specify the URL and port of the Kafka broker as a valid absolute URL, including the prefix.
-<7> Configuration for an input to filter application logs from the `my-project` namespace.
-<8> Configuration for a pipeline to send audit logs to the secure external Elasticsearch instance:
-** A name to describe the pipeline.
-** The `inputRefs` is the log type, in this example `audit`.
-** The `outputRefs` is the name of the output to use, in this example `elasticsearch-secure` to forward to the secure Elasticsearch instance and `default` to forward to the internal Elasticsearch instance.
-** Optional: Labels to add to the logs.
-<9> Optional: String. One or more labels to add to the logs. Quote values like "true" so they are recognized as string values, not as a boolean.
-<10> Configuration for a pipeline to send infrastructure logs to the insecure external Elasticsearch instance.
-<11> Configuration for a pipeline to send logs from the `my-project` project to the internal Elasticsearch instance.
-** A name to describe the pipeline.
-** The `inputRefs` is a specific input: `my-app-logs`.
-** The `outputRefs` is `default`.
-** Optional: String. One or more labels to add to the logs.
-<12> Configuration for a pipeline to send logs to the Kafka broker, with no pipeline name:
-** The `inputRefs` is the log type, in this example `application`.
-** The `outputRefs` is the name of the output to use.
-** Optional: String. One or more labels to add to the logs.
-
-[discrete]
-[id="cluster-logging-external-fluentd_{context}"]
-== Fluentd log handling when the external log aggregator is unavailable
-
-If your external logging aggregator becomes unavailable and cannot receive logs, Fluentd continues to collect logs and stores them in a buffer. When the log aggregator becomes available, log forwarding resumes, including the buffered logs. If the buffer fills completely, Fluentd stops collecting logs. {ocp-product-title} rotates the logs and deletes them. You cannot adjust the buffer size or add a persistent volume claim (PVC) to the Fluentd daemon set or pods.
+<1> Forwarding to an external Elasticsearch of version 8.x or greater requires the `version` field to be specified.
+<2> `index` is set to read the field value `.log_type` and falls back to "unknown" if not found.
+<3> Use username and password to authenticate to the server
+<4> Enable Mutual Transport Layer Security (mTLS) between collector and elasticsearch. The spec identifies the keys and secret to the respective certificates that they represent.
 
 [discrete]
 == Supported Authorization Keys

modules/logging-create-clf.adoc

@@ -1,54 +1,55 @@
 // Module included in the following assemblies:
 //
-// * observability/logging/log_collection_forwarding/log-forwarding.adoc
+// * configuring/log_collection_forwarding/log-forwarding.adoc
 
 :_mod-docs-content-type: REFERENCE
 [id="logging-create-clf_{context}"]
 = Creating a log forwarder
 
-To create a log forwarder, you must create a `ClusterLogForwarder` CR that specifies the log input types that the service account can collect. You can also specify which outputs the logs can be forwarded to. If you are using the multi log forwarder feature, you must also reference the service account in the `ClusterLogForwarder` CR.
-
-If you are using the multi log forwarder feature on your cluster, you can create `ClusterLogForwarder` custom resources (CRs) in any namespace, using any name.
-If you are using a legacy implementation, the `ClusterLogForwarder` CR must be named `instance`, and must be created in the `openshift-logging` namespace.
+To create a log forwarder, create a `ClusterLogForwarder` custom resource (CR). This CR defines the service account, permissible input log types, pipelines, outputs, and any optional filters.
 
 [IMPORTANT]
 ====
 You need administrator permissions for the namespace where you create the `ClusterLogForwarder` CR.
 ====
 
-.ClusterLogForwarder resource example
+.`ClusterLogForwarder` CR example
 [source,yaml]
 ----
-apiVersion: logging.openshift.io/v1
+apiVersion: observability.openshift.io/v1
 kind: ClusterLogForwarder
-metadata:
-  name: <log_forwarder_name> <1>
-  namespace: <log_forwarder_namespace> <2>
+metadata:  
+  name: <log_forwarder_name>
+  namespace: <log_forwarder_namespace>
 spec:
-  serviceAccountName: <service_account_name> <3>
+  outputs:                       # <1>
+    - name: <output_name>
+      type: <output_type> 
+  inputs:                        # <2>
+    - name: <input_name>  
+      type: <input_type>  
+  filters:                       # <3>
+    - name: <filter_name>
+      type: <filter_type> 
   pipelines:
-   - inputRefs:
-     - <log_type> <4>
-     outputRefs:
-     - <output_name> <5>
-  outputs:
-  - name: <output_name> <6>
-    type: <output_type> <5>
-    url: <log_output_url> <7>
+    - inputRefs:
+      - <input_name>             #<4>
+    - outputRefs:
+      - <output_name>            #<5>
+    - filterRefs:
+      - <filter_name>            #<6>
+  serviceAccount:
+    name: <service_account_name> #<7>
 # ...
 ----
-<1> In legacy implementations, the CR name must be `instance`. In multi log forwarder implementations, you can use any name.
-<2> In legacy implementations, the CR namespace must be `openshift-logging`. In multi log forwarder implementations, you can use any namespace.
-<3> The name of your service account. The service account is only required in multi log forwarder implementations if the log forwarder is not deployed in the `openshift-logging` namespace.
-<4> The log types that are collected. The value for this field can be `audit` for audit logs, `application` for application logs, `infrastructure` for infrastructure logs, or a named input that has been defined for your application.
-<5> The type of output that you want to forward logs to. The value of this field can be `default`, `loki`, `kafka`, `elasticsearch`, `fluentdForward`, `syslog`, or `cloudwatch`.
-+
-[NOTE]
-====
-The `default` output type is not supported in mutli log forwarder implementations.
-====
-<6> A name for the output that you want to forward logs to.
-<7> The URL of the output that you want to forward logs to.
+<1> The type of output that you want to forward logs to. The value of this field can be `azureMonitor`, `cloudwatch`, `elasticsearch`, `googleCloudLogging`, `http`, `kafka`, `loki`, `lokistack`, `otlp`, `splunk`, or `syslog`.
+<2> A list of inputs. The names `application`, `audit`, and `infrastructure` are reserved for the default inputs.
+<3> A list of filters to apply to records going through this pipeline. Each filter is applied in the order defined here. If a filter drops a records, subsequent filters are not applied.
+<4> This value should be the same as the input name. You can also use the default input names `application`, `infrastructure`, and `audit`.
+<5> This value should be the same as the output name.
+<6> This value should be the same as the filter name.
+<7> The name of your service account.
+
 
 // To be followed up on by adding input examples / docs:
 ////

modules/logging-delivery-tuning.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * observability/logging/log_collection_forwarding/configuring-log-forwarding.adoc
+// * configuring/configuring-log-forwarding.adoc
 
 :_mod-docs-content-type: REFERENCE
 [id="logging-delivery-tuning_{context}"]
 = Tuning log payloads and delivery
 
-In {logging} 5.9 and newer versions, the `tuning` spec in the `ClusterLogForwarder` custom resource (CR) provides a means of configuring your deployment to prioritize either throughput or durability of logs.
+The `tuning` spec in the `ClusterLogForwarder` custom resource (CR) provides a means of configuring your deployment to prioritize either throughput or durability of logs.
 
 For example, if you need to reduce the possibility of log loss when the collector restarts, or you require collected log messages to survive a collector restart to support regulatory mandates, you can tune your deployment to prioritize log durability. If you use outputs that have hard limitations on the size of batches they can receive, you may want to tune your deployment to prioritize log throughput.
 
@@ -41,11 +41,12 @@ spec:
 <1> Specify the delivery mode for log forwarding.
 ** `AtLeastOnce` delivery means that if the log forwarder crashes or is restarted, any logs that were read before the crash but not sent to their destination are re-sent. It is possible that some logs are duplicated after a crash.
 ** `AtMostOnce` delivery means that the log forwarder makes no effort to recover logs lost during a crash. This mode gives better throughput, but may result in greater log loss.
-<2> Specifying a `compression` configuration causes data to be compressed before it is sent over the network. Note that not all output types support compression, and if the specified compression type is not supported by the output, this results in an error. The possible values for this configuration are `none` for no compression, `gzip`, `snappy`, `zlib`, or `zstd`. `lz4` compression is also available if you are using a Kafka output. See the table "Supported compression types for tuning outputs" for more information.
+<2> Specifying a `compression` configuration causes data to be compressed before it is sent over the network. Note that not all output types support compression, and if the specified compression type is not supported by the output, this results in an error. For more information, see "Supported compression types for tuning outputs".
 <3> Specifies a limit for the maximum payload of a single send operation to the output.
 <4> Specifies a minimum duration to wait between attempts before retrying delivery after a failure. This value is a string, and can be specified as milliseconds (`ms`), seconds (`s`), or minutes (`m`).
 <5> Specifies a maximum duration to wait between attempts before retrying delivery after a failure. This value is a string, and can be specified as milliseconds (`ms`), seconds (`s`), or minutes (`m`).
 
+[id="supported-compression-types_{context}"]
 .Supported compression types for tuning outputs
 [options="header"]
 |===