升级到 Logging 6.0 - 日志记录 | 可观察性 | OpenShift 容器平台 4.17

使用oc explain命令
日志存储
日志可视化
日志收集和转发
管理、资源分配和工作负载调度
输入规范
- 应用程序输入
- 输入接收器
输出规范
密钥和 TLS 配置
Red Hat 托管 Elasticsearch
Red Hat 托管 LokiStack
过滤器和管道配置
验证和状态

日志记录 v6.0 是对以前版本的重大升级，实现了集群日志记录的几个长期目标

引入了不同的运算符来管理日志记录组件（例如，收集器、存储、可视化）。
删除了对基于 Elastic 产品（即 Elasticsearch、Kibana）的托管日志存储和可视化的支持。
弃用了 Fluentd 日志收集器实现。
删除了对ClusterLogging.logging.openshift.io和ClusterLogForwarder.logging.openshift.io资源的支持。

**cluster-logging-operator**不提供自动升级流程。

鉴于日志收集、转发和存储的各种配置，**cluster-logging-operator**不提供自动升级。本文档可帮助管理员将现有的ClusterLogging.logging.openshift.io和ClusterLogForwarder.logging.openshift.io规范转换为新的 API。其中包含针对常见用例的已迁移ClusterLogForwarder.observability.openshift.io资源示例。

使用`oc explain`命令

oc explain命令是 OpenShift CLI oc 中的一个重要工具，它提供自定义资源 (CR) 内字段的详细描述。此命令对于配置或排查 OpenShift 集群中资源的管理员和开发人员来说非常宝贵。

资源描述

oc explain提供与特定对象关联的所有字段的深入解释。这包括像 Pod 和服务这样的标准资源，以及像 StatefulSet 和由运算符定义的自定义资源这样的更复杂的实体。

要查看ClusterLogForwarder自定义资源的outputs字段的文档，可以使用

$ oc explain clusterlogforwarders.observability.openshift.io.spec.outputs

可以使用简写形式obsclf代替clusterlogforwarder。

这将显示有关这些字段的详细信息，包括它们的类型、默认值和任何相关的子字段。

分层结构

该命令以分层格式显示资源字段的结构，阐明不同配置选项之间的关系。

例如，以下是如何深入了解LokiStack自定义资源的storage配置。

$ oc explain lokistacks.loki.grafana.com
$ oc explain lokistacks.loki.grafana.com.spec
$ oc explain lokistacks.loki.grafana.com.spec.storage
$ oc explain lokistacks.loki.grafana.com.spec.storage.schemas

每个命令都揭示了资源规范更深层次的细节，使结构清晰明了。

类型信息

oc explain还会指示每个字段的类型（例如字符串、整数或布尔值），允许您验证资源定义是否使用了正确的数据类型。

例如

$ oc explain lokistacks.loki.grafana.com.spec.size

这将显示size应使用整数值定义。

默认值

在适用情况下，该命令会显示字段的默认值，从而深入了解在未明确指定任何值时将使用哪些值。

再次使用lokistacks.loki.grafana.com为例

$ oc explain lokistacks.spec.template.distributor.replicas

示例输出

GROUP:      loki.grafana.com
KIND:       LokiStack
VERSION:    v1

FIELD: replicas <integer>

DESCRIPTION:
    Replicas defines the number of replica pods of the component.

日志存储

在此版本中，唯一可用的托管日志存储解决方案是Lokistack，由**loki-operator**管理。此解决方案以前作为托管Elasticsearch产品的首选替代方案，其部署过程保持不变。

要继续使用由**elasticsearch-operator**提供的现有Red Hat托管Elasticsearch或Kibana部署，请在删除openshift-logging命名空间中名为instance的ClusterLogging资源之前，从openshift-logging命名空间中名为elasticsearch的Elasticsearch资源和名为kibana的Kibana资源中删除所有者引用。

临时将**ClusterLogging**状态设置为Unmanaged

$ oc -n openshift-logging patch clusterlogging/instance -p '{"spec":{"managementState": "Unmanaged"}}' --type=merge

从**Elasticsearch**资源中删除**ClusterLogging**的ownerReferences

以下命令确保**ClusterLogging**不再拥有**Elasticsearch**资源。对**ClusterLogging**资源的logStore字段的更新将不再影响**Elasticsearch**资源。
```
$ oc -n openshift-logging patch elasticsearch/elasticsearch -p '{"metadata":{"ownerReferences": []}}' --type=merge
```
从**Kibana**资源中删除**ClusterLogging**的ownerReferences

以下命令确保**ClusterLogging**不再拥有**Kibana**资源。对**ClusterLogging**资源的visualization字段的更新将不再影响**Kibana**资源。
```
$ oc -n openshift-logging patch kibana/kibana -p '{"metadata":{"ownerReferences": []}}' --type=merge
```
将**ClusterLogging**状态设置为Managed

$ oc -n openshift-logging patch clusterlogging/instance -p '{"spec":{"managementState": "Managed"}}' --type=merge

日志可视化

日志可视化的OpenShift控制台UI插件已从**cluster-logging-operator**移动到**cluster-observability-operator**。

日志收集和转发

日志收集和转发配置现在在新的API中指定，它是observability.openshift.io API组的一部分。以下部分重点介绍与旧API资源的区别。

Vector是唯一受支持的收集器实现。

管理、资源分配和工作负载调度

管理状态（例如，Managed、Unmanaged）、资源请求和限制、容忍度和节点选择的配置现在是新的**ClusterLogForwarder** API的一部分。

之前的配置

apiVersion: "logging.openshift.io/v1"
kind: "ClusterLogging"
spec:
  managementState: "Managed"
  collection:
    resources:
      limits: {}
      requests: {}
    nodeSelector: {}
    tolerations: {}

当前配置

apiVersion: "observability.openshift.io/v1"
kind: ClusterLogForwarder
spec:
  managementState: Managed
  collector:
    resources:
      limits: {}
      requests: {}
    nodeSelector: {}
    tolerations: {}

输入规范

输入规范是**ClusterLogForwarder**规范的可选部分。管理员可以继续使用**application**、**infrastructure**和**audit**的预定义值来收集这些来源。

应用程序输入

命名空间和容器的包含和排除已合并到单个字段中。

5.9 包含和排除命名空间和容器的应用程序输入

apiVersion: "logging.openshift.io/v1"
kind: ClusterLogForwarder
spec:
  inputs:
   - name: application-logs
     type: application
     application:
       namespaces:
       - foo
       - bar
       includes:
       - namespace: my-important
         container: main
       excludes:
       - container: too-verbose

6.0 包含和排除命名空间和容器的应用程序输入

apiVersion: "observability.openshift.io/v1"
kind: ClusterLogForwarder
spec:
  inputs:
   - name: application-logs
     type: application
     application:
       includes:
       - namespace: foo
       - namespace: bar
       - namespace: my-important
         container: main
       excludes:
       - container: too-verbose

**application**、**infrastructure**和**audit**是保留字，在定义输入时不能用作名称。

输入接收器

输入接收器的更改包括：

在接收器级别显式配置类型。
端口设置移动到接收器级别。

5.9 输入接收器

apiVersion: "logging.openshift.io/v1"
kind: ClusterLogForwarder
spec:
  inputs:
  - name: an-http
    receiver:
      http:
        port: 8443
        format: kubeAPIAudit
  - name: a-syslog
    receiver:
      type: syslog
      syslog:
        port: 9442

6.0 输入接收器

apiVersion: "observability.openshift.io/v1"
kind: ClusterLogForwarder
spec:
  inputs:
  - name: an-http
    type: receiver
    receiver:
      type: http
      port: 8443
      http:
        format: kubeAPIAudit
  - name: a-syslog
    type: receiver
    receiver:
      type: syslog
      port: 9442

输出规范

对输出规范的高级更改包括：

URL设置已移动到每个输出类型规范。
调整参数已移动到每个输出类型规范。
TLS配置与身份验证分离。
为TLS和身份验证显式配置密钥和secret/configmap。

密钥和TLS配置

密钥和TLS配置现在分为每个输出的身份验证和TLS配置。它们必须在规范中显式定义，而不是依赖管理员定义具有已识别密钥的密钥。升级TLS和授权配置需要管理员了解以前识别的密钥才能继续使用现有密钥。以下部分中的示例提供了有关如何配置**ClusterLogForwarder**密钥以转发到现有的Red Hat托管日志存储解决方案的详细信息。

Red Hat托管Elasticsearch

v5.9 转发到Red Hat托管Elasticsearch

apiVersion: logging.openshift.io/v1
kind: ClusterLogging
metadata:
  name: instance
  namespace: openshift-logging
spec:
  logStore:
    type: elasticsearch

v6.0 转发到Red Hat托管Elasticsearch

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: instance
  namespace: openshift-logging
spec:
  outputs:
  - name: default-elasticsearch
    type: elasticsearch
    elasticsearch:
      url: https://elasticsearch:9200
      version: 6
      index: <log_type>-write-{+yyyy.MM.dd}
    tls:
      ca:
        key: ca-bundle.crt
        secretName: collector
      certificate:
        key: tls.crt
        secretName: collector
      key:
        key: tls.key
        secretName: collector
  pipelines:
  - outputRefs:
    - default-elasticsearch
  - inputRefs:
    - application
    - infrastructure

在此示例中，应用程序日志写入application-write别名/索引而不是app-write。

Red Hat托管LokiStack

v5.9 转发到Red Hat托管LokiStack

apiVersion: logging.openshift.io/v1
kind: ClusterLogging
metadata:
  name: instance
  namespace: openshift-logging
spec:
  logStore:
    type: lokistack
    lokistack:
      name: lokistack-dev

v6.0 转发到Red Hat托管LokiStack

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: instance
  namespace: openshift-logging
spec:
  outputs:
  - name: default-lokistack
    type: lokiStack
    lokiStack:
      target:
        name: lokistack-dev
        namespace: openshift-logging
      authentication:
        token:
          from: serviceAccount
    tls:
      ca:
        key: service-ca.crt
        configMapName: openshift-service-ca.crt
  pipelines:
  - outputRefs:
    - default-lokistack
  - inputRefs:
    - application
    - infrastructure

过滤器和管道配置

管道配置现在仅定义输入源到其输出目标的路由，任何所需的转换都作为过滤器单独配置。以前版本中所有管道的属性在此版本中都已转换为过滤器。单个过滤器在filters规范中定义，并由管道引用。

5.9 过滤器

apiVersion: logging.openshift.io/v1
kind: ClusterLogForwarder
spec:
  pipelines:
   - name: application-logs
     parse: json
     labels:
       foo: bar
     detectMultilineErrors: true

6.0 过滤器配置

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
spec:
  filters:
  - name: detectexception
    type: detectMultilineException
  - name: parse-json
    type: parse
  - name: labels
    type: openshiftLabels
    openshiftLabels:
      foo: bar
  pipelines:
  - name: application-logs
    filterRefs:
    - detectexception
    - labels
    - parse-json

验证和状态

大多数验证在创建或更新资源时强制执行，从而提供即时反馈。这与以前的版本不同，以前的版本在创建后进行验证，需要检查资源状态。对于在创建或更新时无法验证的情况，某些验证仍然在创建后进行。

ClusterLogForwarder.observability.openshift.io的实例必须满足以下条件，然后运算符才能部署日志收集器：已授权、有效、就绪。这些条件的一个示例是：

6.0 状态条件

apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
status:
  conditions:
  - lastTransitionTime: "2024-09-13T03:28:44Z"
    message: 'permitted to collect log types: [application]'
    reason: ClusterRolesExist
    status: "True"
    type: observability.openshift.io/Authorized
  - lastTransitionTime: "2024-09-13T12:16:45Z"
    message: ""
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/Valid
  - lastTransitionTime: "2024-09-13T12:16:45Z"
    message: ""
    reason: ReconciliationComplete
    status: "True"
    type: Ready
  filterConditions:
  - lastTransitionTime: "2024-09-13T13:02:59Z"
    message: filter "detectexception" is valid
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/ValidFilter-detectexception
  - lastTransitionTime: "2024-09-13T13:02:59Z"
    message: filter "parse-json" is valid
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/ValidFilter-parse-json
  inputConditions:
  - lastTransitionTime: "2024-09-13T12:23:03Z"
    message: input "application1" is valid
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/ValidInput-application1
  outputConditions:
  - lastTransitionTime: "2024-09-13T13:02:59Z"
    message: output "default-lokistack-application1" is valid
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/ValidOutput-default-lokistack-application1
  pipelineConditions:
  - lastTransitionTime: "2024-09-13T03:28:44Z"
    message: pipeline "default-before" is valid
    reason: ValidationSuccess
    status: "True"
    type: observability.openshift.io/ValidPipeline-default-before

已满足且适用的条件的“状态”值为“True”。状态不是“True”的条件会提供一个原因和一条消息来解释问题。

升级到日志记录 6.0

使用oc explain命令