容器与云原生 / 系统课时

理解 Gateway API 状态条件

理解 Gateway API 状态条件

Gateway、Listener 和 HTTPRoute 能成功创建,并不代表入口流量已经生效。本课从 status.conditions 入手,判断配置是否被接受、对象引用是否解析成功、控制器是否处理到当前版本,并用 observedGeneration 排除读取旧状态造成的误判。

学习目标

  • 读懂 Accepted、ResolvedRefs、Programmed 等关键 Condition 的含义与边界
  • 找到 Gateway、Listener 与 HTTPRoute 对应的状态位置
  • 用 observedGeneration 判断 Condition 是否针对当前配置版本

为什么先看状态条件

kubectl apply 成功只说明 API Server 接受并保存了对象。随后 Gateway API 控制器还要校验 Listener、Route 附着关系、对象引用和实现能力,并把协调结果写入 status。因此排障时应先读 Condition,而不是只确认资源能否 get 到。

一个 Condition 不能只看 status=True/False/Unknown。type 表示检查项,reason 和 message 解释原因,observedGeneration 表示这份判断针对哪个资源版本。Accepted=True 表示对应配置已被控制器接受;ResolvedRefs=True 表示相关引用能够解析且引用关系被允许;Gateway 上的 Programmed=True 表示实现已完成相应的数据面编程确认,但它不是端到端业务健康证明。

不同资源、Gateway API 版本和实现暴露的 Condition 集合并不完全相同。尤其对 HTTPRoute,应把 Accepted 和 ResolvedRefs 作为标准排查重点,不要把 Programmed 当成所有 Route parent 都必须出现的固定条件。

Gateway API 资源状态条件与生效链路

从三个层级读取状态

Gateway 的总体状态位于 status.conditions,每个 Listener 则在 status.listeners[] 中拥有独立状态。即使 Gateway 总体已被接受,某个 Listener 仍可能因为引用、协议或冲突问题不可用,因此要按 name 找到目标 Listener,再读取它的 Conditions。

HTTPRoute 的状态按父对象记录在 status.parents[]。一个 Route 可以关联多个 Gateway,也可能由不同控制器处理,因此排查某条入口路径时,应根据 parentRef 和 controllerName,必要时结合 sectionName,定位正确的 parent 条目。

先查看完整状态:

bash
kubectl get gateway web-gateway -o yaml
kubectl get httproute shop-route -o yaml

预期结果

yaml
# Gateway 状态摘要
status:
  conditions:
  - type: Accepted
    status: "True"
  - type: Programmed
    status: "True"
  listeners:
  - name: http
    conditions:
    - type: Accepted
      status: "True"

# HTTPRoute 状态摘要
status:
  parents:
  - parentRef:
      name: web-gateway
    controllerName: <VALUE>
    conditions:
    - type: Accepted
      status: "True"
    - type: ResolvedRefs
      status: "True"

控制器名称、Condition 顺序、reason 和 message 会随环境变化。这里刻意不在 HTTPRoute 示例中加入 Programmed:如果当前实现额外报告了它,可以作为补充证据;如果没有,不能仅凭缺少该条件就判定 Route 异常。

用 Condition 缩小故障范围

对 HTTPRoute 而言,Accepted=False 首先指向“Route 没有被这个 parent 接受”。常见方向包括目标 Gateway 或 Listener 不匹配、allowedRoutes 不允许该 Route,以及 hostname 等附着约束不满足。此时优先处理 Route 与 Listener 的附着关系,不要直接跳到后端网络。

ResolvedRefs=False 更接近“Route 内部引用存在问题”,例如 Backend Service 不存在、端口无效、引用类型不受支持,或跨 Namespace 引用缺少所需授权。排查时应同时读取 reason 和 message,用它们定位具体引用,而不是只记录一个 False。

Gateway 上的 Programmed=False 或 Unknown 表示控制器尚未确认完成对应的编程阶段。应先检查 Accepted 和 Listener 状态,再查看控制器与数据平面。即使看到 Programmed=True,也仍需用真实请求验证 DNS、TLS、Service、Pod 和网络路径。

确认状态对应当前版本

修改 spec 后,metadata.generation 会增长,而控制器需要时间重新协调。如果某个 Condition 的 observedGeneration 小于当前 metadata.generation,这份状态仍可能对应旧配置,不能据此确认本次变更已经生效。

可以把当前 generation 与 HTTPRoute parent 下的 Conditions 一起打印:

bash
kubectl get httproute shop-route -o jsonpath='{.metadata.generation}{"\n"}{range .status.parents[*].conditions[*]}{.type}{"="}{.status}{" observed="}{.observedGeneration}{"\n"}{end}'

预期输出

text
<VALUE>
Accepted=True observed=<VALUE>
ResolvedRefs=True observed=<VALUE>

数字取决于资源修改次数,实际环境也可能出现更多 Condition。只有目标 parent 的关键 Condition 已更新,且 observedGeneration 与当前 metadata.generation 一致时,才说明正在读取当前配置版本的判断。

建立固定的状态排查顺序

实际排障可保持稳定顺序:先看 Gateway 的总体 Conditions,再检查目标 Listener;随后在 HTTPRoute 的 status.parents[] 中定位正确 parent,确认 Accepted、ResolvedRefs 以及实现实际提供的其他 Conditions;最后核对 observedGeneration 是否追上当前 generation。

只有控制面状态与当前配置版本一致、关键条件符合预期后,再进入入口地址、DNS、TLS、Service、Pod 和网络路径等数据面检查。这样可以避免在 Route 尚未被接受或引用尚未解析时,过早把问题误判为网络故障。

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

目录与阅读设置

记录一个想法

理解 Gateway API 状态条件

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

登录哪都通