容器与云原生 / 系统课时
排查入口地址异常
排查入口地址异常
当域名没有可用入口 IP、Gateway 长时间没有地址,或外部请求根本到不了网关时,不应先修改 Route。本课从 Gateway Condition、GatewayClass、数据面入口和外部连通性逐层采集证据,定位故障究竟发生在哪一层。
学习目标
- 根据 Gateway 的
Accepted、Programmed和地址状态判断故障阶段 - 检查 GatewayClass、控制器与承载入口的数据面资源
- 区分地址未分配、DNS 指向错误和地址存在但网络不可达的问题
先确认异常属于哪一层
入口地址异常可能表现为 Gateway 的 ADDRESS 为空、入口 Service 的 EXTERNAL-IP 长时间为 <pending>、DNS 指向错误,或者 Gateway 已有地址但客户端仍无法建立连接。这些现象相似,却分别属于控制面、地址供应、DNS 或外部网络路径。

排查应从 Kubernetes 控制面向外推进:先确认 Gateway 是否被接受,再判断控制器是否已经完成编程,然后检查 .status.addresses,最后追踪当前 Gateway 实现使用的数据面和外部网络资源。入口本身尚未建立时,反复修改 HTTPRoute 通常不会解决问题。
从 Gateway Condition 定位阶段
先查看完整 Gateway 状态。下面的命令同时取得 GatewayClass 名称,并收集 Gateway、GatewayClass 和常见 LoadBalancer Service 的证据。
GATEWAY=public-gateway
NAMESPACE=edge
CLASS=$(kubectl get gateway "$GATEWAY" -n "$NAMESPACE" -o jsonpath='{.spec.gatewayClassName}')
kubectl describe gateway "$GATEWAY" -n "$NAMESPACE"
kubectl get gatewayclass "$CLASS" -o wide
kubectl get service -A --field-selector spec.type=LoadBalancer -o wide预期输出
Name: public-gateway
Namespace: edge
...
Status:
Addresses:
Type: IPAddress
Value: <IP>
Conditions:
Type: Accepted
Status: True
...
Type: Programmed
Status: True
...
NAME CONTROLLER ACCEPTED AGE
example-gateway-class example.com/gateway-controller True <TIME>
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
<NS> <SERVICE> LoadBalancer <IP> <IP> 80:<PORT>/TCP <TIME>实际字段、Condition 顺序以及数据面资源名称由 Gateway 实现决定。Accepted=False 表示 Gateway 尚未被控制器接受,此时优先读取对应 Condition 的 reason 和 message,检查 GatewayClass、Listener 参数和实现支持范围。
Accepted=True 后再看 Programmed。Programmed=False 表示实现尚未完成所需的数据面或基础设施编程;原因可能是资源不足、地址无法分配或配置无法落地。部分实现会给出类似 AddressNotAssigned 的原因,但不要只依赖原因名称,应结合 message 与控制器状态判断。
最后检查 .status.addresses。地址为空说明 Gateway 尚没有可供客户端使用的入口地址;出现 IPAddress 或 Hostname 后,才能继续判断 DNS 与外部网络是否正常。
检查 GatewayClass 与数据面
Gateway 引用的 GatewayClass 必须存在并处于已接受状态。GatewayClass 的 .spec.controllerName 表明哪个 Gateway 实现负责这个 Class;如果 Class 未被接受,或对应控制器没有正常工作,Gateway 的编程与地址分配通常也不会正常完成。
许多实现会创建或使用 LoadBalancer 类型的 Service 承载数据面,但 Gateway API 并不要求所有实现都采用这种模型。因此,前面列出的 LoadBalancer Service 只能作为线索,不能仅凭名称猜测它与 Gateway 的关系。应结合实现生成的标签、OwnerReference、控制器文档或部署清单确认真正的数据面资源。
如果已确认某个 LoadBalancer Service 属于该 Gateway,而其 EXTERNAL-IP 长时间为 <pending>,故障通常已经落到地址供应层。例如云控制器权限不足、负载均衡配额耗尽、地址池没有空闲地址,或裸机集群没有部署能够为 LoadBalancer Service 提供地址的实现。此时继续修改 HTTPRoute 没有意义。
地址出现后验证 DNS 与外部连通性
Gateway 获得 IP 后,可以用 curl --resolve 暂时绕过 DNS,把业务域名直接绑定到 Gateway 地址。这样既能使用指定 IP 建立连接,又会保留正确的 HTTP Host 和 TLS SNI,适合区分 DNS 故障与入口网络故障。
curl -vk --connect-timeout 5 --resolve app.example.com:443:<IP> https://app.example.com/预期结果
* Connected to app.example.com (<IP>) port 443
...
< HTTP/<VERSION> <STATUS><IP>、<VERSION> 和 <STATUS> 会随环境变化。这里使用 -k 是为了排查连接与路由链路时避免证书校验干扰判断,并不代表生产环境可以忽略证书错误。如果 .status.addresses 返回 Hostname,应先解析该主机名得到实际 IP,再进行等价的 --resolve 测试。
如果连接在 TCP 或 TLS 阶段失败,应继续检查负载均衡监听、安全组、防火墙、路由以及地址供应系统。如果连接成功并收到 404、503 等 HTTP 响应,请求实际上已经到达入口,此时应转向 Listener、HTTPRoute、BackendRef 和后端 Service,而不是继续排查地址分配。
按现象选择下一步
| 现象 | 判断重点 | 下一步 |
|---|---|---|
.status.addresses 为空,或已确认的 LoadBalancer Service 为 <pending> |
地址尚未成功供应 | 检查 Gateway Condition、控制器和地址供应系统 |
Gateway 已有地址,但 curl --resolve 无法建立 TCP/TLS 连接 |
外部网络路径异常 | 检查负载均衡监听、防火墙、安全组和路由 |
curl --resolve 能收到 HTTP 响应 |
请求已经到达网关 | 排查 Listener、HTTPRoute、BackendRef 与后端 Service |
有效的定位顺序是先读 Gateway Condition,再确认 GatewayClass 与控制器,随后检查 .status.addresses 和当前实现的数据面资源,最后从外部直接验证连接。这样可以把“没有入口地址”“地址存在但网络不可达”和“请求已到网关但路由失败”明确分开。