› ›

添加 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 的元数据进行丰富。

有关可用索引器和匹配器以及一些示例的更多信息，请参阅索引器和匹配器。

示例

编辑

当 Elastic Agent 作为 Kubernetes 中的 Pod 运行时，此配置启用该处理器。

  - add_kubernetes_metadata:
      # Defining indexers and matchers manually is required for {beatname_lc}, for instance:
      #indexers:
      #  - ip_port:
      #matchers:
      #  - fields:
      #      lookup_fields: ["metricset.host"]
      #labels.dedot: true
      #annotations.dedot: true

此配置在作为 Kubernetes 节点上的进程运行的 Elastic Agent 上启用该处理器。

  - 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: $Fleet and Elastic Agent Guide [8.17]/.kube/config
      # Defining indexers and matchers manually is required for {beatname_lc}, for instance:
      #indexers:
      #  - ip_port:
      #matchers:
      #  - fields:
      #      lookup_fields: ["metricset.host"]
      #labels.dedot: true
      #annotations.dedot: true

此配置禁用默认索引器和匹配器，然后启用不同的索引器和匹配器。

  - 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

配置设置

编辑

Elastic Agent 处理器在采集管道之前执行，这意味着它们处理的是原始事件数据，而不是发送到 Elasticsearch 的最终事件。有关相关限制，请参阅使用处理器有哪些限制？

名称	必需	默认	描述
`host`	否		在无法准确检测到 Elastic Agent 的情况下（例如，在主机网络模式下运行 Elastic Agent 时），将 Elastic Agent 的范围限定到的节点。
`scope`	否	`node`	处理器应在节点级别（`node`）还是在整个集群级别（`cluster`）具有可见性。
`namespace`	否		从中收集元数据的命名空间。如果未指定命名空间，则从所有命名空间收集元数据。
`add_resource_metadata`	否		用于向事件添加额外元数据的过滤器和配置。此设置接受以下设置： `node` 或 `namespace`：来自节点和命名空间的额外元数据的标签和注释过滤器。默认情况下，包括所有标签，但不包括注释。要更改默认行为，您可以设置 `include_labels`、`exclude_labels` 和 `include_annotations`。这些设置在存储需要特殊处理以避免重载存储输出的标签和注释时很有用。通过结合使用 `use_regex_include: true` 和 `include_labels` 以及通过结合使用 `use_regex_exclude: true` 和 `exclude_labels`，这些设置中支持通配符。要单独关闭 `node` 或 `namespace` 元数据的丰富，请设置 `enabled: false`。 `deployment`：如果资源是 `pod`，并且它是从 `deployment` 创建的，则默认情况下不会添加 deployment 名称。要启用此行为，请设置 `deployment: true`。 `cronjob`：如果资源是 `pod`，并且它是从 `cronjob` 创建的，则默认情况下不会添加 cronjob 名称。要启用此行为，请设置 `cronjob: true`。展开以查看示例 add_resource_metadata: namespace: include_labels: ["namespacelabel1"] # use_regex_include: false # use_regex_exclude: false # exclude_labels: ["namespacelabel2"] #labels.dedot: true #annotations.dedot: true node: # use_regex_include: false include_labels: ["nodelabel2"] include_annotations: ["nodeannotation1"] # use_regex_exclude: false # exclude_annotations: ["nodeannotation2"] #labels.dedot: true #annotations.dedot: true deployment: true cronjob: true
`kube_config`	否	`KUBECONFIG` 环境变量（如果存在）	用作 Kubernetes 客户端配置的配置文件。
`kube_client_options`	否		Kubernetes 客户端的其他配置选项。目前支持客户端 QPS 和 burst。如果未配置此设置，则使用 Kubernetes 客户端的默认 QPS 和 burst。展开以查看示例 kube_client_options: qps: 5 burst: 10
`cleanup_timeout`	否	`60 秒`	停止容器运行配置之前的不活动时间。
`sync_period`	否		列出历史资源的超时时间。
`labels.dedot`	否	`true`	是否将标签中的点 (`.`) 替换为下划线 (`_`)。 `annotations.dedot`

索引器和匹配器

编辑

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

索引器
匹配器

索引器

编辑

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

可用的索引器有：

container: 使用其容器的 ID 识别 Pod 元数据。
ip_port: 使用其 IP 及其公开端口的组合来标识 Pod 元数据。使用此索引器时，对于 Pod 的所有容器公开的每个端口，都会使用 ip:port 的组合来标识元数据。ip 是 Pod 的 IP。
pod_name: 使用其命名空间和名称作为 namespace/pod_name 来标识 Pod 元数据。
pod_uid: 使用 Pod 的 UID 标识 Pod 元数据。

匹配器

编辑

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

可用的匹配器有：

field_format

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

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

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

- 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 进行查找，这是它在事件中找到的第一个。

- 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

（可选）容器日志的基本路径。如果未指定，则使用 Agent 运行所在平台的默认日志路径：对于 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 匹配器，agent 的输入路径必须是 logs_path 配置设置中定义的目录的子目录。

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

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

- 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 添加标签 »