4. terminationGracePeriodSeconds：关闭超时控制与最佳实践
terminationGracePeriodSeconds 是 Pod 优雅关闭的核心参数，它定义了 Kubernetes 在发送 SIGTERM 信号后，等待容器完成清理工作的最长时间。超过该时间后，Kubelet 将强制发送 SIGKILL 终止容器。在网关升级场景中，该参数的配置直接影响流量中断时长和 Pod 调度效率。
4.1 优雅关闭时间线
Pod 进入 Terminating 状态后，Kubernetes 按以下顺序执行关闭流程：
- 更新 Endpoint / EndpointSlice：将 Pod 从 Service 后端列表中移除，停止新流量接入。
- 执行 preStop Hook：如果定义了 preStop，则先执行该处理程序。
- 发送 SIGTERM：向容器主进程发送终止信号。
- 等待 terminationGracePeriodSeconds：等待容器自行退出。
- 发送 SIGKILL：超时后强制杀死容器。
关键时序点：preStop Hook 的执行时间 计入 terminationGracePeriodSeconds。如果 preStop 执行了 20 秒，则留给 SIGTERM 处理的时间只剩 (terminationGracePeriodSeconds - 20) 秒。
网关场景提示：网关 Pod 的优雅关闭需要额外等待 5-10 秒，确保已建立的连接在流量切断前完成处理。建议在 preStop 中执行 sleep 命令，而非依赖应用自身的关闭超时。
4.2 参数配置与默认值
| 配置项 | 默认值 | 推荐值（网关） | 说明 |
|---|---|---|---|
terminationGracePeriodSeconds |
30 | 60-120 | Pod 从 SIGTERM 到 SIGKILL 的总等待时间 |
preStop sleep |
无 | 10-30 | 在 preStop 中执行 sleep，等待流量排空 |
preStop httpGet |
无 | 可选 | 调用健康检查接口触发主动关闭 |
4.3 关闭超时控制流程
4.4 最佳实践配置
4.4.1 网关 Pod 推荐配置
apiVersion: apps/v1
kind: Deployment
metadata:
name: api-gateway
spec:
template:
spec:
terminationGracePeriodSeconds: 90
containers:
- name: gateway
lifecycle:
preStop:
exec:
command:
- /bin/sh
- -c
- |
sleep 15
# 可选：调用管理接口触发优雅关闭
curl -X POST http://localhost:8080/shutdown
常见陷阱：如果 preStop 中执行了 sleep 30，而 terminationGracePeriodSeconds 设置为 30，则 SIGTERM 发送后容器立即被 SIGKILL 杀死，优雅关闭完全失效。务必保证 terminationGracePeriodSeconds > preStop 执行时间。
4.4.2 不同场景参数对比
| 场景 | terminationGracePeriodSeconds | preStop 策略 | 说明 |
|---|---|---|---|
| 无状态 HTTP 服务 | 30 | 无 | 应用快速关闭，无需额外等待 |
| 网关/代理服务 | 60-120 | sleep 10-30 | 等待已有连接处理完成 |
| 有状态数据库 | 120-300 | 执行数据 flush 脚本 | 确保数据持久化完成 |
| 消息队列消费者 | 60-90 | 调用 drain 接口 | 等待消息处理完成 |
4.5 监控与调试
通过以下方式验证优雅关闭是否正常工作：
- Pod 事件：
kubectl describe pod <pod-name>查看 Terminating 状态持续时间。 - 容器日志：检查应用是否收到 SIGTERM 并正常退出。
- Metrics：监控
kube_pod_termination_duration_seconds指标，识别异常超时。 - 抓包验证：在网关 Pod 关闭期间，确认新连接不再路由到该 Pod。
调试命令：
kubectl get pod -w 实时观察 Pod 状态变化；kubectl logs --previous <pod-name> 查看关闭前容器日志。
4.6 常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Pod 长时间处于 Terminating 状态 | 应用未处理 SIGTERM 或 preStop 执行时间过长 | 增加 terminationGracePeriodSeconds 或优化应用关闭逻辑 |
| 关闭期间仍有新流量接入 | Endpoint 移除延迟或 preStop 未等待流量排空 | 在 preStop 中增加 sleep，确保 Endpoint 同步完成 |
| 容器被 SIGKILL 强制杀死 | terminationGracePeriodSeconds 设置过短 | 根据实际关闭时间调整参数，预留 20% 缓冲 |
| preStop 执行失败导致关闭阻塞 | preStop 脚本错误或依赖服务不可用 | 添加超时机制，避免 preStop 无限等待 |