K8s-Event-Alerter-Pod异常状态告警方案

一、项目背景

1.1 问题

Kubernetes 集群中,Pod 经常因为各种原因陷入异常状态:

这些异常如果不能及时发现,会导致服务中断。传统做法依赖人工巡检或 Prometheus 告警规则,前者不及时,后者配置复杂且缺乏灵活的规则管理能力。

1.2 解决方案:K8s Event Alerter

通过 Kubernetes CRD 定义告警规则,Controller Watch Pod 事件实时检测异常,并通过飞书/钉钉/企业微信 Webhook 发送告警通知:

二、架构设计

2.1 整体架构

graph TD
    A[K8s API Server] -->|Pod status change / Watch| B[controller-runtime Watch
Pod + PodAlertRule] B -->|Event → findRulesForPod
→ enqueue matching rules| C[PodAlertRuleReconciler] C --> C1["1. Fetch PodAlertRule CR"] C1 --> C2["2. listMatchingPods
(namespace + labels + namePattern + maxPodAge)"] C2 --> C3["3. checker.Check(pod, alertTypes) → AnomalyResult"] C3 --> C4["4. 恢复检测:移除已恢复异常的 annotation"] C4 --> C5["5. 告警去重:检查 Pod annotation,有标记则跳过"] C5 --> C6["6. Dispatcher.Dispatch → 发送到所有 Webhook"] C6 --> W1[FeishuNotifier
interactive card, HMAC-SHA256 sign in body] C6 --> W2[DingtalkNotifier
markdown, HMAC-SHA256 sign in URL] C6 --> W3[WecomNotifier
markdown, no sign] C5 --> C7["7. Patch Pod annotation 标记已告警"] C7 --> C8["8. Metrics 打点"] C8 --> C9["9. Update Status + RequeueAfter"]

2.2 事件驱动模型

Controller 同时 Watch 两种资源:

func (r *PodAlertRuleReconciler) SetupWithManager(mgr ctrl.Manager) error {
    return ctrl.NewControllerManagedBy(mgr).
        For(&alertv1alpha1.PodAlertRule{}).
        Watches(&corev1.Pod{}, handler.EnqueueRequestsFromMapFunc(r.findRulesForPod)).
        Named("podalertrule").
        Complete(r)
}

对于时间阈值类异常(Pending/Failed 还未到阈值),计算剩余时间后返回 RequeueAfter,到期精确复查。

2.3 项目结构

k8s-event-alerter/
├── api/v1alpha1/                    # CRD 类型定义
│   ├── podalertrule_types.go        # PodAlertRule Spec/Status
│   ├── groupversion_info.go         # GVK 注册
│   └── zz_generated.deepcopy.go
├── internal/
│   ├── controller/
│   │   └── podalertrule_controller.go  # Reconciler 核心逻辑 + Annotation 去重
│   ├── checker/
│   │   └── checker.go               # Pod 异常检测(4 种策略)
│   ├── notifier/
│   │   ├── notifier.go              # Notifier 接口 + Dispatcher
│   │   ├── feishu.go                # 飞书通知实现
│   │   ├── dingtalk.go              # 钉钉通知实现
│   │   └── wecom.go                 # 企业微信通知实现
│   └── metrics/
│       └── metrics.go               # Prometheus 指标
├── cmd/main.go                      # 入口
├── chart/                           # Helm chart
├── config/                          # Kubebuilder kustomize 配置
├── instances/                       # 示例 CR
├── Dockerfile
├── Makefile
└── go.mod

三、CRD 设计:PodAlertRule

3.1 完整示例

apiVersion: alert.k8seventalerter.io/v1alpha1
kind: PodAlertRule
metadata:
  name: watch-pending-and-evicted
spec:
  # 监控的 namespace(空=全集群)
  namespaces:
    - blueking

  # Pod label 筛选(可选)
  podSelector:
    matchLabels:
      app: my-service

  # Pod 名称正则(可选)
  namePattern: "^my-service-.*"

  # 告警类型及阈值
  alertTypes:
    - type: Pending
      threshold: "5m"       # Pending 超过 5 分钟触发
    - type: Evicted          # 驱逐立即触发
    - type: ImagePullBackOff # 镜像拉取失败立即触发
    - type: Failed
      threshold: "10m"      # Failed 超过 10 分钟触发

  # 多 Webhook 通知
  webhooks:
    - type: feishu
      url: "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
      secret: "optional-signing-secret"
    - type: dingtalk
      url: "https://oapi.dingtalk.com/robot/send?access_token=yyy"
      secret: "optional-signing-secret"
    - type: wecom
      url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=zzz"

  # 告警级别
  severity: warning      # info / warning / critical

  # Pod 最大年龄(过滤历史 Pod)
  maxPodAge: "1h"

3.2 CRD 核心字段

字段 类型 默认值 说明
namespaces []string 空(全集群) 监控的 namespace 列表
podSelector LabelSelector nil Pod label 筛选
namePattern string "" Pod 名称正则
alertTypes []AlertTypeConfig 必填 告警类型及阈值
webhooks []WebhookConfig 必填 通知 Webhook 列表
severity string warning 告警级别(info/warning/critical)
maxPodAge Duration 1h Pod 最大年龄,超过的 Pod 被忽略

3.3 四种告警类型

类型 触发条件 threshold 语义
Pending Pod phase=Pending 且超过 threshold 必须,默认 5m
Evicted Pod phase=Failed 且 reason=Evicted 忽略,立即触发
ImagePullBackOff 容器 waiting reason ∈ 忽略,立即触发
Failed Pod phase=Failed 且 reason≠Evicted 且超过 threshold 必须,默认 5m

3.4 Printer Columns

kubectl get par
# NAME                         SEVERITY   ALERTSSENT   AGE
# watch-pending-and-evicted    warning    15           2h
# watch-image-pull-failures    critical   3            2h

四、多平台 Webhook 通知

4.1 架构

type Notifier interface {
    Send(ctx context.Context, webhook alertv1alpha1.WebhookConfig, payload AlertPayload) error
}

type Dispatcher struct {
    notifiers map[alertv1alpha1.WebhookType]Notifier
}

Dispatcher 遍历规则配置的所有 Webhook,按 type 分发到对应 Notifier,依次发送。

4.2 三种平台实现差异

特性 飞书 钉钉 企业微信
消息格式 Interactive Card(富文本卡片) Markdown Markdown
类型字段 msg_type msgtype msgtype
签名方式 HMAC-SHA256,sign 放请求体 HMAC-SHA256,sign 放 URL 参数 无签名
时间戳单位 秒 毫秒 N/A
HMAC key stringToSign 本身 secret 字符串 N/A
频率限制 100 次/分钟 20 次/分钟 20 次/分钟

4.3 签名实现

飞书:

timestamp := fmt.Sprintf("%d", time.Now().Unix())
stringToSign := timestamp + "\n" + secret
mac := hmac.New(sha256.New, []byte(stringToSign))
mac.Write([]byte{})
sign := base64.StdEncoding.EncodeToString(mac.Sum(nil))
// sign 和 timestamp 放入请求体

钉钉:

timestamp := time.Now().UnixMilli()
stringToSign := fmt.Sprintf("%d\n%s", timestamp, secret)
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(stringToSign))
sign := url.QueryEscape(base64.StdEncoding.EncodeToString(mac.Sum(nil)))
// sign 和 timestamp 追加到 URL 参数

五、告警去重

5.1 基于 Pod Annotation 的去重

使用 Pod Annotation 作为去重标记,每种异常类型只告警一次,异常恢复后自动清除标记:

Reconcile 每个 Pod:
  activeAnomalies := checker.Check(pod, alertTypes)

  // 1. 恢复检测:移除已恢复异常的 annotation
  for each annotation matching "alert.k8seventalerter.io/alerted-*":
    if alertType NOT in activeAnomalies:
      → patch pod: remove annotation
      → log: "anomaly recovered"

  // 2. 告警发送:只处理未标记的活跃异常
  for each anomaly in activeAnomalies:
    if pod has annotation for this type:
      → skip (已告警)
    else:
      → dispatch alert
      → patch pod: add annotation

5.2 恢复检测

异常类型 恢复条件 恢复后行为
Pending Pod phase 不再是 Pending 移除 alerted-Pending annotation
ImagePullBackOff 所有容器不再处于 ImagePullBackOff/ErrImagePull 移除 alerted-ImagePullBackOff annotation
Evicted 终态,不会恢复 annotation 跟随 Pod 生命周期自然消失
Failed 终态,不会恢复 annotation 跟随 Pod 生命周期自然消失

5.3 设计取舍

设计 选择 原因
存储 Pod Annotation 持久化在 etcd,Controller 重启不丢状态
去重粒度 每种异常类型只告警一次 彻底消除重复告警
恢复感知 自动移除 annotation 异常复发时能重新告警
RBAC pods 需要 patch 权限 用于写入/移除 annotation

六、可观测性

6.1 Prometheus 指标

指标 类型 标签 说明
k8seventalerter_alerts_sent_total Counter rule, namespace, alert_type, severity 发送的告警总数
k8seventalerter_anomalies_detected_total Counter rule, namespace, alert_type 检测到的异常总数(含跳过)
k8seventalerter_alerts_skipped_total Counter rule, namespace, alert_type 因已有 annotation 标记而跳过的告警数
k8seventalerter_check_duration_seconds Histogram rule 每条规则的检查耗时

6.2 Status 子资源

kubectl get par test-rule -o jsonpath='{.status}'
# {"alertsSent":15,"lastCheckTime":"2026-09-10T07:30:12Z"}

6.3 健康检查

端点 端口 说明
/healthz 8081 存活探针
/readyz 8081 就绪探针
/metrics 8080 Prometheus 指标

七、安全机制

机制 说明
最小 RBAC get/list/watch pods + patch(用于 annotation 去重标记),get/list/watch podalertrules
只读文件系统 readOnlyRootFilesystem: true
非 root 运行 UID 65532
drop ALL capabilities 无特权能力
seccomp RuntimeDefault 限制系统调用
Leader Election 多副本防重复告警

八、技术选型

组件 选择 理由
脚手架 Kubebuilder v4 K8s 控制器标准工具链
语言 Go 1.24 controller-runtime 原生
框架 controller-runtime v0.21 CRD/informer/metrics 内置
Pod 发现 Watch + RequeueAfter 事件驱动 + 精确阈值检查
去重 Pod Annotation 持久化在 etcd,重启不丢状态,恢复感知
指标 prometheus/client_golang K8s 生态标准
部署 Helm chart 标准 K8s 部署方式

九、部署方式

9.1 Helm 部署

helm upgrade --install k8s-event-alerter chart/ \
  --namespace alerter-system \
  --create-namespace

9.2 关键 values 配置

replicaCount: 1
image:
  repository: dockerhub-registry.cn-hangzhou.cr.aliyuncs.com/dz-platform/k8s-event-alerter
  tag: "latest"
  pullPolicy: IfNotPresent
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi
leaderElection:
  enabled: true
metrics:
  enabled: true
  port: 8080
healthProbe:
  port: 8081

9.3 应用规则

kubectl apply -f instances/watch-pending-and-evicted.yaml
kubectl apply -f instances/watch-image-pull-failures.yaml

十、验证

# 查看规则
kubectl get par
# NAME                         SEVERITY   ALERTSSENT   AGE
# watch-pending-and-evicted    warning    15           2h
# watch-image-pull-failures    critical   3            2h

# 查看规则状态
kubectl get par watch-pending-and-evicted -o jsonpath='{.status}'
# {"alertsSent":15,"lastCheckTime":"2026-09-10T07:30:12Z"}

# 查看指标
kubectl exec -n alerter-system deploy/k8s-event-alerter -- wget -qO- http://localhost:8080/metrics | grep k8seventalerter