容器与云原生 / 系统课时

排查入口 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>、响应头和响应体均为动态值,实际环境可能不同。

bash
INGRESS_IP='<IP>'
curl -i -H 'Host: api.example.com' "http://${INGRESS_IP}/orders"

预期输出

text
HTTP/1.1 404 Not Found
<HEADERS>

<VALUE>

404 本身不能证明路由没有命中。若入口访问日志已记录路由名、上游集群和 Envoy 响应标记,应结合这些字段判断来源;其中 NR 表示没有找到可匹配的路由。若请求已经命中路由并转发到上游,则还要考虑 404 是否由应用自身返回。

入口 404 从请求匹配到 Envoy 路由表的定位流程

检查入口对象和路由绑定

使用 Kubernetes Gateway API 时,不要只看 spec,还要检查控制器写回的 status.conditions。Gateway 至少应被接受并编程到数据面;HTTPRoute 在目标父级下通常应看到 Accepted=True 和 ResolvedRefs=True。

bash
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)"'

预期输出

text
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。

bash
kubectl -n demo get virtualservice api-route -o yaml

预期结果中应能看到与请求相符的绑定和匹配条件,例如:

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,实际名称不同应相应替换。

bash
istioctl proxy-status

预期输出

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

bash
istioctl proxy-config routes deployment/istio-ingressgateway.istio-system -o json | jq '[.[] | .virtualHosts[]? | select(any(.domains[]?; . == "api.example.com")) | {name, domains, routes}]'

预期输出

json
[
  {
    "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 已同步,再重放最初固定的请求。

bash
INGRESS_IP='<IP>'
curl -i -H 'Host: api.example.com' "http://${INGRESS_IP}/orders"

预期输出

text
HTTP/1.1 200 OK
<HEADERS>

<VALUE>

如果 Envoy 路由表已经包含目标 Host 和 Path,但请求仍返回 404,应继续检查是否命中了另一条更具体的规则、是否发生了 URI 重写,以及 404 是否来自后端应用。排查入口 404 的关键,是分别验证“声明配置看起来正确”和“这条真实请求确实在目标 Envoy 上命中路由”。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查入口 404 与路由不命中

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

登录哪都通