K8s-Event-Alerter-Pod异常状态告警方案
一、项目背景
1.1 问题
Kubernetes 集群中,Pod 经常因为各种原因陷入异常状态:
- Pending — 资源不足或调度约束导致 Pod 长时间无法调度
- Evicted — 节点资源压力(磁盘、内存)触发 Pod 驱逐
- ImagePullBackOff — 镜像仓库不可达、镜像不存在或认证失败
- Failed — 容器启动失败、OOM、退出码非零等
这些异常如果不能及时发现,会导致服务中断。传统做法依赖人工巡检或 Prometheus 告警规则,前者不及时,后者配置复杂且缺乏灵活的规则管理能力。
1.2 解决方案:K8s Event Alerter
通过 Kubernetes CRD 定义告警规则,Controller Watch Pod 事件实时检测异常,并通过飞书/钉钉/企业微信 Webhook 发送告警通知:
- 规则驱动:CRD 声明式配置,支持 namespace/label/名称正则多维度筛选
- 事件驱动:Watch Pod 状态变更即触发检查,时间阈值类异常使用 RequeueAfter 延迟复查
- 多平台通知:同一规则可配置多个 Webhook,支持飞书、钉钉、企业微信三种平台
- 告警去重:基于 Pod Annotation 标记,每种异常只告警一次,异常恢复后自动清除标记
- 历史过滤:maxPodAge 过滤历史 Pod,避免误报
二、架构设计
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)
}
- Pod 状态变更 →
findRulesForPod()找到所有匹配该 Pod 的 PodAlertRule → 入队 Reconcile - PodAlertRule 变更 → 直接触发自身 Reconcile
对于时间阈值类异常(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 作为去重标记,每种异常类型只告警一次,异常恢复后自动清除标记:
- Annotation 前缀:
alert.k8seventalerter.io/alerted- - 示例:
alert.k8seventalerter.io/alerted-Pending: watch-pending-rule
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