K8s 滚动更新卡在 Terminating：preStop 与 terminationGracePeriodSeconds 配错导致 Pod 优雅退出超时的排查与修正

一、现象：一次常规发布，2 个 Pod 卡 Terminating 90 秒，用户侧 3 个请求 502

上周三下午 15:40，我们给一个 Go 服务（Kubernetes 1.28.9，containerd 1.6.24，Deployment 副本数 12）做了一次滚动更新。发布过程本身没问题，但收尾阶段 kubectl get pod 里始终有 2 个旧 Pod 挂在 Terminating 状态，超过 90 秒还没消失，最后被 kubelet 强杀（SIGKILL）。监控上对应时间点出现 3 个 in-flight 请求 502，告警报「发布窗口错误率 0.8%」。

一开始我以为是网络或 kubelet 抽风，翻 kubectl describe pod 只看到一行的 Terminating，没有任何 hint。这种「Pod 卡死不退出」在生产里很常见，但根因几乎都落在优雅退出这条链路上，而不是网络。

二、原理：kubelet 优雅退出到底按什么顺序走

很多人以为「Pod 退出 = 收到 SIGTERM 就结束」，其实 kubelet 对 Terminating 的 Pod 执行的是一个有明确时序的固定流程：

1. 从Endpoints/EndpointSlice 里摘除该 Pod（让 Service 不再往它发流量）；
2. 执行 lifecycle.preStop（如果配了）；
3. 向容器主进程（PID 1）发 SIGTERM；
4. 等待 terminationGracePeriodSeconds（默认 30s）；
5. 超时还没退 → 发 SIGKILL 强杀。

关键点有两个，也是绝大多数「卡 Terminating」的根因：

• preStop 是同步阻塞的，并且它消耗的是同一个 grace period 预算。也就是说 preStop 里 sleep 多久，就从 terminationGracePeriodSeconds 里扣多久。如果 preStop sleep 35s、grace 只有默认 30s，那 SIGTERM 发出去时预算已经耗尽，进程根本没机会做 graceful shutdown，直接被打 SIGKILL——这就是为什么你看到「连接被硬断、in-flight 请求 502」。
• 摘除 Endpoint 和发 SIGTERM 之间没有「流量真的停了」的保证。摘 endpoint 只是「不再新增路由」，LB/客户端侧仍可能有 keep-alive 连接或 DNS 缓存指向旧 Pod，这些存量连接在 SIGTERM 后如果没有被正确 drain，就会 5xx。

三、具体做法：一段可直接复现的配置

下面是我最后落地的完整片段（Go 服务 + nginx ingress 场景），三个值要联动调，不能只改一个：

spec:
  # 默认 30s 太短，给 preStop + 业务 graceful shutdown 留足预算
  terminationGracePeriodSeconds: 60
  containers:
    - name: app
      lifecycle:
        preStop:
          exec:
            # 关键：sleep 放在 preStop 里，而不是 entrypoint
            command: ["sh", "-c", "sleep 5"]
      readinessProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 2
        failureThreshold: 3
      securityContext:
        # 确保 PID 1 能正确转发信号（见第五节坑 2）
        ...

配套两处：

1. 业务侧（Go）要能正确处理 SIGTERM：收到信号后停止接新请求、等存量请求跑完、在超时前主动 close listener。用 signal.NotifyContext + 一个 40s 左右的内部 deadline，正好落在 60s 总预算内、又给 preStop 的 5s 留了余量。
2. Ingress / 反代侧打开连接 drain：nginx 设 proxy_next_upstream 配合 upstream 摘除，或用 server 的 graceful 等待存量连接结束。客户端如果用连接池，旧连接在 Pod 被 KILL 前仍可能命中，drain 必须反代侧兜底。

验证命令（发布时盯这条）：

# 看每个 Pod 的退出时长，>grace 说明被强杀
kubectl get events --sort-by=.lastTimestamp | grep -i 'killed\|terminating'
# 确认 endpoint 已摘除
kubectl get endpointslices -l kubernetes.io/service-name=app

四、踩过的坑（几个反直觉点）

1. 把 sleep 写进 entrypoint 是错的。如果 CMD ["sh","-c","sleep 5 && ./app"]，那 sleep 是在启动时跑的，跟退出毫无关系，而且会让容器启动变慢、拖慢 readiness。drain 的 sleep 必须放在 lifecycle.preStop。
2. grace period 是「总预算」，preStop 在里面扣。我一开始以为 preStop 是「额外加的时间」，结果 sleep 35s + 默认 30s 直接超时被 KILL。正确心智模型：grace >= preStop + 业务优雅关闭耗时。
3. PID 1 不转发信号。如果容器里 PID 1 是个不处理信号的 shell 或没装 tini/dumb-init，SIGTERM 根本到不了业务进程，只能等 SIGKILL。用 docker run 或 entrypoint 里加 tini -- ./app 解决。
4. readinessProbe 摘除 ≠ 流量停了。摘 endpoint 后 LB 侧 keep-alive 和客户端 DNS 缓存仍会打过来，必须反代侧做 connection draining，否则总有几个请求 5xx。
5. 别把 grace period 调得极大（如 300s）来「掩盖」问题，那样 Pod 一旦真挂掉，回收会非常慢，节点上的僵尸 Pod 会堆积、影响调度。60s 通常够用。

五、结论与可复用清单

「滚动更新卡 Terminating」90% 不是网络问题，而是优雅退出时序 + 预算配置问题。排查时按这个顺序来：

• [ ] 先确认 terminationGracePeriodSeconds 是否 ≥ preStop 耗时 + 业务 graceful shutdown 耗时；
• [ ] 确认 preStop 的 sleep 写在 lifecycle.preStop 而不是 entrypoint；
• [ ] 确认容器 PID 1 能转发 SIGTERM（tini / dumb-init）；
• [ ] 确认业务进程收到 SIGTERM 会停接新请求并 drain 存量；
• [ ] 确认反代/Ingress 侧开了 connection draining；
• [ ] 发布后用 kubectl get events 看有没有 Killing（= 被 SIGKILL 强杀，说明又超时了）。

把「grace 总预算 = preStop + 业务优雅关闭」这个等式记牢，绝大多数 Terminating 卡死都能一次修掉。