Filebeat 在 Kubernetes 环境中采集日志时获取 Pod 名称与 Namespace 的实现与机制说明

在 Kubernetes 环境下，通过 Filebeat 采集容器日志并将其转发至日志平台（如 Kafka、Elasticsearch）是一种常见的日志解决方案。为了实现日志的可观测性与可溯源性，日志记录中必须包含运行该容器的 Pod 名称以及 Namespace 等关键信息。本文将详细介绍 Filebeat 在采集 Kubernetes 日志时，如何实现对 Pod 名称与 Namespace 的获取、注入与输出。

一、采集 Kubernetes 元数据的重要性

在 Kubernetes 集群中，同一应用可能会以多副本的方式部署，不同环境的服务也可能使用相同的日志格式。如果日志中不包含 Pod 名称、Namespace 等元数据，日志难以实现以下能力：

1. 精确定位问题 Pod  当应用异常时，需要快速查明是哪个 Pod 出现问题。

2. 区分不同环境的日志  如 dev、test、prod 共享 Kafka Topic 或 Elasticsearch Index 时，缺乏 Namespace 会导致日志混淆。

3. 支持自动化报警和索引策略  监控系统可基于 Namespace、Pod 名称实现多维度告警。

因此，对于生产级日志平台而言，采集 Kubernetes 元数据是必要步骤。

二、Filebeat 的元数据采集机制

Filebeat 在监听 K8s 中的容器日志时，会借助其内置的 add_kubernetes_metadata 处理器，通过以下方式关联容器信息：

1. 通过文件路径获取容器 ID  K8s 将容器日志写入 /var/log/containers/xxx.log，文件名中包含容器 ID。

2. 通过 Kubelet API 或 Downward API 查询元数据  Filebeat 会调用 K8s API 查找该容器 ID 对应的 Pod 资源。

3. 将 Pod 名称、Namespace、Labels 等写入日志事件中  Filebeat 自动添加这些字段，或允许用户手动配置自定义字段。

三、通过 fields 和环境变量写入 Pod 与 Namespace 信息

在某些部署场景中（如使用 DaemonSet 收集应用容器日志），用户可通过 Kubernetes 的 Downward API 将 Pod 名称和 Namespace 注入到 Filebeat Pod 的环境变量中，再由 Filebeat 写入到日志事件。

示例 Filebeat 配置：

 filebeat.inputs:
 - type: filestream
   paths:
     - /var/log/*
   encoding: utf-8
   fields:
     module_name: "${MODULE_NAME}"
     module_namespace: "${POD_NAMESPACE}"
   parsers:
     - multiline:
         type: pattern
         pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}\ [0-9]{2}:[0-9]{2}:[0-9]{2}'
         negate: true
         match: after

在 Kubernetes 部署文件中，可将 Pod 名称和 Namespace 通过环境变量注入：

 env:
   - name: POD_NAMESPACE
     valueFrom:
       fieldRef:
         fieldPath: metadata.namespace
   - name: POD_NAME
     valueFrom:
       fieldRef:
         fieldPath: metadata.name

这样 Filebeat 采集的每条日志都会自动具备：

 fields.module_namespace: your-namespace
 fields.module_name: your-module

便于后续在 Kafka 或 Elasticsearch 中基于这些字段进行查询、分流、索引或告警。

四、结合 Kubernetes Metadata Processor 获取完整信息

除了 Downward API 注入的字段，Filebeat 还支持更丰富的自动元数据采集方式，即 add_kubernetes_metadata 处理器。

示例：

 processors:
   - add_kubernetes_metadata:
       in_cluster: true

该处理器可以自动添加：

• pod.name

• pod.uid

• namespace

• labels

• annotations

• container.name

• node.name

这使得日志数据具有更高的可观测性，对于后续构建可视化平台或排查问题非常友好。

五、元数据采集后的输出与使用方式

在输出层（如 Kafka、ES），Pod 名称与 Namespace 会作为普通字段写入日志消息中。  典型输出示例（Kafka）：

 {
   "message": "2025-12-12 Some business log...",
   "fields": {
     "module_namespace": "dev",
     "module_name": "factory-service"
   },
   "kubernetes": {
     "pod": {
       "name": "factory-service-6d4c5d78fc-abcde"
     },
     "namespace": "dev"
   }
 }

在可视化平台（如 Kibana）中，你可以轻松实现：

• 按 Pod 查询日志

• 按 Namespace 分索引

• 按应用 Labels 进行聚合

• 按节点(Node)筛选问题

大幅提升日志排查效率。

六、总结

Filebeat 在 Kubernetes 环境中采集 Pod 名称与 Namespace 的实现依赖多种机制，包括：

1. Kubernetes Downward API 注入环境变量

2. Filebeat fields 字段注入，适用于自定义字段

3. add_kubernetes_metadata 处理器自动解析容器 ID 并丰富元数据

4. 通过 Kafka/ES 输出后保留这些信息，便于日志分析

通过以上方式，可以确保日志具备准确的运行环境信息，为生产环境的故障定位、监控告警、数据分析提供强有力的支持。