3.3. 配置日志转发

ClusterLogForwarder (CLF)允许用户配置将日志转发到各种目的地。它提供从不同来源选择日志消息的灵活方法，通过管道发送或过滤它们，并将它们转发到一个或多个输出。

ClusterLogForwarder 的主要功能

使用输入选择日志消息
使用输出将日志转发到外部目的地
使用过滤器过滤、转换和丢弃日志消息
定义日志转发管道连接输入、过滤器和输出

3.3.1. 设置日志集合

此 Cluster Logging 发行版本要求管理员为与 ClusterLogForwarder 关联的服务帐户明确授予日志收集权限。在以前的版本中，不需要传统的日志场景由 ClusterLogging 以及一个可选的 ClusterLogForwarder.logging.openshift.io 资源组成。

Red Hat OpenShift Logging Operator 提供 collect-audit-logs、collect-application-logs 和 collect-infrastructure-logs 集群角色，使收集器能够分别收集审计日志、应用程序日志和基础架构日志。

通过将所需的集群角色绑定到服务帐户来设置日志收集。

3.3.1.1. 传统服务帐户

要使用现有的旧服务帐户 logcollector，请创建以下 ClusterRoleBinding ：

$ oc adm policy add-cluster-role-to-user collect-application-logs system:serviceaccount:openshift-logging:logcollector
$ oc adm policy add-cluster-role-to-user collect-infrastructure-logs system:serviceaccount:openshift-logging:logcollector

另外，如果收集审计日志，请创建以下 ClusterRoleBinding ：

$ oc adm policy add-cluster-role-to-user collect-audit-logs system:serviceaccount:openshift-logging:logcollector

3.3.1.2. 创建服务帐户

先决条件

Red Hat OpenShift Logging Operator 安装在 openshift-logging 命名空间中。
有管理员权限。

流程

为收集器创建服务帐户。如果要将日志写入需要令牌进行身份验证的存储，则必须在服务帐户中包含令牌。

将适当的集群角色绑定到服务帐户：

绑定命令示例

$ oc adm policy add-cluster-role-to-user <cluster_role_name> system:serviceaccount:<namespace_name>:<service_account_name>

3.3.1.2.1. 服务帐户的集群角色绑定

role_binding.yaml 文件将 ClusterLogging operator 的 ClusterRole 绑定到特定的 ServiceAccount，允许其在集群范围管理 Kubernetes 资源。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: manager-rolebinding
roleRef:                                           1
  apiGroup: rbac.authorization.k8s.io              2
  kind: ClusterRole                                3
  name: cluster-logging-operator                   4
subjects:                                          5
  - kind: ServiceAccount                           6
    name: cluster-logging-operator                 7
    namespace: openshift-logging                   8

1: roleRef：引用绑定应用到的 ClusterRole。
2: apiGroup ：指示 RBAC API 组，指定 ClusterRole 是 Kubernetes 的 RBAC 系统的一部分。
3: kind：指定引用的角色是一个 ClusterRole，它将应用集群范围的。
4: name ：绑定到 ServiceAccount 的 ClusterRole 名称，这里是 cluster-logging-operator。
5: subjects ：定义从 ClusterRole 授予权限的实体（用户或服务帐户）。
6: kind：指定主体是一个 ServiceAccount。
7: Name ：被授予权限的 ServiceAccount 的名称。
8: namespace ：指示 ServiceAccount 所在的命名空间。

3.3.1.2.2. 编写应用程序日志

write-application-logs-clusterrole.yaml 文件定义了一个 ClusterRole，它授予将应用程序日志写入 Loki 日志记录应用程序的权限。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-logging-write-application-logs
rules:                                              1
  - apiGroups:                                      2
      - loki.grafana.com                            3
    resources:                                      4
      - application                                 5
    resourceNames:                                  6
      - logs                                        7
    verbs:                                          8
      - create                                      9
Annotations
<1> rules: Specifies the permissions granted by this ClusterRole.
<2> apiGroups: Refers to the API group loki.grafana.com, which relates to the Loki logging system.
<3> loki.grafana.com: The API group for managing Loki-related resources.
<4> resources: The resource type that the ClusterRole grants permission to interact with.
<5> application: Refers to the application resources within the Loki logging system.
<6> resourceNames: Specifies the names of resources that this role can manage.
<7> logs: Refers to the log resources that can be created.
<8> verbs: The actions allowed on the resources.
<9> create: Grants permission to create new logs in the Loki system.

3.3.1.2.3. 编写审计日志

write-audit-logs-clusterrole.yaml 文件定义了一个 ClusterRole，它授予在 Loki 日志记录系统中创建审计日志的权限。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-logging-write-audit-logs
rules:                                              1
  - apiGroups:                                      2
      - loki.grafana.com                            3
    resources:                                      4
      - audit                                       5
    resourceNames:                                  6
      - logs                                        7
    verbs:                                          8
      - create                                      9

1 1: rules：定义此 ClusterRole 授予的权限。
2 2: apiGroups ：指定 API 组 loki.grafana.com。
3 3: loki.grafana.com ：负责 Loki 日志记录资源的 API 组。
4 4: resources：请参阅此角色管理的资源类型，本例中为 audit。
5 5: audit：指定角色管理 Loki 中的审计日志。
6 6: resourceNames ：定义角色可访问的特定资源。
7 7: logs ：引用可以由此角色管理的日志。
8 8: verbs ：资源允许的操作。
9 9: create ：授予创建新审计日志的权限。

3.3.1.2.4. 编写基础架构日志

write-infrastructure-logs-clusterrole.yaml 文件定义了一个 ClusterRole，它授予在 Loki 日志记录系统中创建基础架构日志的权限。

YAML 示例

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cluster-logging-write-infrastructure-logs
rules:                                              1
  - apiGroups:                                      2
      - loki.grafana.com                            3
    resources:                                      4
      - infrastructure                              5
    resourceNames:                                  6
      - logs                                        7
    verbs:                                          8
      - create                                      9

1: rules：指定此 ClusterRole 授予的权限。
2: apiGroups ：指定 Loki 相关资源的 API 组。
3: loki.grafana.com ：管理 Loki 日志记录系统的 API 组。
4: resources：定义此角色可以与之交互的资源类型。
5: infrastructure ：请参阅此角色管理的基础架构相关资源。
6: resourceNames：指定此角色可以管理的资源的名称。
7: logs ：引用与基础架构相关的日志资源。
8: verbs ：此角色所允许的操作。
9: create ：授予在 Loki 系统中创建基础架构日志的权限。

3.3.1.2.5. ClusterLogForwarder 编辑器角色

clusterlogforwarder-editor-role.yaml 文件定义了一个 ClusterRole，允许用户在 OpenShift 中管理 ClusterLogForwarders。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: clusterlogforwarder-editor-role
rules:                                              1
  - apiGroups:                                      2
      - observability.openshift.io                  3
    resources:                                      4
      - clusterlogforwarders                        5
    verbs:                                          6
      - create                                      7
      - delete                                      8
      - get                                         9
      - list                                        10
      - patch                                       11
      - update                                      12
      - watch                                       13

1: rules：指定此 ClusterRole 授予的权限。
2: apiGroups ：请参阅特定于 OpenShift 的 API 组
3: obervability.openshift.io ：用于管理可观察性资源的 API 组，如 logging。
4: resources：指定此角色可以管理的资源。
5: clusterlogforwarders ：请参阅 OpenShift 中的日志转发资源。
6: verbs ：指定 ClusterLogForwarders 上允许的操作。
7: create: Grants 权限来创建新的 ClusterLogForwarders。
8: delete: Grants 权限删除现有 ClusterLogForwarders。
9: get ：授予检索有关特定 ClusterLogForwarders 的信息的权限。
10: list ：允许列出所有 ClusterLogForwarders。
11: patch ：授予部分修改 ClusterLogForwarders 的权限。
12: update: 授予更新现有 ClusterLogForwarders 的权限。
13: watch ：授予监控 ClusterLogForwarders 的更改的权限。

3.3.2. 修改收集器中的日志级别

要修改收集器中的日志级别，您可以将 observability.openshift.io/log-level 注解设置为 trace、debug、info、warn、error 和 off。

日志级别注解示例

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: collector
  annotations:
    observability.openshift.io/log-level: debug
# ...

3.3.3. 管理 Operator

ClusterLogForwarder 资源有一个 managementState 字段，用于控制 Operator 是否主动管理其资源或保留其非受管状态：

受管: （默认）Operator 将驱动日志记录资源以匹配 CLF spec 中所需状态。
Unmanaged: Operator 不执行与日志记录组件相关的任何操作。

这样，管理员可以通过将 managementState 设置为 Unmanaged 来临时暂停日志转发。

3.3.4. ClusterLogForwarder 的结构

CLF 有一个 spec 部分，其中包含以下关键组件：

输入: 选择要转发的日志消息。来自集群不同部分的内置输入类型 application, infrastructure 和 audit。您还可以定义自定义输入。
输出: 定义要将日志转发到的目的地。每个输出都有一个唯一的名称和特定于类型的配置。
Pipelines: 定义通过过滤器到输出的路径日志从输入中获取。管道具有唯一名称，它由输入、输出和过滤器名称列表组成。
过滤器: 在管道中转换或丢弃日志消息。用户可以定义匹配某些日志字段并丢弃或修改消息的过滤器。过滤器按管道中指定的顺序应用。

3.3.4.1. 输入

输入在 spec.inputs 下的阵列中配置。有三个内置输入类型：

application: 从所有应用程序容器中选择日志，不包括基础架构命名空间中的日志，如 default、openshift 或带有 kube- 或 openshift- 前缀的任何命名空间。
infrastructure: 选择在 default 和 openshift 命名空间和节点日志中运行的基础架构组件的日志。
audit: 从 OpenShift API 服务器审计日志、Kubernetes API 服务器审计日志、ovn 审计日志和 auditd 的节点审计日志中选择日志。

用户可以定义类型 application 的自定义输入，它们从特定的命名空间选择日志或使用 pod 标签。

3.3.4.2. 输出

输出在 spec.outputs 下的一个数组中配置。每个输出都必须具有唯一的名称和类型。支持的类型有：

azureMonitor: 将日志转发到 Azure Monitor。
cloudwatch: 将日志转发到 AWS CloudWatch。
elasticsearch: 将日志转发到外部 Elasticsearch 实例。
googleCloudLogging: 将日志转发到 Google Cloud Logging。
http: 将日志转发到通用 HTTP 端点。
kafka: 将日志转发到 Kafka 代理。
loki: 将日志转发到 Loki 日志记录后端。
lokistack: 将日志转发到 Loki 和 Web 代理与 OpenShift Container Platform 身份验证集成支持的日志组合。LokiStack 的代理使用 OpenShift Container Platform 身份验证来强制实施多租户
otlp: 使用 OpenTelemetry 协议转发日志。
splunk: 将日志转发到 Splunk。
syslog: 将日志转发到外部 syslog 服务器。

每种输出类型都有自己的配置字段。

3.3.5. 配置 OTLP 输出

集群管理员可以使用 OpenTelemetry 协议(OTLP)输出来收集日志并将其转发到 OTLP 接收器。OTLP 输出使用 OpenTelemetry Observability 框架定义的规格使用 JSON 编码通过 HTTP 发送数据。

重要

OpenTelemetry 协议(OTLP)输出日志转发器只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。

有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。

流程

创建或编辑 ClusterLogForwarder 自定义资源(CR)，通过添加以下注解来启用使用 OTLP 的转发：

ClusterLogForwarder CR 示例

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  annotations:
    observability.openshift.io/tech-preview-otlp-output: "enabled" 1
  name: clf-otlp
spec:
  serviceAccount:
    name: <service_account_name>
  outputs:
  - name: otlp
    type: otlp
    otlp:
      tuning:
        compression: gzip
        deliveryMode: AtLeastOnce
        maxRetryDuration: 20
        maxWrite: 10M
        minRetryDuration: 5
      url: <otlp_url> 2
  pipelines:
  - inputRefs:
    - application
    - infrastructure
    - audit
    name: otlp-logs
    outputRefs:
    - otlp

1: 使用此注解启用 OpenTelemetry 协议(OTLP)输出，它是一个技术预览功能。
2: 此 URL 必须是绝对的，是发送日志的 OTLP 端点的占位符。

注意

OTLP 输出使用 OpenTelemetry 数据模型，它与其他输出类型的 ViaQ 数据模型不同。它遵循 OpenTelemetry Observability 框架定义的 OpenTelemetry Semantic Conventions。

3.3.5.1. Pipelines

管道在 spec.pipelines 下的数组中配置。每个管道都必须具有唯一的名称，它由以下组成：

inputRefs: 日志应转发到此管道的输入名称。
outputRefs: 将日志发送到的输出名称。
filterRefs: （可选）要应用的过滤器名称。

filterRefs 的顺序很重要，因为它们会按顺序应用。较早的过滤器可以丢弃不会被后续过滤器处理的消息。

3.3.5.2. 过滤器

过滤器在 spec.filters 下的数组中配置。它们可以根据结构化字段的值匹配传入的日志消息，并修改或丢弃它们。

管理员可以配置以下过滤器：

3.3.5.3. 启用多行异常检测

启用容器日志的多行错误检测。

警告

启用此功能可能会对性能有影响，可能需要额外的计算资源或备用日志记录解决方案。

日志解析器通常会错误地将同一个例外中的不同的行识别为不同的例外。这会导致额外的日志条目，以及要跟踪的信息的不完整或不正确。

java 异常示例

java.lang.NullPointerException: Cannot invoke "String.toString()" because "<param1>" is null
    at testjava.Main.handle(Main.java:47)
    at testjava.Main.printMe(Main.java:19)
    at testjava.Main.main(Main.java:10)

要启用日志记录来检测多行异常并将其重新编译到单个日志条目中，请确保 ClusterLogForwarder 自定义资源(CR)包含 .spec.filters 下的 detectMultilineErrors 字段。

ClusterLogForwarder CR 示例

apiVersion: "observability.openshift.io/v1"
kind: ClusterLogForwarder
metadata:
  name: <log_forwarder_name>
  namespace: <log_forwarder_namespace>
spec:
  serviceAccount:
    name: <service_account_name>
  filters:
  - name: <name>
    type: detectMultilineException
  pipelines:
    - inputRefs:
        - <input-name>
      name: <pipeline-name>
      filterRefs:
        - <filter-name>
      outputRefs:
        - <output-name>

3.3.5.3.1. 详情

当日志消息作为一系列针对一个例外的信息出现时，会将它们合并到一个统一的日志记录中。第一个日志消息的内容被替换为序列中所有消息字段的连接内容。

收集器支持以下语言：

Java
JS
Ruby
Python
Golang
PHP
Dart

3.3.5.4. 配置内容过滤器以丢弃不需要的日志记录

配置 drop 过滤器后，日志收集器会根据过滤器在转发前评估日志流。收集器丢弃与指定配置匹配的不需要的日志记录。

流程

将过滤器的配置添加到 ClusterLogForwarder CR 中的 filters spec 中。
以下示例演示了如何配置 ClusterLogForwarder CR，以根据正则表达式丢弃日志记录：
ClusterLogForwarder CR 示例
```
apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
# ...
spec:
  serviceAccount:
    name: <service_account_name>
  filters:
  - name: <filter_name>
    type: drop 1
    drop: 2
    - test: 3
      - field: .kubernetes.labels."foo-bar/baz" 4
        matches: .+ 5
      - field: .kubernetes.pod_name
        notMatches: "my-pod" 6
  pipelines:
  - name: <pipeline_name> 7
    filterRefs: ["<filter_name>"]
# ...
```
1
指定过滤器的类型。drop 过滤器丢弃与过滤器配置匹配的日志记录。
2
指定应用 drop 过滤器的配置选项。
3
指定用于评估是否丢弃日志记录的测试配置。
如果为测试指定的所有条件都为 true，则测试会通过，记录将被丢弃。
当为 drop 过滤器配置指定多个测试时，如果有任何测试通过，则会丢弃记录。
如果评估条件时出错，例如，被评估的日志记录中缺少该字段，则条件评估为 false。
4
指定点分隔的字段路径，它是日志记录中字段的路径。该路径可以包含字母数字字符和下划线 (a-zA-Z0-9_)，例如 .kubernetes.namespace_name。如果网段包含此范围之外的字符，段必须放在引号内，例如，.kubernetes.labels."foo.bar-bar/baz"。您可以在单个 test 配置中包含多个字段路径，但它们都必须评估为 true 才能通过测试以及要应用的 drop 过滤器。
5
指定正则表达式。如果日志记录与此正则表达式匹配，它们将被丢弃。您可以为单个 field 路径设置 matches 或 notMatches 条件，但不能同时设置这两个条件。
6
指定正则表达式。如果日志记录与此正则表达式不匹配，它们将被丢弃。您可以为单个 field 路径设置 matches 或 notMatches 条件，但不能同时设置这两个条件。
7
指定 drop 过滤器应用到的管道。
运行以下命令来应用 ClusterLogForwarder CR：
```
$ oc apply -f <filename>.yaml
```

其他示例

下面的额外示例演示了如何将 drop 过滤器配置为仅保留更高优先级的日志记录：

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
# ...
spec:
  serviceAccount:
    name: <service_account_name>
  filters:
  - name: important
    type: drop
    drop:
    - test:
      - field: .message
        notMatches: "(?i)critical|error"
      - field: .level
        matches: "info|warning"
# ...

除了在单一 test 配置中包含多个字段路径外，您还可以包含被视为 OR 检查的额外测试。在以下示例中，如果 test 配置评估为 true，则记录将被丢弃。但是，对于第二个 test 配置，两个字段 specs 都必须是 true，才能将其评估为 true ：

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
# ...
spec:
  serviceAccount:
    name: <service_account_name>
  filters:
  - name: important
    type: drop
    drop:
    - test:
      - field: .kubernetes.namespace_name
        matches: "^open"
    - test:
      - field: .log_type
        matches: "application"
      - field: .kubernetes.pod_name
        notMatches: "my-pod"
# ...

3.3.5.5. API 审计过滤器概述

OpenShift API 服务器为每个 API 调用生成审计事件，详细说明请求者的请求、响应和请求者的身份，从而导致大量数据。API 审计过滤器使用规则启用非必要事件和事件大小减少，从而提高更易于管理的审计跟踪。规则按顺序检查，检查会在第一个匹配项时停止。事件中包含的数据量由 level 字段的值决定：

None: 事件被丢弃。
Metadata：只包含审计元数据，请求和响应正文会被删除。
Request：包含审计元数据和请求正文，响应正文会被删除。
RequestResponse：包含所有数据：元数据、请求正文和响应正文。响应正文可能非常大。例如，oc get pods -A 生成包含集群中每个 pod 的 YAML 描述的响应正文。

ClusterLogForwarder 自定义资源 (CR) 使用与标准 Kubernetes Audit 策略相同的格式，同时提供以下附加功能：

通配符

用户、组、命名空间和资源的名称可以在前导或尾部带有 * 星号字符。例如，命名空间 openshift-\* 匹配 openshift-apiserver 或 openshift-authentication。资源 \*/status 匹配 Pod/status 或 Deployment/status。

默认规则

与策略中任何规则不匹配的事件将被过滤，如下所示：

get、list 和 watch 等只读系统事件会被丢弃。
服务帐户写入发生在与服务帐户相同的命名空间中的事件将被丢弃。
所有其他事件都会被转发，受任何配置的速率限制。

要禁用这些默认值，请使用只有一个 level 字段的规则结束您的规则列表，或者添加一条空规则。

省略响应代码: 要省略的整数状态代码列表。您可以使用 OmitResponseCodes 字段（没有创建事件）的 HTTP 状态代码列表根据响应中的 HTTP 状态代码丢弃事件。默认值为 [404, 409, 422, 429]。如果该值为空列表 []，则不会省略状态代码。

ClusterLogForwarder CR Audit 策作为 OpenShift Container Platform 审计策略外的补充起作用。ClusterLogForwarder CR 审计过滤器更改日志收集器转发的内容，并提供按操作动词、用户、组、命名空间或资源过滤的功能。您可以创建多个过滤器，将同一审计流的不同摘要发送到不同的位置。例如，您可以将详细的流发送到本地集群日志存储，并将不太详细的流发送到远程站点。

注意

您必须具有集群角色 collect-audit-logs 才能收集审计日志。以下示例旨在说明审计策略中可能的规则范围，不是推荐的配置。

Audit 策略示例

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: <log_forwarder_name>
  namespace: <log_forwarder_namespace>
spec:
  serviceAccount:
    name: <service_account_name>
  pipelines:
    - name: my-pipeline
      inputRefs: audit 1
      filterRefs: my-policy 2
  filters:
    - name: my-policy
      type: kubeAPIAudit
      kubeAPIAudit:
        # Don't generate audit events for all requests in RequestReceived stage.
        omitStages:
          - "RequestReceived"

        rules:
          # Log pod changes at RequestResponse level
          - level: RequestResponse
            resources:
            - group: ""
              resources: ["pods"]

          # Log "pods/log", "pods/status" at Metadata level
          - level: Metadata
            resources:
            - group: ""
              resources: ["pods/log", "pods/status"]

          # Don't log requests to a configmap called "controller-leader"
          - level: None
            resources:
            - group: ""
              resources: ["configmaps"]
              resourceNames: ["controller-leader"]

          # Don't log watch requests by the "system:kube-proxy" on endpoints or services
          - level: None
            users: ["system:kube-proxy"]
            verbs: ["watch"]
            resources:
            - group: "" # core API group
              resources: ["endpoints", "services"]

          # Don't log authenticated requests to certain non-resource URL paths.
          - level: None
            userGroups: ["system:authenticated"]
            nonResourceURLs:
            - "/api*" # Wildcard matching.
            - "/version"

          # Log the request body of configmap changes in kube-system.
          - level: Request
            resources:
            - group: "" # core API group
              resources: ["configmaps"]
            # This rule only applies to resources in the "kube-system" namespace.
            # The empty string "" can be used to select non-namespaced resources.
            namespaces: ["kube-system"]

          # Log configmap and secret changes in all other namespaces at the Metadata level.
          - level: Metadata
            resources:
            - group: "" # core API group
              resources: ["secrets", "configmaps"]

          # Log all other resources in core and extensions at the Request level.
          - level: Request
            resources:
            - group: "" # core API group
            - group: "extensions" # Version of group should NOT be included.

          # A catch-all rule to log all other requests at the Metadata level.
          - level: Metadata

1: 收集的日志类型。此字段的值可以是 audit(用于审计日志）、application（用于应用程序日志）、infrastructure（用于基础架构日志），或输入为您的应用程序定义的名称。
2: 审计策略的名称。

3.3.5.6. 在输入 ny 过滤应用程序日志，包括标签表达式或匹配的标签键和值

您可以使用 input 选择器，根据标签表达式或匹配的标签键及其值包含应用程序日志。

流程

将过滤器的配置添加到 ClusterLogForwarder CR 中的 input spec 中。

以下示例演示了如何配置 ClusterLogForwarder CR，使其包含基于标签表达式或匹配的标签键/值的日志：