容器与云原生 / 系统课时
排查入口 404 与路由不命中
排查入口 404 与路由不命中
入口返回 404 时,重点不是反复修改路由 YAML,而是确认请求在哪一层失去匹配。按“请求事实 → Gateway 或 VirtualService 状态 → Envoy 实际路由表 → 原请求复测”的顺序检查,可以快速区分请求条件不符、配置未被接受和配置未下发到数据面的情况。
学习目标
- 能判断 404 是入口代理路由不命中,还是后端应用返回
- 能检查 Gateway API 或 Istio VirtualService 的绑定与匹配条件
- 能用
istioctl proxy-config routes验证入口 Envoy 实际收到的路由
固定失败请求并确认 404 来源
排查前先固定 Host、Path、Method 和关键 Header,后续始终重放同一请求。下面假设入口地址已知,请求 api.example.com/orders 当前返回 404;<IP>、响应头和响应体均为动态值,实际环境可能不同。
INGRESS_IP='<IP>'
curl -i -H 'Host: api.example.com' "http://${INGRESS_IP}/orders"预期输出
HTTP/1.1 404 Not Found
<HEADERS>
<VALUE>404 本身不能证明路由没有命中。若入口访问日志已记录路由名、上游集群和 Envoy 响应标记,应结合这些字段判断来源;其中 NR 表示没有找到可匹配的路由。若请求已经命中路由并转发到上游,则还要考虑 404 是否由应用自身返回。

检查入口对象和路由绑定
使用 Kubernetes Gateway API 时,不要只看 spec,还要检查控制器写回的 status.conditions。Gateway 至少应被接受并编程到数据面;HTTPRoute 在目标父级下通常应看到 Accepted=True 和 ResolvedRefs=True。
kubectl -n edge get gateway public-gateway -o json | jq -r '.status.conditions[] | select(.type == "Accepted" or .type == "Programmed") | "\(.type)=\(.status)"'
kubectl -n demo get httproute api-route -o json | jq -r '.status.parents[].conditions[] | select(.type == "Accepted" or .type == "ResolvedRefs") | "\(.type)=\(.status)"'预期输出
Accepted=True
Programmed=True
Accepted=True
ResolvedRefs=True若 Accepted=False,优先检查 parentRefs、目标 listener、allowedRoutes 以及 Route 与 listener hostname 是否存在交集;若 ResolvedRefs=False,检查后端 Service、端口和跨命名空间引用,跨命名空间 BackendRef 还可能需要 ReferenceGrant。状态为空时,应确认 GatewayClass 是否由预期控制器接管。
如果入口使用 Istio Gateway 与 VirtualService,则重点检查 VirtualService.spec.gateways、hosts 和 http.match 是否与真实请求一致。下面读取当前配置;如果环境已经使用 Gateway API,则不需要为了相同流量再维护一份 VirtualService。
kubectl -n demo get virtualservice api-route -o yaml预期结果中应能看到与请求相符的绑定和匹配条件,例如:
spec:
gateways:
- edge/public-gateway
hosts:
- api.example.com
http:
- match:
- uri:
prefix: /orders常见问题包括 Host 写错、Path 前缀不一致、Method 或 Header 条件过严,以及 VirtualService 没有绑定到实际处理该流量的 Gateway。若 Istio Gateway 以 SIMPLE 或 MUTUAL 模式终止 HTTPS,解密后的 HTTP 请求由 http 路由匹配;tls 路由主要用于 TLS 未在该 Gateway 终止的场景。
以 Envoy 路由表确认下发结果
声明对象正确并不代表入口代理已经收到配置。先查看代理与 Istiod 的同步状态,再直接读取入口 Envoy 的 Route Configuration。以下示例假设入口工作负载为 deployment/istio-ingressgateway.istio-system,实际名称不同应相应替换。
istioctl proxy-status预期输出
NAME CDS LDS EDS RDS ISTIOD VERSION
istio-ingressgateway-<ID>.istio-system SYNCED SYNCED SYNCED SYNCED <VALUE> <VALUE>若该代理的 RDS 未同步,应先处理数据面与 Istiod 的配置同步问题;代理完全不在列表中,则检查入口 Pod 状态以及它与控制面的连接。
继续读取真实路由表,并过滤声明了 api.example.com 的 virtual host:
istioctl proxy-config routes deployment/istio-ingressgateway.istio-system -o json | jq '[.[] | .virtualHosts[]? | select(any(.domains[]?; . == "api.example.com")) | {name, domains, routes}]'预期输出
[
{
"name": "<VALUE>",
"domains": [
"api.example.com"
],
"routes": [
{
"match": {
"prefix": "/orders"
},
"route": {
"cluster": "<VALUE>"
}
}
]
}
]具体字段可能因路由配置而略有差异,但应能在目标 virtual host 中找到与 /orders 对应的匹配规则。若过滤结果为 [],说明目标 Host 的规则没有进入该入口 Envoy,此时应回查 Route 或 VirtualService 的绑定、作用域和控制面状态,而不是继续修改后端 Service。
修复并按原请求复测
修复时一次只调整一个条件,例如 hostname、Path 或 Gateway 绑定,避免多个修改同时掩盖根因。应用配置后,先确认对象状态正常且 RDS 已同步,再重放最初固定的请求。
INGRESS_IP='<IP>'
curl -i -H 'Host: api.example.com' "http://${INGRESS_IP}/orders"预期输出
HTTP/1.1 200 OK
<HEADERS>
<VALUE>如果 Envoy 路由表已经包含目标 Host 和 Path,但请求仍返回 404,应继续检查是否命中了另一条更具体的规则、是否发生了 URI 重写,以及 404 是否来自后端应用。排查入口 404 的关键,是分别验证“声明配置看起来正确”和“这条真实请求确实在目标 Envoy 上命中路由”。