容器与云原生 / 系统课时

排查 HTTPRoute 不生效

排查 HTTPRoute 不生效

HTTPRoute 不生效时,最重要的证据不是猜控制器实现,而是资源自己的状态条件。应先确认 Gateway 是否可用,再检查 Route 是否成功附着到父对象、引用是否解析成功,最后核对监听器、Host、Path 和后端 Service。

学习目标

  • 通过 Gateway 与 HTTPRoute 的 status.conditions 判断异常发生在哪一层
  • 核对 parentRefs、listener、namespace 与 backendRefs 的引用关系
  • 用状态、后端端点和真实请求完成 HTTPRoute 修复验证

先看 Gateway 是否已经可用

HTTPRoute 依附于 Gateway 提供的 listener。若 Gateway 自己还没有被控制器接受或编程,继续修改 Route 通常没有意义。先读取 Gateway 的类、监听器和状态条件。

bash
kubectl get gateway edge -n demo -o yaml

预期结果

text
spec:
  gatewayClassName: example
  listeners:
  - name: http
    protocol: HTTP
    port: 80
status:
  conditions:
  - type: Accepted
    status: "True"
  - type: Programmed
    status: "True"

具体状态字段还可能包含 reason、message、observedGeneration 和时间戳。排障时至少确认 Accepted=True;实现支持并报告 Programmed 时,也应确认其为 True,因为这表示配置已成功送往数据面。

如果 Gateway 的 Accepted=False,应先检查 gatewayClassName、GatewayClass 是否存在以及控制器是否支持该类。若 Programmed=False,则说明对象可能已被接受,但底层负载均衡器、代理或其他数据面尚未配置完成。

HTTPRoute 从 Gateway 到后端的状态排查链路

检查 Route 是否真正附着到父对象

HTTPRoute 的 spec.parentRefs 表示它希望附着到哪些父对象;真正的附着结果由 status.parents 体现。一个 Route 可以面对多个父对象,因此必须按目标 Gateway 对应的状态项判断,不能只看第一条 condition。

bash
kubectl get httproute web -n demo -o yaml

预期结果

text
spec:
  parentRefs:
  - name: edge
  hostnames:
  - app.example
status:
  parents:
  - parentRef:
      name: edge
    conditions:
    - type: Accepted
      status: "True"
    - type: ResolvedRefs
      status: "True"

Accepted=True 表示该 Route 对这个 parent 已被接受。若 status.parents 为空,常见方向包括 parent 不存在、控制器没有观察到该资源,或者控制器不负责这个父对象。若存在 parent 状态但 Accepted=False,重点读取对应的 reason 和 message,不要只根据布尔值猜根因。

常见的附着失败包括 listener 的 allowedRoutes 不允许当前 Namespace、parentRefs.sectionName 指向不存在的 listener,或者 Route 类型不被目标 listener 支持。

判断引用是否解析成功

ResolvedRefs 用来判断 Route 内部引用是否有效。即使 Accepted=True,ResolvedRefs 也可能是 False;例如引用了不存在的 Service,或跨 Namespace 引用后端却没有得到 ReferenceGrant 授权。

bash
kubectl get httproute web -n demo -o jsonpath='{range .status.parents[*]}{.parentRef.name}{"\t"}{range .conditions[*]}{.type}={.status}({.reason}){" "}{end}{"\n"}{end}'

预期输出

text
edge	Accepted=True(Accepted) ResolvedRefs=True(ResolvedRefs)

不同实现的 reason 文本可能不同,应以实际输出为准。若看到 ResolvedRefs=False,继续检查后端引用:

bash
kubectl get httproute web -n demo -o jsonpath='{.spec.rules[*].backendRefs[*].name}{"\n"}'
kubectl get service -n demo

预期输出

text
api
NAME   TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
api    ClusterIP   <IP>         <none>        8080/TCP  <TIME>

若 backendRefs 指向其他 Namespace,还要确认该后端类型允许跨 Namespace 引用,并检查目标 Namespace 中是否存在匹配的 ReferenceGrant。ReferenceGrant 授权的是“谁可以引用谁”,不是简单的全局开关。

核对 listener 与请求匹配

状态条件都正常后,再看请求是否符合 listener 和 HTTPRoute 的匹配条件。parentRefs.sectionName 若存在,必须对应 Gateway 中的 listener 名称;Route 的 hostnames、规则中的 path match 也必须与真实请求一致。

bash
kubectl get gateway edge -n demo -o jsonpath='{range .spec.listeners[*]}{.name}{"\t"}{.protocol}{"\t"}{.port}{"\n"}{end}'
kubectl get httproute web -n demo -o jsonpath='{.spec.hostnames[*]}{"\n"}'

预期输出

text
http	HTTP	80
app.example

如果入口地址为 <IP>,可直接发送带 Host 的请求,绕过 DNS 验证 Gateway 与 HTTPRoute 的数据面路径:

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

预期输出

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

<RESPONSE_BODY>

返回码与响应体由应用决定。若 Accepted=True、ResolvedRefs=True,但请求仍没有命中,重点核对 listener hostname、Route hostname、path match、规则优先级以及数据面是否已经完成编程。

检查后端和完成验收

Route 引用正确但 Service 没有可用 endpoint,同样会导致请求失败。最后检查 EndpointSlice,并再次观察 HTTPRoute 状态。

bash
kubectl get endpointslice -n demo -l kubernetes.io/service-name=api
kubectl get httproute web -n demo -o jsonpath='{range .status.parents[*].conditions[*]}{.type}{"="}{.status}{" "}{.reason}{"\n"}{end}'

预期输出

text
NAME       ADDRESSTYPE   PORTS   ENDPOINTS   AGE
api-<ID>   IPv4          8080    <IP>        <TIME>
Accepted=True Accepted
ResolvedRefs=True ResolvedRefs

Gateway API 的优势之一就是把控制平面判断直接暴露在状态条件中。排查 HTTPRoute 时,应优先沿 Gateway → status.parents → Accepted/ResolvedRefs → listener 与匹配规则 → backendRefs → Service/EndpointSlice → 实际请求 的顺序推进,这比先查代理日志更容易快速锁定配置层问题。

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

目录与阅读设置

记录一个想法

排查 HTTPRoute 不生效

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

登录哪都通