容器与云原生 / 系统课时
理解 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 的总体状态位于 status.conditions,每个 Listener 则在 status.listeners[] 中拥有独立状态。即使 Gateway 总体已被接受,某个 Listener 仍可能因为引用、协议或冲突问题不可用,因此要按 name 找到目标 Listener,再读取它的 Conditions。
HTTPRoute 的状态按父对象记录在 status.parents[]。一个 Route 可以关联多个 Gateway,也可能由不同控制器处理,因此排查某条入口路径时,应根据 parentRef 和 controllerName,必要时结合 sectionName,定位正确的 parent 条目。
先查看完整状态:
kubectl get gateway web-gateway -o yaml
kubectl get httproute shop-route -o 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 一起打印:
kubectl get httproute shop-route -o jsonpath='{.metadata.generation}{"\n"}{range .status.parents[*].conditions[*]}{.type}{"="}{.status}{" observed="}{.observedGeneration}{"\n"}{end}'预期输出
<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 尚未被接受或引用尚未解析时,过早把问题误判为网络故障。