容器与云原生 / 系统课时

排查 Ingress 规则不生效

排查 Ingress 规则不生效

Ingress 已创建却没有按预期转发时,不要先盲目改规则。按“控制器归属 → Host/Path 匹配 → Service 后端 → 控制器证据 → 真实请求”收集证据,可以更快判断故障停在哪一层,并确认修复是否真正进入数据面。

学习目标

  • 判断 Ingress 是否被正确的 IngressClass 和控制器接管
  • 核对 Host、Path、pathType 与 Service 后端是否形成有效匹配
  • 根据事件、后端状态和真实请求定位规则未生效的层级

从资源归属开始排查

Ingress 只是声明式 API 对象,真正把规则转换为代理或负载均衡配置的是 Ingress Controller。先确认集群中的 IngressClass,以及目标 Ingress 的 spec.ingressClassName 是否指向预期的类。

bash
kubectl get ingressclass
kubectl get ingress web -n demo -o wide
kubectl get ingress web -n demo -o jsonpath='{.spec.ingressClassName}{"\n"}'

预期输出

text
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 命令:

bash
kubectl get ingressclass nginx -o yaml

预期结果

text
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 注解作为主要配置方式。

Ingress 规则不生效的分层定位关系

核对 Host、Path 和 pathType

类绑定正确后,再确认请求是否真的能命中规则。Ingress 的 Host 匹配依赖 HTTP Host 头;仅把域名解析到入口 IP,并不能证明请求一定会进入目标规则。Exact 要求路径完全一致,Prefix 按 / 分隔的路径元素匹配,例如 /api 可匹配 /api 和 /api/v1,但不会匹配 /apix。

bash
kubectl get ingress web -n demo -o yaml

预期结果

text
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 发现了可用后端。

bash
kubectl get service api -n demo
kubectl get endpointslice -n demo -l kubernetes.io/service-name=api

预期输出

text
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 常用于暴露入口地址,但是否填写以及填写形式取决于控制器实现;资源事件和控制器日志通常能提供更直接的失败证据。

bash
kubectl describe ingress web -n demo

预期输出

text
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 直接验证路由:

bash
curl -i -H 'Host: app.example' http://<IP>/api/health

在示例后端健康且该端点返回成功响应的前提下,预期输出类似:

text
HTTP/1.1 200 OK
<HEADER>: <VALUE>

<RESPONSE_BODY>

实际状态码、响应头和响应体由应用决定。若带正确 Host 后成功,而使用错误 Host 或路径时无法进入同一后端,说明入口和数据面已按规则工作;只有资源归属、后端发现和真实请求三者一致,才能确认这次修复真正生效。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

排查 Ingress 规则不生效

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通