一次 Kubernetes Pod 长期卡在 Terminating 状态的排查记录

Tue, 21 Jul 2026 07:00:00 +0800

一、问题背景

交易系统的核心 API 服务以 Deployment 形式跑在 Kubernetes 集群上，平时靠滚动更新（rolling update）发版，预期旧 Pod 在 30 秒优雅退出窗口内 shutdown、新 Pod 接管流量。某次例行发布（v2.3.1）触发滚动更新后，监控却开始报警：部分接口 5xx 比例陡增、响应超时。我们登陆集群一看，发现旧版本的 Pod 并没有按预期被清掉，而是大量堆积在 Terminating 状态，且 AGE 已经显示几十分钟，远超正常的 30 秒。节点资源被这些"死而不僵"的 Pod 占着，新 Pod 调度拥挤、部分直接 Pending，发布流水线也卡在"等待旧副本退出"。

二、故障现象

现场表现非常反直觉：

kubectl get pods 显示约 20 个旧 Pod 状态为 Terminating，AGE 高达 40 分钟以上，普通 kubectl delete pod xxx 没有任何反应。
kubectl describe pod 能看到 deletionTimestamp 已经设置，但 Events 最后一条基本是空或者停留在 “Killing” 之前，说明 APIServer 已经标记删除，Pod 对象却迟迟没被真正移除。
登上对应节点用 crictl ps / docker ps 查看，这些"Terminating"的容器进程其实还活着，端口也仍在监听——它们是"僵尸"，不是"已退出"。
新 Pod 大量 Pending：调度器认为节点资源已被占用（Terminating 的 Pod 依然计入 requests），有油却加不进新车。
线上出现诡异 5xx：这些旧容器进程明明还活着、端口还监听，但流量已经进不来——因为 Endpoint 控制器早把它们的 IP 从 Service 的 Endpoints 里摘掉了。于是造成"进程活着、服务已下线"的真空窗口，请求被导向尚未就绪的新 Pod 或干脆无可用后端。

三、排查过程

第一步，先确认 Pod 是不是真的进了删除态。kubectl get pod <p> -o jsonpath='{.metadata.deletionTimestamp}' 有值、{.metadata.deletionGracePeriodSeconds} 也有值，说明对象确实处于"标记删除但等待完成"阶段——Terminating 不等于"正在删"，而是"删不动"。

第二步，区分两类卡死：节点失联型 vs 节点健康型。先 kubectl get node 确认节点都是 Ready，节点上的 kubelet 正常工作，排除"kubelet 失联、apiserver 标记删除却没人在节点侧执行"的情况。既然节点健康，问题一定出在"节点侧删不掉"或"对象删除被门闩卡住"。

第三步，查 finalizer。kubectl get pod <p> -o jsonpath='{.metadata.finalizers}' 暴露了端倪：这批 Pod 上挂着团队自研控制器写入的自定义 finalizer（如 example.com/cleanup）。该 finalizer 约定由控制器在清理完外部资源后摘除，但当时控制器因上游依赖故障未能完成 reconcile，finalizer 永不清除——而 K8s 的删除语义规定：只要还有 finalizer 未清空，对象就永远停在 Terminating。这正是"删不动"的第一类根因。

第四步，查 preStop。即便没有 finalizer，仍有大量 Pod 卡着，于是对照 Pod spec 发现 lifecycle.preStop 里 exec 了一段脚本，脚本用 sleep 60 来"等待上游连接优雅排空"。但 Pod 的 terminationGracePeriodSeconds 只有 30 秒。这里有个常被忽略的时序：K8s 删除一个 Pod 时，先发 SIGTERM，然后执行 preStop，且 preStop 的耗时算在 grace period 之内，preStop 完成后才发 SIGKILL。也就是说，30 秒的窗口要先被 preStop 的 60 秒 sleep 吃掉，preStop 永远跑不完，SIGKILL 永远不会发出，容器进程就这么挂着——这是"删不动"的第二类根因，也是现场最致命的一条。

第五步，交叉验证流量真空。kubectl get endpoints <svc> 确认旧 Pod IP 已从 Endpoints 摘掉，解释了为何进程活着却 5xx：它们已被 Service 层逻辑"除名"，新请求不会再来，而新 Pod 又因为节点资源被僵尸占着起不来，形成发布中断的死锁。

四、解决方案

止血不能无脑 kubectl delete --force --grace-period=0。强制删除会绕过优雅退出与 finalizer 流程，对有状态卷/有外部资源绑定的 Pod 可能留下孤儿资源，且节点侧容器可能清理不干净。正确做法是分情况处理：

finalizer 残留、控制器已无法恢复：安全摘除 finalizer，让对象立即进入"可被真正删除"状态，kubelet 随即执行容器停止： kubectl patch pod <p> -p '{"metadata":{"finalizers":[]}}' --type=merge 对多个 Pod 可批量 kubectl get pods --field-selector=status.phase=Running | grep Terminating 后循环 patch。
preStop 死等：对已处于删除态的 Pod 无法再改 grace period。稳妥做法是先同样 patch 摘除 finalizer 跳过 preStop 阶段强制退出，同时修复镜像里的 preStop 脚本（去掉长 sleep、改为只做信号转发/快速关闭监听），再重新滚动发版。
清理完僵尸后，确认 kubectl get pods 无残留 Terminating，新 Pod 正常 Running 并重新加入 Endpoints，5xx 与 Pending 随即消失。

五、根因分析

本质是对 Pod 删除语义的理解偏差：设置了 deletionTimestamp 不等于立即删除，也不等于 30 秒后一定删除。一个 Pod 真正从集群消失，必须同时满足两个条件——（1）所有 finalizers 被清空；（2）节点侧 kubelet 停掉全部容器，而停止容器又要求 preStop 在 terminationGracePeriodSeconds 内完成、之后 SIGKILL 兜底。这两道"门闩"任一卡住，对象就永久停在 Terminating。其中 preStop 耗时计入 grace period 这一细节最易被忽视：很多人以为 SIGTERM 之后还有整整 30 秒，实际上这 30 秒要先被 preStop 占用。

六、预防措施

preStop 只做轻量操作：转发 SIGTERM、关闭监听端口、flush 日志，绝不 sleep 或等待外部依赖。如确有等待诉求，时长必须明显小于 terminationGracePeriodSeconds，并预留 SIGKILL 缓冲（建议 grace ≥ preStop 预估耗时 + 5s）。
finalizer 必须有控制器兜底：reconcile 逻辑要保证在异常/退出路径上也能清理 finalizer；给控制器加存活探针、健康监控与崩溃告警，避免"写 finalizer 的控制器自己先挂了"。
合理设置优雅退出窗口：默认 30s 不够长关闭的业务适当上调，但别无脑拉满——窗口越长，卡死时僵尸存活越久。
补齐监控：对持续 Terminating 超过 1 分钟的 Pod 告警；节点 NotReady 告警；控制器 Pod 状态告警；发布流水线在滚动后检查 Terminating 残留再判定成功。
发布规范：滚动更新显式配置 maxUnavailable / maxSurge，避免一次性驱逐过多副本放大影响面。

七、总结

Terminating 不是"正在删除"，而是"删除被卡住"。定位时先看两点：一是 finalizer 是否残留、控制器是否还活着；二是节点是否健康、preStop 是否超时吞噬了优雅窗口。止血优先用 patch 安全摘除 finalizer 让僵尸退场，根治则落在镜像里的 preStop 设计（轻量、不等待）与控制器对 finalizer 的兜底清理上。把删除语义吃透，发布才不会在"旧副本退不掉、新副本起不来"的死锁里翻车。

Terminating on Zero Day Notes