容器与云原生 / 系统课时
排查 Ingress 规则不生效
排查 Ingress 规则不生效
Ingress 已创建却没有按预期转发时,不要先盲目改规则。按“控制器归属 → Host/Path 匹配 → Service 后端 → 控制器证据 → 真实请求”收集证据,可以更快判断故障停在哪一层,并确认修复是否真正进入数据面。
学习目标
- 判断 Ingress 是否被正确的 IngressClass 和控制器接管
- 核对 Host、Path、pathType 与 Service 后端是否形成有效匹配
- 根据事件、后端状态和真实请求定位规则未生效的层级
从资源归属开始排查
Ingress 只是声明式 API 对象,真正把规则转换为代理或负载均衡配置的是 Ingress Controller。先确认集群中的 IngressClass,以及目标 Ingress 的 spec.ingressClassName 是否指向预期的类。
kubectl get ingressclass
kubectl get ingress web -n demo -o wide
kubectl get ingress web -n demo -o jsonpath='{.spec.ingressClassName}{"\n"}'预期输出
NAME CONTROLLER PARAMETERS AGE
nginx k8s.io/ingress-nginx <none> <TIME>
NAME CLASS HOSTS ADDRESS PORTS AGE
web nginx app.example <IP> 80 <TIME>
nginx实际的 ADDRESS、AGE 和控制器标识可能不同。CLASS 为空也不一定代表故障:集群可能配置了默认 IngressClass,某些控制器也可能按自身设置处理未显式指定 class 的 Ingress。排障时仍要明确到底由哪个控制器负责,避免无人接管或被错误控制器处理。
接着检查 IngressClass 的控制器标识。这里应使用可执行的 kubectl 命令:
kubectl get ingressclass nginx -o yaml预期结果
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
name: nginx
spec:
controller: k8s.io/ingress-nginx如果 spec.ingressClassName 指向不存在的 IngressClass,或者该类的 spec.controller 与目标控制器声明的标识不一致,Ingress 就不会被预期实现正确处理。新配置应优先使用 spec.ingressClassName,不要把已废弃的 kubernetes.io/ingress.class 注解作为主要配置方式。

核对 Host、Path 和 pathType
类绑定正确后,再确认请求是否真的能命中规则。Ingress 的 Host 匹配依赖 HTTP Host 头;仅把域名解析到入口 IP,并不能证明请求一定会进入目标规则。Exact 要求路径完全一致,Prefix 按 / 分隔的路径元素匹配,例如 /api 可匹配 /api 和 /api/v1,但不会匹配 /apix。
kubectl get ingress web -n demo -o yaml预期结果
spec:
ingressClassName: nginx
rules:
- host: app.example
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: api
port:
number: 8080这里的后端端口 8080 指向 Service 的 port,不是直接填写 Pod 的 targetPort。如果使用 ImplementationSpecific,路径解释由控制器决定;排障需要可预测行为时,应确认对应控制器文档,或优先使用语义明确的 Exact、Prefix。
检查 Service 与 EndpointSlice
规则正确并不代表后端可用。继续核对 Ingress 引用的 Service 是否存在、后端端口是否与 Service 的 port 一致,以及 Service 是否通过 EndpointSlice 发现了可用后端。
kubectl get service api -n demo
kubectl get endpointslice -n demo -l kubernetes.io/service-name=api预期输出
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
api ClusterIP <IP> <none> 8080/TCP <TIME>
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
api-<ID> IPv4 8080 <IP>,<IP> <TIME>若 Service 不存在、Ingress 写成了 Service 未暴露的端口,或者 EndpointSlice 没有后端地址,控制器即使已接管 Ingress,也无法把请求送到正确后端。此时应优先检查 Service selector、Pod Ready 状态以及 port 与 targetPort 的映射。
读取事件和控制器证据
Ingress API 没有像 Gateway API Route 那样统一的 Accepted、ResolvedRefs 条件,因此不能只盯着 status。status.loadBalancer 常用于暴露入口地址,但是否填写以及填写形式取决于控制器实现;资源事件和控制器日志通常能提供更直接的失败证据。
kubectl describe ingress web -n demo预期输出
Name: web
Namespace: demo
Ingress Class: nginx
Rules:
Host Path Backends
app.example /api api:8080 (<IP>:8080)
Events:
<EVENTS_OR_NONE>如果 Events 中出现 class 无效、Service 不存在或配置被拒绝等信息,先按事件修复。若事件没有有效线索而数据面仍未变化,再检查对应 Ingress Controller 的 Pod 状态和日志;控制器所在 Namespace、Pod 标签和日志格式因实现而异,不应假设固定名称。
用真实请求闭环验证
修复后应同时满足三层证据:Ingress 由目标控制器接管,Service 与 EndpointSlice 后端有效,真实请求能按正确 Host 和 Path 到达应用。假设入口地址为 <IP>,可绕过 DNS 直接验证路由:
curl -i -H 'Host: app.example' http://<IP>/api/health在示例后端健康且该端点返回成功响应的前提下,预期输出类似:
HTTP/1.1 200 OK
<HEADER>: <VALUE>
<RESPONSE_BODY>实际状态码、响应头和响应体由应用决定。若带正确 Host 后成功,而使用错误 Host 或路径时无法进入同一后端,说明入口和数据面已按规则工作;只有资源归属、后端发现和真实请求三者一致,才能确认这次修复真正生效。