› › ›

添加 Kubernetes 元数据

编辑

添加 Kubernetes 元数据

编辑

add_kubernetes_metadata 处理器会根据事件的来源 Kubernetes Pod，使用相关的元数据来注释每个事件。此处理器仅将元数据添加到尚未包含元数据的事件中。

在启动时，它会检测到 in_cluster 环境并缓存与 Kubernetes 相关的元数据。仅当检测到有效配置时，才会注释事件。如果无法检测到有效的 Kubernetes 配置，则不会使用 Kubernetes 相关元数据注释事件。

每个事件都使用以下信息进行注释：

Pod 名称
Pod UID
命名空间
标签

此外，节点和命名空间元数据会添加到 Pod 元数据中。

add_kubernetes_metadata 处理器有两个基本构建块：

索引器
匹配器

索引器使用 Pod 元数据为每个 Pod 创建唯一的标识符。这些标识符有助于将观察到的 Pod 的元数据与实际事件相关联。例如，ip_port 索引器可以获取一个 Kubernetes Pod，并根据其所有 pod_ip:container_port 组合为其创建标识符。

匹配器使用事件中的信息来构建查找键，这些查找键与索引器创建的标识符相匹配。例如，当 fields 匹配器使用 ["metricset.host"] 作为查找字段时，它将使用字段 metricset.host 的值构建查找键。当这些查找键之一与其中一个标识符匹配时，该事件将使用已标识的 Pod 的元数据进行丰富。

当 add_kubernetes_metadata 与 Filebeat 一起使用时，它会使用 container 索引器和 logs_path。因此，在 log.file.path 中的路径包含对容器 ID 的引用的事件会使用该容器的 Pod 元数据进行丰富。

可以通过禁用配置中的默认索引器和匹配器来禁用此行为

processors:
  - add_kubernetes_metadata:
      default_indexers.enabled: false
      default_matchers.enabled: false

您可以在索引器和匹配器中找到有关可用索引器和匹配器的更多信息以及一些示例。

以下配置在 Filebeat 作为 Kubernetes 中的 Pod 运行时启用处理器。

processors:
  - add_kubernetes_metadata:
      #labels.dedot: true
      #annotations.dedot: true

以下配置在 Kubernetes 节点上作为进程运行的 Beat 上启用处理器。

processors:
  - add_kubernetes_metadata:
      host: <hostname>
      # If kube_config is not set, KUBECONFIG environment variable will be checked
      # and if not present it will fall back to InCluster
      kube_config: $Filebeat Reference [8.17]/.kube/config
      #labels.dedot: true
      #annotations.dedot: true

以下配置禁用默认的索引器和匹配器，并启用用户感兴趣的索引器和匹配器。

processors:
  - add_kubernetes_metadata:
      host: <hostname>
      # If kube_config is not set, KUBECONFIG environment variable will be checked
      # and if not present it will fall back to InCluster
      kube_config: ~/.kube/config
      default_indexers.enabled: false
      default_matchers.enabled: false
      indexers:
        - ip_port:
      matchers:
        - fields:
            lookup_fields: ["metricset.host"]
      #labels.dedot: true
      #annotations.dedot: true

add_kubernetes_metadata 处理器具有以下配置设置：

host

（可选）指定要将 Filebeat 范围限定到的节点，以防无法准确检测到节点，例如在主机网络模式下运行 Filebeat 时。

scope

（可选）指定处理器应在节点级别还是在整个集群级别具有可见性。可能的值为 node 和 cluster。默认情况下，范围为 node。

namespace

（可选）选择要从中收集元数据的命名空间。如果未设置，则处理器将从所有命名空间收集元数据。默认情况下，此项未设置。

add_resource_metadata

（可选）指定要添加到事件的额外元数据的过滤器和配置。配置参数：

node 或 namespace：为来自节点和命名空间的额外元数据指定标签和注释过滤器。默认情况下，包含所有标签，但不包含注释。要更改默认行为，可以定义 include_labels、exclude_labels 和 include_annotations。当存储需要特殊处理以避免存储输出过载的标签和注释时，这些设置非常有用。注意：这些设置不支持通配符。可以通过设置 enabled: false 来单独禁用 node 或 namespace 元数据的丰富。
deployment：如果资源是 pod 且它是由 deployment 创建的，则默认情况下会添加 deployment 名称，可以通过设置 deployment: false 来禁用此行为。
cronjob：如果资源是 pod 且它是由 cronjob 创建的，则默认情况下会添加 cronjob 名称，可以通过设置 cronjob: false 来禁用此行为。

示例

      add_resource_metadata:
        namespace:
          include_labels: ["namespacelabel1"]
          #labels.dedot: true
          #annotations.dedot: true
        node:
          include_labels: ["nodelabel2"]
          include_annotations: ["nodeannotation1"]
          #labels.dedot: true
          #annotations.dedot: true
        deployment: false
        cronjob: false

kube_config: （可选）使用给定的配置文件作为 Kubernetes 客户端的配置。如果存在，则默认为 KUBECONFIG 环境变量。
use_kubeadm: （可选）默认为 true。默认情况下，会向 kubeadm config map 发出请求，以便通过请求 /api/v1/namespaces/kube-system/configmaps/kubeadm-config API 端点来丰富集群名称。
kube_client_options: （可选）可以为 Kubernetes 客户端配置其他选项。目前支持客户端 QPS 和 burst，如果未设置，则将使用 Kubernetes 客户端的默认 QPS 和 burst。示例：

      kube_client_options:
        qps: 5
        burst: 10

cleanup_timeout: （可选）指定停止容器运行配置之前的非活动时间。默认为 60s。
sync_period: （可选）指定列出历史资源的超时时间。
default_indexers.enabled: （可选）当您要指定自己的索引器时，启用或禁用默认的 Pod 索引器。
default_matchers.enabled: （可选）当您要指定自己的匹配器时，启用或禁用默认的 Pod 匹配器。
labels.dedot: （可选）默认为 true。如果设置为 true，则标签中的 . 将替换为 _。
annotations.dedot: （可选）默认为 true。如果设置为 true，则标签中的 . 将替换为 _。

索引器和匹配器

编辑

索引器

编辑

索引器使用 Pod 元数据为每个 Pod 创建唯一的标识符。

可用的索引器有：

container: 使用其容器的 ID 标识 Pod 元数据。
ip_port: 使用其 IP 及其公开端口的组合来标识 Pod 元数据。当使用此索引器时，元数据使用 Pod 的 IP 进行标识，并且为每个容器公开的每个端口使用 ip:port 的组合进行标识。
pod_name: 使用其命名空间和名称（如 namespace/pod_name）来标识 Pod 元数据。
pod_uid: 使用 Pod 的 UID 标识 Pod 元数据。

匹配器

编辑

匹配器用于构建查找键，这些查找键与索引创建的标识符匹配。

`field_format`

编辑

使用由字符串格式创建的键查找 Pod 元数据，该字符串格式可以包含事件字段。

此匹配器具有一个选项 format 来定义字符串格式。此字符串格式可以包含事件中任何字段的占位符。

例如，以下配置使用 ip_port 索引器通过 Pod IP 及其公开端口的组合来标识 Pod 元数据，并使用事件中的目标 IP 和端口作为匹配键：

processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - ip_port:
    matchers:
      - field_format:
          format: '%{[destination.ip]}:%{[destination.port]}'

`fields`

编辑

使用某些特定字段的值作为键来查找 Pod 元数据。当定义多个字段时，将使用事件中包含的第一个字段。

此匹配器具有一个选项 lookup_fields 来定义将使用其值进行查找的文件。

例如，以下配置使用 ip_port 索引器来标识 Pod，并定义一个匹配器，该匹配器使用目标 IP 或服务器 IP 进行查找，这是它在事件中找到的第一个：

processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - ip_port:
    matchers:
      - fields:
          lookup_fields: ['destination.ip', 'server.ip']

`logs_path`

编辑

使用从存储在 log.file.path 字段中的日志路径提取的标识符查找 Pod 元数据。

此匹配器具有以下配置设置：

logs_path

（可选）容器日志的基本路径。如果未指定，则使用 Filebeat 运行的平台的默认日志路径：对于 Linux - /var/lib/docker/containers/，Windows - C:\\ProgramData\\Docker\\containers。要更改默认值：容器 ID 必须紧随 logs_path 之后 - <log_path>/<container_id>，其中 container_id 是一个 64 个字符长的十六进制字符串。

resource_type

（可选）要获取 ID 的资源类型。有效的 resource_type：

pod：基于 Pod UID 进行查找。当 resource_type 设置为 pod 时，还必须设置 logs_path，在这种情况下支持的路径：
- /var/lib/kubelet/pods/ 用于从挂载到 Pod 卷中的卷读取日志，这些日志最终会出现在 /var/lib/kubelet/pods/<pod UID>/volumes/<volume name>/... 下。要使用 /var/lib/kubelet/pods/ 作为 log_path，必须将 /var/lib/kubelet/pods 挂载到 filebeat Pod 中。
- /var/log/pods/ 注意：当使用 resource_type: 'pod' 时，日志将仅使用 Pod 元数据（Pod ID、Pod 名称等）而不是容器元数据进行丰富。
container：基于容器 ID 进行查找，logs_path 必须设置为 /var/log/containers/。默认为 container。

为了能够使用 logs_path 匹配器，filebeat 输入路径必须是 logs_path 配置设置中定义的目录的子目录。

当从默认 docker 日志路径（Linux 上为 /var/lib/docker/containers/<container ID>/...）收集日志时，默认配置能够使用容器 ID 查找元数据。

例如，以下配置将在从 /var/lib/kubelet/pods/<pod UID>/... 收集日志时使用 Pod UID。

processors:
- add_kubernetes_metadata:
    ...
    default_indexers.enabled: false
    default_matchers.enabled: false
    indexers:
      - pod_uid:
    matchers:
      - logs_path:
          logs_path: '/var/lib/kubelet/pods'
          resource_type: 'pod'

« 为事件生成 ID 添加标签 »