容器与云原生 / 技术文章
Kubernetes Ingress 访问异常怎么排查
Kubernetes Ingress 访问异常常表现为域名打不开、请求超时、404、502/503 或 TLS 握手失败。本文面向负责服务发布和线上排障的 SRE、平台工程师,给出一条从外部请求到后端 Pod 的分层排查路径,最终把“访问失败”收敛到入口地址、控制器、路由规则、Service/EndpointSlice、TLS 或应用监听中的具体一层。
先用现象确定排查起点
不要看到 Ingress 异常就立即修改 YAML。第一步应固定同一条请求,同时记录 DNS、连接、TLS 和 HTTP 层的实际结果。不同现象通常对应不同故障边界:DNS 无法解析时优先检查域名和入口地址;连接超时通常指向负载均衡器、网络或入口组件;TLS 错误应检查证书、SNI 与监听配置;HTTP 404 更可能是 Host/Path 未命中;502、503 则应继续检查 Service、EndpointSlice 和后端应用。
先保留完整请求信息:
curl -vk --connect-timeout 5 https://app.example.com/api/health预期结果不是一定返回 200,而是获得足够的分层证据。例如已经成功建立 TLS 并收到 HTTP 404,说明 DNS、TCP 和 TLS 主链路基本可用,此时不应把主要精力放在负载均衡器连通性上。
* Connected to app.example.com (<IP>) port 443
* SSL connection using TLSv1.3
> GET /api/health HTTP/1.1
> Host: app.example.com
< HTTP/1.1 404 Not Found如果 DNS 尚未切换,可以直接向入口 IP 发请求并显式保留 Host,从而把 DNS 与 Ingress 路由问题拆开验证:
curl -v -H 'Host: app.example.com' http://<IP>/api/health对于 HTTPS,不要简单使用 https://<IP> 代替域名,因为 TLS 证书选择通常依赖 SNI。可以使用 --resolve 同时固定目标 IP 和正确域名:
curl -vk --resolve app.example.com:443:<IP> https://app.example.com/api/health确认 Ingress 是否由正确的 Controller 接管
Ingress 本身只是 Kubernetes API 中的路由声明,真正监听入口并生成数据面配置的是 Ingress Controller。资源存在并不等于已经有控制器接纳它,因此排查时应先确认 ingressClassName、IngressClass 和实际 Controller 三者是否对应。
kubectl get ingress -A
kubectl get ingressclass
kubectl describe ingress web -n app重点检查 spec.ingressClassName,以及对应 IngressClass 的 spec.controller。如果集群中同时运行多个控制器,例如不同团队分别部署入口组件,错误的 class 会导致资源被错误实现接管,或者根本无人处理。
kubectl get ingress web -n app -o jsonpath='{.spec.ingressClassName}{"\n"}'
kubectl get ingressclass nginx -o jsonpath='{.spec.controller}{"\n"}'预期结果应能明确找到负责该 Ingress 的实现,例如:
nginx
k8s.io/ingress-nginx随后检查控制器 Pod 是否健康以及最近是否发生重启:
kubectl get pods -A -l app.kubernetes.io/component=controller -o wide如果使用的控制器没有采用该标签,应根据实际部署的标签或工作负载名称查询。这里的目标不是记住某一种控制器的固定命令,而是确认三个事实:负责该 Ingress 的 Controller 是否存在、是否 Ready、是否持续运行。
验证 Host、Path 和后端引用是否真的匹配
当入口可以访问但返回 404,最有价值的检查通常不是 Pod 日志,而是比较实际请求与 Ingress 规则。Ingress 路由至少需要同时考虑 Host、Path 和 pathType,其中任何一个不匹配都可能让请求落入控制器默认后端。
kubectl get ingress web -n app -o yaml假设规则为:
spec:
rules:
- host: app.example.com
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api
port:
number: 8080那么应使用与规则完全对应的请求验证:
curl -v -H 'Host: app.example.com' http://<IP>/api/health此时依次核对四个对象:请求的 Host 是否为 app.example.com,Path 是否符合 /api 的 Prefix 语义,后端 Service 名称 api 是否存在,Service 端口是否确实为 8080。不要把 Service 的 port 与容器的 containerPort 或 Service 的 targetPort 混为一谈;Ingress backend 引用的是 Service 暴露的端口。
如果同一个 Host 存在多个 Ingress,或者多个规则覆盖相近路径,还应把 Namespace 内相关资源一起列出,确认是否产生控制器相关的合并或冲突行为:
kubectl get ingress -n app -o wideIngress API 定义了标准路由字段,但多个 Ingress 之间发生冲突时的具体处理仍可能受到 Controller 实现影响,因此发现重复 Host/Path 后,应继续查控制器事件和配置生成结果,而不是假定所有实现行为完全一致。
从 Service 一直检查到 EndpointSlice 和 Pod
如果路由规则正确但出现 502、503、连接重置或请求长时间等待,应把关注点从 Ingress 转向后端链路。最常见的故障包括 Service 端口写错、selector 没选中 Pod、EndpointSlice 没有 ready endpoint、Pod 未 Ready,以及应用没有监听 targetPort。
先检查 Service 定义:
kubectl get service api -n app -o yaml确认 spec.ports[].port 与 Ingress backend 引用一致,并继续检查 targetPort。然后查看 EndpointSlice:
kubectl get endpointslice -n app -l kubernetes.io/service-name=api -o wide正常情况下,应至少看到一个可以承担流量的 endpoint。若地址为空或对应 endpoint 未 Ready,应继续检查 Service selector 与 Pod 标签:
kubectl get pods -n app --show-labels
kubectl get service api -n app -o jsonpath='{.spec.selector}{"\n"}'再检查 Pod 的 Ready 状态及容器端口:
kubectl get pods -n app -o wide
kubectl describe pod <POD> -n app还可以绕过 Ingress,直接从集群内部请求 Service。这一步能够把“入口层故障”和“服务自身故障”明确分开:
kubectl run curl-debug --rm -it --restart=Never --image=curlimages/curl -- \
curl -sv http://api.app.svc.cluster.local:8080/health如果内部 Service 请求同样失败,就没有必要继续反复修改 Ingress;应优先修复 Service、EndpointSlice、Pod readiness 或应用监听问题。若内部访问正常而入口访问失败,故障边界才重新收敛到 Ingress Controller、路由或入口网络。
TLS 异常要区分证书选择和后端转发
HTTPS 请求失败时,要先确认故障发生在客户端到入口的 TLS 握手阶段,还是握手成功后的 HTTP 转发阶段。若 curl -vk 尚未出现 HTTP 状态码就因证书、握手或连接问题退出,应优先检查 Ingress TLS 配置和 Secret。
kubectl get ingress web -n app -o jsonpath='{.spec.tls}{"\n"}'
kubectl get secret app-tls -n app -o jsonpath='{.type}{"\n"}'TLS Secret 通常应为:
kubernetes.io/tls继续确认 Ingress spec.tls[].hosts、请求域名和证书覆盖的 DNS 名称一致。使用 --resolve 可以排除 DNS 干扰并保留正确 SNI:
curl -vk --resolve app.example.com:443:<IP> https://app.example.com/若 TLS 已成功建立但随后返回 502 或 503,证书通常不是当前首要问题,应回到 Service 和后端链路。还要注意,客户端到 Ingress 的 TLS 终止与 Controller 到后端是否再次使用 TLS 是两个独立问题;后端协议、证书校验或 HTTPS 转发能力如果依赖 annotation 或控制器扩展,需要按照所用 Controller 的配置证据单独检查。
用事件和 Controller 日志确认最终根因
资源静态配置只能说明“声明了什么”,事件和 Controller 日志才能补充“控制器处理时发生了什么”。当 Ingress 长时间不生效、规则看似正确却行为异常,或刚完成发布变更后出现故障,应立即查看事件。
kubectl describe ingress web -n app
kubectl get events -n app --sort-by=.lastTimestamp典型线索包括 Service 不存在、端口无法解析、Secret 缺失、配置校验失败,以及 Controller 无法同步配置。然后找到负责该 Ingress 的控制器工作负载并查看日志:
kubectl logs -n <CONTROLLER_NAMESPACE> <CONTROLLER_POD> --since=15m不要只搜索 error。更有效的方法是围绕 Ingress 名称、Namespace、Host、Service 名称和变更时间点关联日志,因为不同 Controller 对配置拒绝、重载失败和后端不可用的日志级别并不一致。
完成定位后,恢复动作应针对已经取得证据的故障层执行:入口地址错误就修复 LoadBalancer 或 DNS;Ingress 未被接管就修正 class 或 Controller;Host/Path 不匹配就修正路由;EndpointSlice 为空就修复 selector、readiness 或 Pod;TLS Secret 错误就更换正确证书;应用未监听目标端口就修复工作负载。恢复后重新执行最初保存的同一条 curl 请求,并同时检查 Controller 和后端状态,确认故障链路已经真正闭合,而不是仅让某一次请求偶然成功。