grafana/kubernetes-diff-logger

Kubernetes对象变更差异监控工具

镜像概述和主要用途

本镜像封装了一个轻量级应用，旨在监控Kubernetes集群中的对象（如Pod、Deployment、Service等），并在这些对象发生创建、更新或删除等变更时，自动捕获并记录变更前后的差异信息。主要用途包括跟踪Kubernetes资源的变更历史、支持配置审计、辅助故障排查及检测配置漂移等场景。

核心功能和特性

核心功能

• 实时监控指定类型的Kubernetes对象（支持Pod、Deployment、StatefulSet、ConfigMap、Secret等常见资源类型）
• 检测对象的创建、更新、删除事件，并生成变更前后的结构化差异日志
• 支持自定义监控范围（如指定命名空间、对象标签等）

特性

• 轻量级：应用体积小，资源占用低，适合在资源受限的Kubernetes环境中部署
• 易于集成：通过Kubernetes API与集群原生集成，无需额外依赖
• 灵活配置：支持通过环境变量或配置文件自定义监控规则和日志输出格式
• 标准化日志：默认输出JSON格式日志，便于与日志收集系统（如ELK、Promtail）集成

使用场景和适用范围

适用场景

• 变更审计：记录Kubernetes资源的所有修改操作，满足合规性要求
• 故障排查：当集群出现异常时，通过查看变更历史快速定位问题根源
• 配置漂移检测：监控生产环境资源配置是否与预期一致，及时发现未授权修改
• 开发/测试环境：跟踪资源修改记录，辅助团队协作和问题复现

适用范围

• 运行Kubernetes v1.16+的集群环境
• 需要对Kubernetes资源变更进行跟踪的团队或组织
• 具备Kubernetes API访问权限的部署环境（集群内或集群外）

使用方法和配置说明

前置条件

• 部署环境需具备访问Kubernetes API的权限（集群内部署可通过ServiceAccount实现，集群外部署需提供kubeconfig文件）
• Docker引擎或容器运行时环境

Docker部署示例

集群内部署（推荐）

在Kubernetes集群内通过Pod部署，利用ServiceAccount获取API访问权限：

yaml
apiVersion: v1
kind: Pod
metadata:
  name: k8s-object-diff-watcher
  namespace: default
spec:
  serviceAccountName: diff-watcher-sa  # 需提前创建具有适当权限的ServiceAccount
  containers:
  - name: diff-watcher
    image: [镜像名称]  # 替换为实际镜像地址
    env:
    - name: WATCH_OBJECT_TYPES
      value: "pod,deployment,configmap"  # 监控的对象类型，逗号分隔
    - name: WATCH_NAMESPACES
      value: "default,kube-system"  # 监控的命名空间，逗号分隔（留空表示所有命名空间）
    - name: LOG_FORMAT
      value: "json"  # 日志格式，可选json或text
    - name: LOG_LEVEL
      value: "info"  # 日志级别，可选debug/info/warn/error

集群外部署

通过本地Docker运行，使用kubeconfig文件访问远程Kubernetes集群：

bash
docker run -d \
  --name k8s-diff-watcher \
  -v /path/to/local/kubeconfig:/app/kubeconfig \  # 挂载本地kubeconfig文件
  -e KUBE_CONFIG_PATH=/app/kubeconfig \  # 指定kubeconfig路径
  -e WATCH_OBJECT_TYPES="deployment,statefulset" \
  -e WATCH_NAMESPACES="prod" \
  -e LOG_FORMAT="text" \
  [镜像名称]  # 替换为实际镜像地址

配置参数说明

环境变量配置

日志输出示例

JSON格式日志（默认）

json
{
  "timestamp": "2023-10-01T12:34:56Z",
  "event_type": "update",
  "object_type": "deployment",
  "object_name": "nginx-deploy",
  "namespace": "default",
  "diff": {
    "spec.replicas": {
      "old_value": 2,
      "new_value": 3
    }
  },
  "resource_version": "123456"
}

文本格式日志

2023-10-01T12:34:56Z [INFO] Update event detected: deployment/nginx-deploy (namespace: default)
Diff:
  spec.replicas: 2 → 3
Resource version: 123456

部署权限要求

在Kubernetes集群内部署时，需为应用的ServiceAccount绑定以下最小权限的ClusterRole：

yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: k8s-diff-watcher-role
rules:
- apiGroups: ["*"]
  resources: ["pods", "deployments", "statefulsets", "configmaps", "secrets", "services"]  # 根据监控对象类型调整
  verbs: ["get", "watch", "list"]  # 仅需读取权限