terminationGracePeriodSeconds是Kubernetes中唯一生效的优雅终止超时控制点，必须显式设置为45～60秒，并确保Go层context.WithTimeout严格小于此值，同时配合就绪探针快速摘流与preStop轻量预处理，三者协同保障Shutdown()完整执行。
terminationGracePeriodSeconds 是唯一生效的超时控制点
Kubernetes 中 Golang 服务能否“等够时间”完成 Shutdown()，不取决于 Go 代码里的 context.WithTimeout，而取决于 Pod 级别的 terminationGracePeriodSeconds。这个字段才是 kubelet 发送 SIGTERM 后真正开始倒计时的起点——它决定了从发信号到强制杀进程（SIGKILL）之间有多少秒可用。
常见错误是只在 Go 里设了 30s 超时，但没配 terminationGracePeriodSeconds，结果 kubelet 默认用 30s，而你的 srv.Shutdown(ctx) 却卡在 25s 就返回了，后面清理 DB/Redis 的逻辑还没跑完，进程却因超时被 SIGKILL 终止。
-
terminationGracePeriodSeconds必须显式写在 Deployment 或 Pod spec 的spec层级，不是容器层 - 值建议设为 45～60 秒：给 Go 的
Shutdown()留 25～30s，再留 15～30s 给依赖组件关闭（DB 连接池、gRPC client、后台 goroutine） - 如果用了
preStophook，它的执行时间会从terminationGracePeriodSeconds中扣除，不是额外加时
preStop Hook 不是超时替代品，而是前置清理入口
preStop hook 的作用不是延长超时，而是抢在 SIGTERM 到达前做轻量级预处理，比如通知上游降权、关闭健康检查端口、或触发本地状态快照。它本身没有独立超时机制，执行时间全算在 terminationGracePeriodSeconds 内。
典型误用：把 DB.Close() 或 srv.Shutdown() 放进 preStop HTTP hook 里——这会导致两个问题：一是 hook 超时失败会直接跳过 shutdown；二是 HTTP hook 的调用和 SIGTERM 是并发的，可能引发竞态。
立即学习“go语言免费学习笔记（深入）”；
评估 Kubernetes 集群安全态势，覆盖 RBAC、工作负载安全、网络策略、基础设施即代码（IaC）、运行时监控和密钥管理等 30 项控制项……
- 推荐只在
preStop中做非阻塞操作，例如：curl -X POST http://localhost:8080/shutdown-prepare - 真正的 Shutdown() 和资源清理必须放在 Go 主程序里监听
SIGTERM后执行 - 不要依赖
preStop返回成功才继续 shutdown —— 它失败了，SIGTERM 仍会照常发出
Go 代码里的 context.WithTimeout 必须小于 terminationGracePeriodSeconds
Go 的 srv.Shutdown(ctx) 只负责 HTTP 连接层面的等待，它不感知 Kubernetes 生命周期。如果你传入的 context.WithTimeout(context.Background(), 60*time.Second)，但 terminationGracePeriodSeconds 只有 30，那第 31 秒 kubelet 就发 SIGKILL，Go 进程根本没机会执行后续清理。
所以必须让 Go 层超时严格小于集群层超时，留出缓冲空间给非 HTTP 资源释放。
- 设
terminationGracePeriodSeconds: 45→ Go 中用context.WithTimeout(ctx, 30*time.Second) - 别用
context.Background()直接调srv.Shutdown()，否则一旦 handler 里有死循环或阻塞 channel，就会永久 hang 住 -
srv.Shutdown()返回context.DeadlineExceeded是预期行为，不是 bug，无需 panic
就绪探针（Readiness Probe）必须配合信号处理才能避免流量漏打
即使设置了正确的超时，如果就绪探针没及时响应 shutdown 状态，Kubernetes 仍可能在 terminationGracePeriodSeconds 倒计时中继续把新请求转发到正在关闭的 Pod 上——因为 Endpoint 摘除依赖就绪状态，而不是信号是否收到。
这意味着：超时设得再准，只要流量还在进来，Shutdown() 就永远等不完活跃连接。
- 在 signal handler 里第一时间将就绪状态置为 false（例如设全局
isReady = false） - 就绪探针 endpoint（如
/healthz）必须读取该状态，返回 503 而非 200 - Readiness Probe 的
initialDelaySeconds和periodSeconds要足够短（建议 ≤5s），确保状态变更后 1～2 轮探针就能生效
最常被忽略的一点：超时不是数字对齐就行，而是三层时间必须咬合——就绪探针摘流量的速度、HTTP server shutdown 等待时间、依赖组件 close 的耗时，三者叠加不能超过 terminationGracePeriodSeconds。任何一层拖慢，都会让整个优雅退出失效。
