外观
14 - Ingress 返回 502、503、504 分别意味着什么:七层入口故障定位
摘要
用户收到 504,应用日志却显示请求只执行了 20 ms,两者为什么可以同时成立?应用执行时间只是整条请求链路的一部分。本文先说明入口路由与代理转发的基本模型,再结合响应生成者、后端地址和阶段耗时定位 502、503、504,最后用无可用后端的实验建立证据链。
1. 场景:网关 504,应用为什么没有慢日志
Ingress 是 Kubernetes 中描述外部 HTTP 路由的 API 资源,例如把某个域名和路径映射到一个 Service;Ingress Controller(入口控制器)读取这些声明,并通过代理处理流量。七层入口中的“七层”指应用层,这里主要关注 HTTP 请求与响应。
Service 为一组后端提供稳定的访问入口,Pod 是运行应用容器的工作负载单元,Endpoint 表示后端地址和端口,EndpointSlice 则是组织这些端点的 Kubernetes 资源。一次请求可能经历:
图表将在阅读到此处时加载…
图中 Cloud Load Balancer(云负载均衡,简称 LB)是外部入口,Ingress Controller 根据路由把请求转发到后端。Service/Endpoint 表示后端选择与访问关系,不意味着流量一定经过一个独立的 Service 代理进程;具体路径取决于控制器实现。
应用记录的 20 ms 如果只覆盖“业务线程开始到结束”,就不包含以下可能发生的等待:
- 客户端和入口建连;
- Ingress 等待连接池;
- 请求在应用接受队列或线程池排队;
- 响应从 Pod 写回代理;
- 代理读取响应体;
- 多次上游重试。
因此,即使业务执行只用了 20 ms,请求也可能在开始执行前或响应返回途中耗尽网关的等待时间。排查时还要确认应用日志与入口错误对应同一个请求、同一次上游尝试,不能用一次成功尝试的耗时解释此前的失败。
2. Ingress 不是一种固定实现
Ingress 对象描述期望的路由,控制器负责把声明转化为实际代理配置。对象创建成功,不等于对应控制器已经接管,也不等于配置已经在处理请求的数据面生效。不同控制器基于 NGINX、Envoy、HAProxy、云厂商代理或其他实现,错误到状态码的映射、默认超时、重试和日志字段并不相同。
Gateway API 是另一组用于描述网关与路由的 Kubernetes API,提供更丰富的流量模型;是否可用取决于集群版本和实现。使用它时,仍应先确认哪一跳生成响应。
3. 502、503、504 不能脱离生成者背定义
对代理来说,上游是它转发请求的目标,下游是向它发起请求的一方。以下是代理层常见的故障映射,不能据此直接判定应用根因:
| 状态码 | 代理层常见含义 | 可能证据 |
|---|---|---|
| 502 | 上游连接失败、响应协议无效或连接被重置 | connect error、reset、invalid header |
| 503 | 没有可用上游、过载拒绝、维护或主动熔断 | no healthy upstream、no endpoints |
| 504 | 在配置时间内未收到预期上游响应 | upstream timeout |
应用本身也可以主动返回这些状态;云负载均衡和 WAF(Web 应用防火墙)也可能生成相同状态码。响应头和页面样式只是线索,最终要查对应层日志:请求是否到达、是否选中了上游、连接或读取是否失败,以及该层是生成错误还是转发上游错误。客户端本地超时则可能没有收到 HTTP 响应,不能直接称为“收到 504”。
4. 一次请求可能跨越多条 TCP 连接
下面以负载均衡和入口代理分别终止连接、再向下一跳建立或复用连接的部署为例。TLS 是用于加密传输和身份认证的协议;不同连接是否启用 TLS,要看实际配置。
图表将在阅读到此处时加载…
每一跳可独立设置连接、请求、读取、写入、空闲和总超时,具体支持哪些限制取决于实现。连接超时约束建连阶段,读取或写入超时可能约束相邻操作之间的等待,并不一定限制整个请求的总时长。只把应用调用下游服务的客户端 timeout 改大,不能延长外层代理的等待时间。
5. 建立时间账本
Request ID 是用于关联请求的标识;Trace ID 用于关联分布式追踪中的调用记录。沿链路传递这些标识,再按每次上游尝试记录关键事件。以下时间账本以单次尝试、非流式响应为简化模型:
text
t0 客户端发起
t1 外部 LB 接收
t2 Ingress 接收
t3 Ingress 选定上游,开始建立或复用连接
t4 Pod 接收
t5 业务线程开始
t6 业务线程结束
t7 Ingress 收到完整响应
t8 客户端收到响应关键差值:
text
t3 - t2:入口排队、路由和连接池等待
t4 - t3:建连或连接复用后的请求传输
t5 - t4:应用内部排队
t6 - t5:业务执行
t7 - t6:响应写回和读取这些差值用于区分“业务慢”与“业务之外的等待”,不是所有日志都能直接提供这些时间点。连接复用、缓冲、流式响应和重试会改变事件关系,应按实际路径解释字段;代理总耗时通常已包含应用执行时间,不能再把二者直接相加。
跨机器绝对时间需要时钟同步;优先使用每个组件自身的 duration(持续时间)字段和 Trace 中调用的先后关系。如果超时请求没有走到 t7 或 t8,应记录失败时刻和原因,而不是补出完整响应时间。
6. Endpoint 如何影响入口
Ingress 通常最终把流量发往 Service 后端,但具体是访问 ClusterIP(Service 的集群内虚拟 IP),还是根据端点信息直接访问 Pod,取决于控制器实现和配置。
Readiness(就绪状态)表示 Pod 是否适合接收流量。后端变化要经过资源更新和控制器传播,已有连接也未必随端点变化立即消失,因此发布期间可能出现以下竞态。箭头表示一种可能的过程,不是各组件严格同步执行的保证:
text
Pod 开始终止
→ Readiness 变为失败
→ EndpointSlice 更新
→ Controller/数据面收到变化
→ 旧连接仍可能存在
→ 应用进程过早退出
→ 连接 reset,入口返回 502连接 reset 指连接被重置;它可能被入口映射为 502,具体仍取决于代理实现。无损发布需要就绪状态、preStop(容器终止前的生命周期钩子)、应用排空、终止宽限期和代理连接行为协同。应用排空是停止接收新工作,并让已有请求在允许时间内完成;单独增加一个 sleep 不能证明这些条件已经满足。
7. 最小实验:制造无 Endpoint 与慢上游
下面的 YAML 和命令用于观察无可用 Endpoint 的情况。慢上游是另一类故障,需要后端能够受控地延迟响应,并结合代理超时配置观察;这份 NGINX 静态页面配置不会主动制造慢响应。
实验需要支持以下 API 的测试集群、已部署的 Ingress Controller、kubectl 和相应资源操作权限,集群还需能拉取 nginx:1.27-alpine。在同一测试命名空间创建下面的后端和 Ingress,确认 ingress-demo 名称未与已有资源冲突。命令采用 Bash 语法。
创建后端:
yaml
apiVersion: apps/v1
kind: Deployment
metadata: {name: ingress-demo}
spec:
replicas: 1
selector:
matchLabels: {app: ingress-demo}
template:
metadata:
labels: {app: ingress-demo}
spec:
containers:
- name: web
image: nginx:1.27-alpine
ports: [{name: http, containerPort: 80}]
---
apiVersion: v1
kind: Service
metadata: {name: ingress-demo}
spec:
selector: {app: ingress-demo}
ports: [{port: 80, targetPort: http}]Ingress API 示例:
yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress-demo
spec:
ingressClassName: nginx
rules:
- host: ingress-demo.example.test
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: ingress-demo
port: {number: 80}ingressClassName 指定由哪个 Ingress 类处理路由,nginx 必须与测试集群的实际配置匹配;域名解析和入口地址也必须按集群修改。请求的 HTTP Host 需匹配 ingress-demo.example.test,访问路径为 /。
先确认 Pod 就绪、Service 有可用后端,并通过入口成功取得页面,再把 Service Selector(标签选择器)临时改错。后端 Pod 的标签仍为 app=ingress-demo,选择器改成 app=wrong 后将无法选中它:
bash
kubectl get endpointslice -l kubernetes.io/service-name=ingress-demo
kubectl patch service ingress-demo --type merge \
-p '{"spec":{"selector":{"app":"wrong"}}}'第一条命令用于查看修改前的 EndpointSlice;执行修改后,再用它检查端点变化,并从同一入口发起请求、查看控制器日志。
预期观察:在端点更新传播后,Service 不再有匹配的可用后端,入口请求出现相应失败。不同控制器可能返回不同状态,EndpointSlice 对象是否仍存在也不能替代对其中端点及就绪条件的检查。实验目标是关联“无可用端点”、实际状态码与入口日志。
实验后将 Selector 恢复为 app=ingress-demo,确认同一路径重新成功,再清理本实验创建的 Deployment、Service 和 Ingress。
8. 排查顺序
图表将在阅读到此处时加载…
按图逐跳收集证据。外部 LB 有请求记录而 Ingress 没有时,应先核对日志覆盖范围和实际转发路径,再检查入口连接;Ingress 已选中上游时,则结合上游地址和错误原因区分建连失败、等待响应和应用返回错误。
必查信息:
- Ingress Controller 产品和版本;
- 请求
Host、Path(路径)、TLS SNI(TLS 握手携带的服务器名称); - 控制器访问日志和错误日志中的 upstream(上游)地址、状态和耗时;
- Service/EndpointSlice;
- Pod IP、Node、版本、Readiness;
- 应用入口日志和 Trace。
9. 反例与正例
反例:所有超时统一改成 60 秒
外层 30 秒、内层 60 秒时,如果外层到期后没有有效取消内层工作,内层就可能在客户端已经失败后继续占用资源。统一增大超时只会延长等待,不能消除排队、连接故障或慢下游。
正例:从总 Deadline 向内分配预算
Deadline 是整个操作必须结束的截止时间,各层根据剩余时间分配预算。以下是预算关系示例,3 s 不是通用推荐值:
text
客户端总预算 3 s
入口保留网络与响应预算
应用对下游设置更短预算
重试必须消费剩余 DeadlineSLO(服务等级目标)规定服务希望达到的可用性或延迟水平。具体预算应由业务 SLO 和延迟分布决定,并为回传响应留出时间;重试也要消耗剩余预算,不能每次重新获得完整时限。
10. 容易踩的坑
10.1 看到 504 就只查应用执行时间
把应用执行跨度放回时间账本,检查它之前的等待和之后的响应回传,避免只凭方法耗时排除上游问题。
10.2 用 Pod 日志缺失证明请求没进集群
请求可能在日志点之前排队或失败,也可能被采样丢弃。
10.3 只检查 Ingress YAML
同时核对控制器是否接管该 Ingress,以及实际处理请求的代理配置和日志;API 中的声明只是证据链的起点。
10.4 发布失败只增加 PreStop sleep
需要验证 Endpoint 传播、旧连接和应用排空,而不是猜一个等待值。
10.5 忽略代理重试
一次客户端请求可能对应多个上游 attempt(尝试),放大流量并掩盖首个失败实例。应分别记录每次尝试的目标、状态和耗时,而不是只看最终结果。
11. 总结
502、503、504 只有和响应生成者、上游地址及阶段耗时放在一起才有诊断价值。
可以带走的三个核心要点:
- 一次入口请求通常跨多条独立连接,各跳的超时与重试策略需要分别检查。
- 先确定谁生成状态码,再用 upstream 地址、状态和耗时定位失败阶段。
- 应用方法耗时不包含入口和内部排队,端到端排障必须建立完整时间账本。
下一篇:NetworkPolicy 配了却没有生效:网络策略的实现与边界。