xingse/event-forwarder-gelf

event-forwarder-gelf Docker镜像文档

镜像概述

event-forwarder-gelf是一个轻量级Docker镜像，专门用于将Kubernetes集群中的事件实时转发到支持Graylog扩展日志格式(GELF)的日志系统（如Graylog）。通过标准化的GELF格式，实现Kubernetes事件的集中收集、存储和分析，帮助管理员监控集群状态、排查故障及进行审计。

核心功能与特性

• Kubernetes事件采集：实时监听并采集Kubernetes集群中的各类事件（如Pod调度、节点状态变化、资源创建/删除等）
• GELF格式转换：将Kubernetes原生事件格式转换为Graylog Extended Log Format (GELF)，支持结构化日志
• 灵活配置：可通过环境变量自定义转发目标、日志级别、事件过滤规则等
• 轻量级设计：基于精简基础镜像，资源占用低，适合在Kubernetes集群中作为DaemonSet或Deployment运行
• Kubernetes API集成：通过Kubernetes API或kubeconfig文件实现集群访问，支持RBAC权限控制

使用场景与适用范围

• Kubernetes集群监控：集中收集集群事件，辅助监控系统（如Prometheus+Grafana）构建完整可观测性平台
• 故障排查：实时转发关键事件至日志系统，便于快速定位集群异常（如Pod启动失败、节点资源不足等）
• 审计与合规：记录资源变更事件，满足合规性要求（如跟踪配置修改、权限变更等操作）
• 多集群日志集中：统一收集多Kubernetes集群事件，实现跨集群日志管理

使用方法与配置说明

前置条件

• 运行环境：Kubernetes集群（1.16+）
• 目标系统：支持GELF输入的日志系统（如Graylog、Logstash等）
• 权限要求：容器需具备访问Kubernetes API的权限（通过Service Account或kubeconfig）

Docker Run 示例

bash
docker run -d \
  --name event-forwarder-gelf \
  -e GELF_ENDPOINT=udp://graylog.example.com:12201 \
  -e KUBE_CONFIG=/etc/kubeconfig \
  -v /path/to/kubeconfig:/etc/kubeconfig \
  xingse/event-forwarder-gelf:latest

Kubernetes Deployment 示例

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: event-forwarder-gelf
  namespace: monitoring
spec:
  replicas: 1
  selector:
    matchLabels:
      app: event-forwarder-gelf
  template:
    metadata:
      labels:
        app: event-forwarder-gelf
    spec:
      serviceAccountName: event-reader
      containers:
      - name: event-forwarder-gelf
        image: xingse/event-forwarder-gelf:latest
        env:
        - name: GELF_ENDPOINT
          value: "udp://graylog-service:12201"
        - name: LOG_LEVEL
          value: "info"
        - name: NAMESPACE_FILTER
          value: "default,monitoring"  # 可选，仅转发指定命名空间事件

环境变量配置

RBAC权限配置（Kubernetes内运行）

若在Kubernetes集群内运行，需创建具备事件读取权限的Service Account：

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: event-reader
  namespace: monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: event-reader-role
rules:
- apiGroups: [""]
  resources: ["events"]
  verbs: ["get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: event-reader-binding
subjects:
- kind: ServiceAccount
  name: event-reader
  namespace: monitoring
roleRef:
  kind: ClusterRole
  name: event-reader-role
  apiGroup: rbac.authorization.k8s.io

常见问题

• Q: 如何验证事件是否成功转发？
  A: 可通过设置LOG_LEVEL=debug查看转发日志，或在目标GELF系统中搜索Kubernetes事件相关条目。

• Q: 容器无法访问Kubernetes API怎么办？
  A: 确保Service Account已正确配置RBAC权限，或通过KUBE_CONFIG挂载有效的kubeconfig文件。

• Q: 是否支持TLS加密传输？
  A: 支持通过https://前缀的GELF_ENDPOINT使用TLS加密（需目标系统支持GELF over HTTPS）。