容器与云原生 / 系统课时

排查入口地址异常

排查入口地址异常

当域名没有可用入口 IP、Gateway 长时间没有地址,或外部请求根本到不了网关时,不应先修改 Route。本课从 Gateway Condition、GatewayClass、数据面入口和外部连通性逐层采集证据,定位故障究竟发生在哪一层。

学习目标

  • 根据 Gateway 的 Accepted、Programmed 和地址状态判断故障阶段
  • 检查 GatewayClass、控制器与承载入口的数据面资源
  • 区分地址未分配、DNS 指向错误和地址存在但网络不可达的问题

先确认异常属于哪一层

入口地址异常可能表现为 Gateway 的 ADDRESS 为空、入口 Service 的 EXTERNAL-IP 长时间为 <pending>、DNS 指向错误,或者 Gateway 已有地址但客户端仍无法建立连接。这些现象相似,却分别属于控制面、地址供应、DNS 或外部网络路径。

Gateway 入口地址异常的分层排查路径

排查应从 Kubernetes 控制面向外推进:先确认 Gateway 是否被接受,再判断控制器是否已经完成编程,然后检查 .status.addresses,最后追踪当前 Gateway 实现使用的数据面和外部网络资源。入口本身尚未建立时,反复修改 HTTPRoute 通常不会解决问题。

从 Gateway Condition 定位阶段

先查看完整 Gateway 状态。下面的命令同时取得 GatewayClass 名称,并收集 Gateway、GatewayClass 和常见 LoadBalancer Service 的证据。

bash
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

预期输出

text
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 故障与入口网络故障。

bash
curl -vk --connect-timeout 5 --resolve app.example.com:443:<IP> https://app.example.com/

预期结果

text
* 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 和当前实现的数据面资源,最后从外部直接验证连接。这样可以把“没有入口地址”“地址存在但网络不可达”和“请求已到网关但路由失败”明确分开。

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

目录与阅读设置

记录一个想法

排查入口地址异常

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

登录哪都通