添加 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 的元数据来丰富事件。

每个 Beat 都可以定义自己的默认索引器和匹配器,默认情况下启用这些索引器和匹配器。例如,Filebeat 启用 container 索引器,该索引器基于所有容器 ID 标识 Pod 元数据,并启用 logs_path 匹配器,该匹配器获取 log.file.path 字段,提取容器 ID,并使用它来检索元数据。

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

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

processors:
  - add_kubernetes_metadata:
      # Defining indexers and matchers manually is required for heartbeat, for instance:
      #indexers:
      #  - ip_port:
      #matchers:
      #  - fields:
      #      lookup_fields: ["metricset.host"]
      #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: $Heartbeat Reference [8.17]/.kube/config
      # Defining indexers and matchers manually is required for heartbeat, for instance:
      #indexers:
      #  - ip_port:
      #matchers:
      #  - fields:
      #      lookup_fields: ["metricset.host"]
      #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
(可选)指定节点以将 Heartbeat 的范围限定为无法准确检测到的情况,例如在主机网络模式下运行 Heartbeat 时。
scope
(可选)指定处理器应在节点级别还是在整个集群级别具有可见性。可能的值为 nodecluster。默认情况下,范围为 node
namespace
(可选)选择要从中收集元数据的命名空间。如果未设置,则处理器会从所有命名空间收集元数据。默认情况下未设置。
add_resource_metadata

(可选)指定额外元数据的过滤器和配置,这些元数据将添加到事件中。配置参数

  • nodenamespace:指定来自节点和命名空间的额外元数据的标签和注释过滤器。默认情况下,会包括所有标签,但不包括注释。要更改默认行为,可以定义 include_labelsexclude_labelsinclude_annotations。当存储需要特殊处理以避免存储输出过载的标签和注释时,这些设置非常有用。注意:这些设置不支持通配符。可以通过设置 enabled: false 单独禁用 nodenamespace 元数据的丰富化。
  • deployment:如果资源是 pod 并且是从 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 configmap 发出请求,以便通过请求 /api/v1/namespaces/kube-system/configmaps/kubeadm-config API 端点来丰富集群名称。
kube_client_options
(可选)可以为 Kubernetes 客户端配置其他选项。目前支持客户端 QPS 和突发,如果未设置,将使用 Kubernetes 客户端的默认 QPS 和突发。示例
      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']