容器与云原生 / 系统课时
排查 HTTPRoute 不生效
排查 HTTPRoute 不生效
HTTPRoute 不生效时,最重要的证据不是猜控制器实现,而是资源自己的状态条件。应先确认 Gateway 是否可用,再检查 Route 是否成功附着到父对象、引用是否解析成功,最后核对监听器、Host、Path 和后端 Service。
学习目标
- 通过 Gateway 与 HTTPRoute 的
status.conditions判断异常发生在哪一层 - 核对
parentRefs、listener、namespace 与backendRefs的引用关系 - 用状态、后端端点和真实请求完成 HTTPRoute 修复验证
先看 Gateway 是否已经可用
HTTPRoute 依附于 Gateway 提供的 listener。若 Gateway 自己还没有被控制器接受或编程,继续修改 Route 通常没有意义。先读取 Gateway 的类、监听器和状态条件。
kubectl get gateway edge -n demo -o yaml预期结果
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,则说明对象可能已被接受,但底层负载均衡器、代理或其他数据面尚未配置完成。

检查 Route 是否真正附着到父对象
HTTPRoute 的 spec.parentRefs 表示它希望附着到哪些父对象;真正的附着结果由 status.parents 体现。一个 Route 可以面对多个父对象,因此必须按目标 Gateway 对应的状态项判断,不能只看第一条 condition。
kubectl get httproute web -n demo -o yaml预期结果
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 授权。
kubectl get httproute web -n demo -o jsonpath='{range .status.parents[*]}{.parentRef.name}{"\t"}{range .conditions[*]}{.type}={.status}({.reason}){" "}{end}{"\n"}{end}'预期输出
edge Accepted=True(Accepted) ResolvedRefs=True(ResolvedRefs)不同实现的 reason 文本可能不同,应以实际输出为准。若看到 ResolvedRefs=False,继续检查后端引用:
kubectl get httproute web -n demo -o jsonpath='{.spec.rules[*].backendRefs[*].name}{"\n"}'
kubectl get service -n demo预期输出
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 也必须与真实请求一致。
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"}'预期输出
http HTTP 80
app.example如果入口地址为 <IP>,可直接发送带 Host 的请求,绕过 DNS 验证 Gateway 与 HTTPRoute 的数据面路径:
curl -i -H 'Host: app.example' http://<IP>/api/health预期输出
HTTP/1.1 200 OK
<HEADER>: <VALUE>
<RESPONSE_BODY>返回码与响应体由应用决定。若 Accepted=True、ResolvedRefs=True,但请求仍没有命中,重点核对 listener hostname、Route hostname、path match、规则优先级以及数据面是否已经完成编程。
检查后端和完成验收
Route 引用正确但 Service 没有可用 endpoint,同样会导致请求失败。最后检查 EndpointSlice,并再次观察 HTTPRoute 状态。
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}'预期输出
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
api-<ID> IPv4 8080 <IP> <TIME>
Accepted=True Accepted
ResolvedRefs=True ResolvedRefsGateway API 的优势之一就是把控制平面判断直接暴露在状态条件中。排查 HTTPRoute 时,应优先沿 Gateway → status.parents → Accepted/ResolvedRefs → listener 与匹配规则 → backendRefs → Service/EndpointSlice → 实际请求 的顺序推进,这比先查代理日志更容易快速锁定配置层问题。