yutachaos/kube-job-notifier

Kubernetes Job 通知插件 Docker 镜像文档

1. 镜像概述和主要用途

1.1 概述

本 Docker 镜像封装了 Kubernetes Job 通知插件，是一个轻量级工具，用于监控 Kubernetes 集群中 Job 资源的生命周期事件（如创建、完成、失败、超时等），并将事件信息通过指定渠道发送通知。

1.2 主要用途

• 实时推送 Kubernetes Job 执行状态变更通知
• 集成多渠道通知机制，确保运维/开发人员及时获取 Job 结果
• 辅助监控 CI/CD 流水线、定时任务等场景下的 Job 执行情况

2. 核心功能和特性

3. 使用场景和适用范围

3.1 典型使用场景

• CI/CD 流水线监控：通知自动化部署 Job 的执行结果（如镜像构建成功/失败、应用发布状态）
• 定时任务告警：监控 CronJob 执行状态，对失败或超时的定时任务（如数据备份、报表生成）发送告警
• 关键业务 Job 跟踪：对核心业务 Job（如订单处理、数据同步）发送执行状态通知，确保业务连续性
• 开发测试反馈：通知开发人员测试 Job 的运行结果，加速问题定位

3.2 适用范围

• 环境要求：Kubernetes 集群（v1.16+），支持 RBAC 权限控制
• 网络要求：插件实例需能访问 Kubernetes API Server（集群内默认通过 https://kubernetes.default.svc:443 访问）及通知渠道服务（如 Slack API、SMTP 服务器等）
• 权限要求：需配置 ClusterRole 权限，允许监听 jobs 资源的 watch、list、get 操作

4. 使用方法和配置说明

4.1 镜像拉取

bash
docker pull docker.xuanyuan.run/[镜像仓库地址]/k8s-job-notifier:v1.0.0  # 替换为实际镜像仓库地址和版本

4.2 配置方式

插件支持两种配置方式：环境变量配置（适合简单场景）和 ConfigMap 配置（适合复杂场景，支持动态更新）。

4.2.1 环境变量配置

通过 docker run 或 Kubernetes Pod 的 env 字段传入环境变量，核心配置项如下（完整列表见 5.1 节）：

4.2.2 ConfigMap 配置

通过 ConfigMap 存储复杂配置（如多渠道详细参数、通知模板），示例 ConfigMap：

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: job-notifier-config
  namespace: kube-system
data:
  config.yaml: |
    notification:
      channels:
        - type: slack
          webhook_url: "https://hooks.slack.com/services/XXX"
          channel: "#job-alerts"
          username: "k8s-job-notifier"
        - type: webhook
          endpoint: "https://api.example.com/notify"
          method: "POST"
          headers:
            Content-Type: "application/json"
      trigger_conditions: ["failed", "timeout"]  # 仅失败或超时触发通知
    template:
      title: "Kubernetes Job {{.JobName}} ({{.Namespace}}) {{.Status}}"
      body: |
        Job 名称: {{.JobName}}
        命名空间: {{.Namespace}}
        状态: {{.Status}}
        开始时间: {{.StartTime}}
        持续时间: {{.Duration}}
        日志链接: {{.LogURL}}

4.3 部署示例

4.3.1 Docker 运行示例（单机测试用）

bash
docker run -d \
  --name k8s-job-notifier \
  -e KUBERNETES_API_URL="https://192.168.1.100:6443"  # 替换为实际 K8s API 地址  
  -e KUBERNETES_TOKEN="eyJhbGciOiJSUzI1NiIsImtpZCI..."  # 替换为具有 Job 访问权限的 Token  
  -e NOTIFICATION_CHANNELS="slack" \
  -e TRIGGER_CONDITIONS="failed,completed" \
  -e SLACK_WEBHOOK_URL="https://hooks.slack.com/services/XXX" \
  [镜像仓库地址]/k8s-job-notifier:v1.0.0

4.3.2 Kubernetes Deployment 部署示例（生产环境推荐）

步骤 1：创建 RBAC 权限配置
插件需通过 RBAC 获取监听 Job 资源的权限：

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: job-notifier-sa
  namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: job-notifier-role
rules:
- apiGroups: ["batch"]
  resources: ["jobs"]
  verbs: ["watch", "list", "get"]  # 监听 Job 事件需 watch/list/get 权限
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: job-notifier-binding
subjects:
- kind: ServiceAccount
  name: job-notifier-sa
  namespace: kube-system
roleRef:
  kind: ClusterRole
  name: job-notifier-role
  apiGroup: rbac.authorization.k8s.io

步骤 2：创建 Deployment
使用 ConfigMap 配置（需先创建 4.2.2 节的 ConfigMap）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: job-notifier
  namespace: kube-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: job-notifier
  template:
    metadata:
      labels:
        app: job-notifier
    spec:
      serviceAccountName: job-notifier-sa  # 关联 RBAC 权限
      containers:
      - name: job-notifier
        image: docker.xuanyuan.run/[镜像仓库地址]/k8s-job-notifier:v1.0.0
        volumeMounts:
        - name: config-volume
          mountPath: /etc/job-notifier/config.yaml
          subPath: config.yaml  # 挂载 ConfigMap 中的配置文件
        resources:
          limits:
            cpu: 100m
            memory: 256Mi
          requests:
            cpu: 50m
            memory: 128Mi
      volumes:
      - name: config-volume
        configMap:
          name: job-notifier-config  # 关联 4.2.2 节创建的 ConfigMap

4.4 验证部署

1. 检查 Pod 状态：

   bash
   kubectl get pods -n kube-system -l app=job-notifier
   

   确保 Pod 状态为 Running。

2. 查看日志：

   bash
   kubectl logs -n kube-system <pod-name> -f
   

   确认日志中无错误信息，且包含 "Successfully connected to Kubernetes API" 等初始化成功日志。

3. 测试通知：
   创建一个测试 Job 并故意使其失败（如执行 exit 1），检查通知渠道是否收到告警。

5. 配置参数详细说明

5.1 核心环境变量配置

5.2 通知渠道配置参数

5.2.1 Slack 渠道

5.2.2 Webhook 渠道

6. 注意事项

1. RBAC 权限：插件需配置 ClusterRole 权限以监听 Job 资源，参考 4.3.2 节的 RBAC 配置。
2. 网络策略：若集群启用网络策略，需允许插件 Pod 访问 Kubernetes API Server（443 端口）及通知渠道服务（如 Slack API、Webhook 地址等）。
3. 版本兼容性：支持 Kubernetes v1.16+，低版本集群可能存在 API 兼容性问题（如 batch/v1 Job 资源版本差异）。
4. 高可用：生产环境建议部署 2 副本（通过 Deployment replicas: 2），避免单点故障。
5. 敏感信息：通知渠道密钥（如 Slack Webhook URL）建议通过 Secret 存储，而非明文配置（可通过 envFrom 挂载 Secret）。