Merge pull request #95250 from eromanova97/OBSDOCS-2036

OBSDOCS-2038: fix 'Overview of API audit filter' and remove duplicate

Author: xenolinux

configuring/configuring-log-forwarding.adoc

@@ -117,7 +117,7 @@ include::modules/enabling-multi-line-exception-detection.adoc[leveloffset=+2]
 include::modules/logging-http-forward.adoc[leveloffset=+2]
 include::modules/cluster-logging-collector-log-forward-syslog.adoc[leveloffset=+2]
 include::modules/content-filter-drop-records.adoc[leveloffset=+2]
-include::modules/audit-filtering.adoc[leveloffset=+2]
+include::modules/logging-audit-log-filtering.adoc[leveloffset=+2]
 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]

log_collection_forwarding/cluster-logging-collector.adoc

@@ -30,6 +30,6 @@ include::modules/log-collector-http-server.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../log_collection_forwarding/configuring-log-forwarding.adoc#logging-audit-filtering_configuring-log-forwarding[Overview of API audit filter]
+* xref:../log_collection_forwarding/configuring-log-forwarding.adoc#logging-audit-log-filtering_configuring-log-forwarding[API audit filter overview]
 
 include::modules/cluster-logging-collector-tuning.adoc[leveloffset=+1]

modules/audit-filtering.adoc

@@ -1,58 +1,70 @@
 // Module included in the following assemblies:
 //
 // * observability/logging/log_collection_forwarding/configuring-log-forwarding.adoc
+// * configuring/configuring-log-forwarding.adoc
 
 :_mod-docs-content-type: CONCEPT
-[id="logging-audit-filtering_{context}"]
-= Overview of API audit filter
-OpenShift API servers generate audit events for each API call, detailing the request, response, and the identity of the requester, leading to large volumes of data. The API Audit filter uses rules to enable the exclusion of non-essential events and the reduction of event size, facilitating a more manageable audit trail. Rules are checked in order, checking stops at the first match. How much data is included in an event is determined by the value of the `level` field:
+[id="logging-audit-log-filtering_{context}"]
+= API audit filter overview
 
-* `None`: The event is dropped.
-* `Metadata`: Audit metadata is included, request and response bodies are removed.
-* `Request`: Audit metadata and the request body are included, the response body is removed.
-* `RequestResponse`: All data is included: metadata, request body and response body. The response body can be very large. For example, `oc get pods -A` generates a response body containing the YAML description of every pod in the cluster.
+OpenShift API servers generate audit events for every API call. These events include details about the request, the response, and the identity of the requester. This can lead to large volumes of data. 
+
+The API audit filter helps manage the audit trail by using rules to exclude non-essential events and to reduce the event size. Rules are checked in order, and checking stops at the first match. The amount of data in an event depends on the value of the `level` field:
 
+* `None`: The event is dropped.
+* `Metadata`: The event includes audit metadata and excludes request and response bodies.
+* `Request`: The event includes audit metadata and the request body, and excludes the response body.
+* `RequestResponse`: The event includes all data: metadata, request body and response body. The response body can be very large. For example, `oc get pods -A` generates a response body containing the YAML description of every pod in the cluster.
 
 [NOTE]
 ====
-You can use this feature only if the Vector collector is set up in your logging deployment.
+You can only use the API audit filter feature if the Vector collector is set up in your logging deployment.
 ====
 
-In logging 5.8 and later, the `ClusterLogForwarder` custom resource (CR) uses the same format as the standard link:https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#audit-policy[Kubernetes audit policy], while providing the following additional functions:
+The `ClusterLogForwarder` custom resource (CR) uses the same format as the standard link:https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/#audit-policy[Kubernetes audit policy]. The `ClusterLogForwarder` CR provides the following additional functions:
 
-Wildcards:: Names of users, groups, namespaces, and resources can have a leading or trailing `\*` asterisk character. For example, namespace `openshift-\*` matches `openshift-apiserver` or `openshift-authentication`. Resource `\*/status` matches `Pod/status` or `Deployment/status`.
+Wildcards:: Names of users, groups, namespaces, and resources can have a leading or trailing `\*` asterisk character. For example, the `openshift-\*` namespace matches `openshift-apiserver` or `openshift-authentication` namespaces. The `\*/status` resource matches `Pod/status` or `Deployment/status` resources.
 
 Default Rules:: Events that do not match any rule in the policy are filtered as follows:
-* Read-only system events such as `get`, `list`, `watch` are dropped.
++
+--
+* Read-only system events such as `get`, `list`, and `watch` are dropped.
 * Service account write events that occur within the same namespace as the service account are dropped.
 * All other events are forwarded, subject to any configured rate limits.
-
+--
++
 To disable these defaults, either end your rules list with a rule that has only a `level` field or add an empty rule.
 
-Omit Response Codes:: A list of integer status codes to omit. You can drop events based on the HTTP status code in the response by using the `OmitResponseCodes` field, a list of HTTP status code for which no events are created. The default value is `[404, 409, 422, 429]`. If the value is an empty list, `[]`, then no status codes are omitted.
+Omit Response Codes:: A list of integer status codes to omit. You can drop events based on the HTTP status code in the response by using the `OmitResponseCodes` field, which lists HTTP status codes for which no events are created. The default value is `[404, 409, 422, 429]`. If the value is an empty list, `[]`, no status codes are omitted.
 
 The `ClusterLogForwarder` CR audit policy acts in addition to the {ocp-product-title} audit policy. The `ClusterLogForwarder` CR audit filter changes what the log collector forwards, and provides the ability to filter by verb, user, group, namespace, or resource. You can create multiple filters to send different summaries of the same audit stream to different places. For example, you can send a detailed stream to the local cluster log store, and a less detailed stream to a remote site.
 
-[NOTE]
-====
-The example provided is intended to illustrate the range of rules possible in an audit policy and is not a recommended configuration.
+[IMPORTANT]
 ====
+* You must have the `collect-audit-logs` cluster role to collect the audit logs. 
 
+* The following example provided is intended to illustrate the range of rules possible in an audit policy and is not a recommended configuration.
+====
 
 .Example audit policy
 [source,yaml]
 ----
-apiVersion: logging.openshift.io/v1
+apiVersion: observability.openshift.io/v1
 kind: ClusterLogForwarder
 metadata:
   name: instance
   namespace: openshift-logging
 spec:
+  serviceAccount:
+    name: example-service-account
   pipelines:
     - name: my-pipeline
-      inputRefs: audit #<1>
-      filterRefs: my-policy #<2>
-      outputRefs: default
+      inputRefs: 
+        - audit # <1>
+      filterRefs: 
+        - my-policy # <2>
+      outputRefs: 
+        - my-output
   filters:
     - name: my-policy
       type: kubeAPIAudit
@@ -120,5 +132,5 @@ spec:
           # A catch-all rule to log all other requests at the Metadata level.
           - level: Metadata
 ----
-<1> 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.
+<1> The collected log types. The value for this field can be `audit` for audit logs, `application` for application logs, `infrastructure` for infrastructure logs, or a named input that is defined for your application.
 <2> The name of your audit policy.