NodePort 配 Local:无 Pod 节点直接丢包

Service 设为 externalTrafficPolicy Local 后,未运行副本的节点会丢弃 NodePort 流量,滚动更新时约三分之一请求超时;改回 Cluster 后恢复。

问题背景

订单查询 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,同样丢包;更新结束后如果副本没有覆盖所有节点,长尾超时就一直存在。

解决方案

  1. 改回 Cluster,源 IP 交给入口层:Service 恢复跨节点转发;真实客户端 IP 由 Ingress 的 X-Forwarded-For 或四层负载均衡的 PROXY protocol 传递。这是最稳妥的组合:可用性不依赖副本分布。

  2. 必须保留 Local 时,保证每节点有端点:副本数不少于节点数,并加拓扑约束,例如:

    1
    2
    3
    4
    5
    6
    7
    
    topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: kubernetes.io/hostname
        whenUnsatisfiable: DoNotSchedule
        labelSelector:
          matchLabels:
            app: order-api
    

    滚动更新同时配 maxUnavailable: 0,避免更新窗口内某节点端点归零。

  3. 入口侧节点级健康检查:LB 对每个节点的 NodePort 拨测,失败节点自动摘除;但内部网关直连 NodePort 的调用方没有这层保护,不能只靠它。

  4. 验证:三个节点分别 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 交给入口层。

延伸阅读

使用 Hugo 构建
主题 Stack 由 Jimmy 设计