问题背景
订单查询 API 部署在一个 3 节点的 Kubernetes 集群里,3 个副本,通过 NodePort 暴露给内部网关调用。上线初期网关日志里的客户端 IP 全是节点地址,做限流和审计都不方便。为了拿到真实源 IP,运维把 Service 的 externalTrafficPolicy 从默认的 Cluster 改成 Local,改完日志里果然出现了真实客户端地址,服务平稳跑了一段时间。
这个改动当时被当成一次小优化:只改了一个字段,Pod、副本数、调度策略都没动。
故障现象
发版滚动更新期间,网关侧出现大约三分之一的请求超时,都是 5 秒连接超时。更新结束后大部分流量恢复,但每隔几分钟仍会冒出一批超时,比例还是接近三分之一。
排查时最让人困惑的是「所有常规检查都正常」:Pod 全部 Ready、Endpoints 里有 3 个地址、集群内直接访问 Service 的 ClusterIP 全通、监控里的健康检查全绿、对 ClusterIP 压测也不掉一个请求。故障只在「从网关经 NodePort 访问」这条路径上出现。
从网关侧看,超时集中在发版后的十几分钟里,之后变成每隔几分钟一小批;把失败请求按目标节点归类,几乎全部落在同一台节点上,像是那台节点的 NodePort 端口「时通时不通」。
排查过程
先排除应用:Pod 日志没有异常、没有重启,CPU 和内存都平稳,应用侧线程池也没有打满。
再查 Service 和 Endpoints:kubectl get endpoints 显示三个 Pod IP 都在,ClusterIP 直连压测零失败。说明「服务发现」和「Pod 本身」都没问题。
然后做分节点拨测。对 3 个节点的 NodePort 分别循环 curl 同一个幂等接口:两个节点 100% 成功,第三个节点 100% 超时。kubectl get pods -o wide 一看就明白了——这台节点上没有订单服务的 Pod。
回头看 Service 配置:externalTrafficPolicy: Local。这个策略的语义是「只把流量转发给本节点的 Ready Pod,不做 SNAT,从而保留客户端源 IP」。代价是:本节点没有 Ready 端点时,进入该节点 NodePort 的数据包会被 kube-proxy 直接标记丢弃,不会兜底转发到其他节点。
在故障节点上翻 kube-proxy 生成的 iptables 规则,能看到 KUBE-XLB 链里针对「无本地端点」的 DROP 标记,和文档语义对得上——没有本地 Pod 时,它不做任何跨节点兜底。
做对照实验:把策略临时改回 Cluster,三个节点立即全通,但网关日志里的源 IP 变成了节点地址——既确认了根因,也确认了当初改 Local 的动机。
继续追副本分布:3 个副本因为资源碎片和默认调度,落在了 2 个节点上。集群里没有任何约束要求「每个节点至少有一个副本」,所以第三个节点永远没有本地端点。滚动更新只是把这个长期存在的空洞放大了:旧 Pod Terminating、新 Pod 还没 Ready 的窗口里,节点本地端点数为 0,同样丢包;更新结束后如果副本没有覆盖所有节点,长尾超时就一直存在。
解决方案
-
改回
Cluster,源 IP 交给入口层:Service 恢复跨节点转发;真实客户端 IP 由 Ingress 的X-Forwarded-For或四层负载均衡的 PROXY protocol 传递。这是最稳妥的组合:可用性不依赖副本分布。 -
必须保留
Local时,保证每节点有端点:副本数不少于节点数,并加拓扑约束,例如:1 2 3 4 5 6 7topologySpreadConstraints: - maxSkew: 1 topologyKey: kubernetes.io/hostname whenUnsatisfiable: DoNotSchedule labelSelector: matchLabels: app: order-api滚动更新同时配
maxUnavailable: 0,避免更新窗口内某节点端点归零。 -
入口侧节点级健康检查:LB 对每个节点的 NodePort 拨测,失败节点自动摘除;但内部网关直连 NodePort 的调用方没有这层保护,不能只靠它。
-
验证:三个节点分别 curl 幂等接口全部 200;更新期间持续压测零超时;Ingress 日志里的客户端 IP 是真实地址。
最终我们采用方案 1,同时对确实需要四层直连和源 IP 的服务保留 Local,但补齐了拓扑约束与更新策略。
根因分析
| 行为 | Cluster(默认) | Local |
|---|---|---|
| 流量去向 | 可转发到任意节点的 Pod | 仅转发本节点 Pod |
| 本节点无端点 | 转发到其他节点 | 丢弃,表现为连接超时 |
| 客户端源 IP | 可能被 SNAT 成节点地址 | 保留 |
| 适用前提 | 无 | 每节点至少一个 Ready 副本 |
Local 的设计目标是保留源 IP,它用「只走本节点」换「不做 SNAT」,并不是高可用的默认值。它隐含一个前提:每个节点都有本地端点。这个前提不会被调度器、健康检查或 Endpoints 列表自动保证——3 个副本落在 2 个节点完全合法,所有检查都会是绿的。滚动更新期间端点短暂为空也是正常状态,Local 把正常状态放大成了用户可见的丢包。
预防措施
- 选型清单:需要源 IP 时优先在入口层解决(XFF、PROXY protocol);坚持
Local就必须同时配置拓扑约束、滚动更新策略和节点级拨测,三样缺一不可。 - 监控补盲:增加「按节点 NodePort 拨测」,任一节点失败即告警;外部探测要覆盖所有节点,不能只打 ClusterIP 或 Pod IP。
- 变更评审:
externalTrafficPolicy属于流量路径变更,纳入变更清单,评审时核对副本分布与更新窗口。 - 调度约束:关键服务统一加
topologySpreadConstraints;节点扩容后复核副本是否覆盖新节点。 - 故障演练:定期随机下线一个节点、或在单节点驱逐服务 Pod,验证节点级拨测仍全绿,避免「副本恰好落在少数节点」的隐性单点。
- 知识沉淀:把
Local/Cluster的语义、SNAT 行为、无端点丢包条件写进团队知识库,避免下次为了源 IP 再踩一遍。
总结
Local 不是「更安全的默认值」,而是一个带前提的优化项:用「节点本地有端点」换「源 IP 保留」。前提不成立时,它会把正常调度和正常滚动更新变成用户可见的丢包。
选它之前先回答一个问题:每个节点都能保证有 Ready 副本吗?答不上来就用 Cluster,把源 IP 交给入口层。