【Envoy Gateway】南北向全景：缺口、五轴坐标系与 16 篇路线

Kubernetes 网络 · Gateway API 已经把角色分离与 YAML 讲清，但钉在 Gateway API v1.2 / Envoy Gateway v1.2。Cilium 第 15 篇 只划南北向与东西向分工，把 Gateway 全书标为「仅边界」。Envoy 数据面 回答消费侧 ACK ≠ 生效；Istio 控制面 回答 istiod 如何翻译 mesh CRD。中间仍缺一层：一次南北向变更如何经附着与 status、Provider watch、Gateway API Translator 的 XdsIR/InfraIR、xDS Translator 与 Infra Manager 变成 Envoy 可服务的快照，以及相对 Cilium Gateway / Istio / Ingress 何时不该上 Envoy Gateway。

本文只做三件事：钉缺口、定义后续 15 篇共用的五条坐标系，并给出阅读路线。难点不在「会不会 Helm 装 Envoy Gateway」，而在控制面意图与数据面路径交界上的可核对字段——Accepted 相对 Programmed、IR 里有没有 Listener、xDS 是否 NACK、入口之后是否已经变成 Cilium 身份流。

本篇在系列中的位置

篇目	核心内容
第 1 篇 · 南北向全景	缺口、五轴坐标系、16 篇路线
第 2 篇 · 角色与附着	GatewayClass / Gateway / Route、parentRefs、status 条件
系列目录	关键问题、阅读路径、全部价值点

版本锚定：Envoy Gateway v1.9.0（源码 tag v1.9.0，发布 2026-08-14）。机制叙述对齐该 tag 下的 internal/gatewayapi、internal/provider、internal/ir、internal/xds，以及文档站点 gateway.envoyproxy.io/v1.9/。兼容矩阵把本发行编译进的数据面标为 Envoy distroless-v1.39.0、Gateway API v1.6.1，Kubernetes 支持 v1.33–v1.36。gateway.envoyproxy.io/latest/ 与 main 是滚动站点，不以 live 文档冒充本版本。无真实 Envoy Gateway 集群则不粘贴伪造 egctl / Route status / config_dump。

一、相对站内已有内容，缺口在哪

下表列出各已有系列的视角，以及本系列补的格子。规则是：不重写已有内容，只填真正空着的格子。

结论：读者会贴 HTTPRoute YAML、知道 Gateway API 有角色分离，也知道 Envoy ACK ≠ 生效，但不知道一次 watch 如何变成 XdsIR、为何 Accepted=True 仍无监听器、未装 v1.6 CRDs 时 TCPRoute 为何消失、SecurityPolicy 与 BackendTrafficPolicy 在 v1.9 的 mergeType 限制如何表现为「策略写了不生效」。本系列补「南北向 Gateway 控制面内核」那一格。

与通识教程的差别也在这里：多数「在 K8s 上装 Envoy Gateway」文章停在 quickstart 与一条 HTTPRoute；本系列追问 YAML apply 成功之后 404 / 无监听 / L4 静默消失仍落在哪一层，以及 status 绿、IR 空、xDS NACK、Envoy 仍服务旧快照、入口之后东西向 deny 各自如何表现。深度来自可证伪的阶段划分，而不是更长的功能清单。

k8s-network/18 的金丝雀实验输出属于 Envoy Gateway v1.2。那些命令结果、status 片段与字段全集不得当成 v1.9.0 事实；本系列只回收它的角色模型结论，不照抄实验台账。

本系列刻意不写 Helm values 百科、每个云厂商 ALB/NLB 控制台步骤、Envoy Filter / HCM / warming 全书、istiod 推送图与 GAMMA mesh 翻译全书、Cilium Gateway 配置菜谱、未实测「比 Ingress 快多少」排行榜。若目标只是「把 HTTPRoute 贴上」，18 与官方 Quickstart 已够；若目标是「失败落在哪一层 IR / 哪一次 xDS」，则必须沿五轴下钻。

本系列反复回指的版本门（不当本篇深挖）

官方 v1.9.0 Release Notes 与 Helm 安装说明把若干行为钉成升级破坏面。后面各篇会拆机制，本篇只登记为坐标系上的门，避免把 /latest 能力写进 v1.9.0：

二、五条坐标系（后续章节回指）

后面每一篇都落到下面某一条轴上。本篇钉名字、关键锚点与失败表象；具体生命周期、源码与停顿点在对应篇展开。排障口诀：先点名轴，再下钻模块——不要一上来改 HTTPRoute YAML 或重装控制器。

官方 System Design 把控制面拆成 Provider、Resource Watcher、Gateway API Translator（产出 Infra IR 与 xDS IR）、xDS Translator、基于 go-control-plane 的 Delta xDS Server、以及 Infra Manager。五轴是把这条管线按值班可核对的失败落格重新切开，而不是另造一套架构名词。

flowchart LR
  cr["GatewayClass Gateway HTTPRoute Policies"] --> provider["K8s Provider Watch"]
  provider --> gwapi["gatewayapi Translator"]
  gwapi --> xdsir["XdsIR"]
  gwapi --> infroir["InfraIR"]
  gwapi --> status["Status Manager"]
  infroir --> infra["Infra Manager Envoy fleet"]
  xdsir --> xdstr["xDS Translator"]
  xdstr --> server["go-control-plane Delta xDS"]
  infra --> envoy["Envoy v1.39 dataplane"]
  server --> envoy
  envoy --> cni["east-west CNI after hop"]

图：一次南北向配置沿五轴从 Gateway API 对象走到 Envoy，再进入入口之后的东西向 CNI。节点为英文，避免窄框折行；正文用中文解释每条轴。

附着 / status 轴

定义：GatewayClass、Gateway、Route 各自保证什么，以及 parentRefs、allowedRoutes、ReferenceGrant 如何决定一条 Route 是否进入翻译输入。

Gateway API 把 Ingress 拆成角色分层：基础设施提供者写 GatewayClass，集群运维写 Gateway（监听端口、TLS、谁可以附着），应用开发者写 Route。规范要求实现用 Conditions 报告对象状态。官方排障文档把三条正极性条件钉死：Accepted 表示对象语义上可被控制器接受并将产生某些数据面配置；Programmed 表示配置已解析并送往数据面、即将就绪（「soon」由实现定义）；ResolvedRefs 表示对象内引用都指向存在且合法的目标。

「YAML 已 apply 但没有任何 listener 地址」或「跨 namespace 的 backendRefs 被拒」优先落本轴，而不是先怀疑 Envoy Filter。本轴不承诺 Accepted=True 等于流量已通：v1.9.0 发行说明明确把 listener 未 Programmed（例如缺 TLS 证书）与 Route Accepted 拆开——Route 可以 Accepted，监听器仍未就绪。Gateway 级 Programmed 在 Kubernetes provider 里还要等 Envoy Service 地址与 Deployment/DaemonSet 可用副本（或 remote infra 就绪），所以「Accepted 绿、Programmed 仍 NoResources」是合法中间态。展开见 第 2 篇。

IR 轴

定义：Gateway API 对象被译成两份与 Envoy 资源树解耦的中间表示：XdsIR（给 xDS Translator）与 InfraIR（给 Infra Manager）。

官方 System Design 写明 IR 的目的是让控制面不跟外部资源的字段布局绑死。tag v1.9.0 的 Translator.Translate（internal/gatewayapi/translator.go）先 InitIRs，再按 Listener → Route → Policy 的顺序填充两份 map；失败的 Gateway 仍会占一个 IR 键，以免 Infra 侧把已拉起的舰队当删除事件清掉。

「status 看起来绿、数据面却没有对应 Listener」优先落本轴：翻译可能丢掉了不兼容 listener、未解析的 Secret，或根本没把该 Gateway 放进 accepted 集合。展开见 第 4 篇。

xDS 轴

定义：XdsIR 如何变成 LDS/RDS/CDS/EDS/SDS，以及 go-control-plane 的 Delta xDS 是否被代理 ACK。

本系列不在第 1 篇展开 Filter 链。v1.9.0 新增 xdsNACKTotal 指标，按 node ID 与 type URL 计数携带 ErrorDetail 的 DiscoveryRequest。NACK 之后代理停在上一份 known-good——这是消费侧 envoy/09–11 已经钉过的语义，本系列只补生产侧如何生成那棵树。主篇是第 5、11、13 篇。

Envoy 数据面轴

定义：配置已经进到 Envoy 进程之后，失败落在 Listener / FilterChainMatch / Cluster / warming 的哪一层。

本轴外链 Envoy 数据面内核，不在本系列重写 HCM、连接池或 Hot restart。南北向值班需要会读 config_dump 与 warming 状态，但那些字段的权威解释在 envoy 系列。本系列只要求：排除本轴之前，先能指出 IR 与 xDS 是否已经把那条 Listener 送出去。

入口之后东西向轴

定义：请求过了 Envoy Gateway 之后，失败如何交回 Cilium（或其他 CNI）的东西向坐标系，而不污染南北向五轴。

Cilium 15 的口令仍然成立：包还在集群外进入监听器时，先问 Gateway/Envoy；包已成为 Pod 身份之间的东西向流时，先问 identity / map / 加密。Gateway 200 之后的后端 deny、跨节点黑洞且 Hubble 无 drop，优先落本轴的四元组（CNI 模式、KPR、加密、Gateway），而不是先改 HTTPRoute。本系列第 15 篇回收北段/南段证据包，不重写 Cilium map。

坐标系背后的三个不变量

相对「只看 Ingress annotation」与「只看 Envoy admin」，Envoy Gateway 南北向控制面同时钉住三条不变量：

1. 意图以 Gateway API 对象及其 status 为键，不以控制器日志为键：规范要求状态尽量写在对象上；observedGeneration 对不上 metadata.generation 时，status 本身就是过期证据。
2. Gateway API 与 Envoy 资源树之间必须经过 IR：多一跳换来的是 Provider 可替换、翻译顺序可测、status 与 IR 同一次 Translate 计算。代价是排障必须问「IR 里有没有」，不能问「控制器开了没有」。
3. 「控制面已推送」不等于「Envoy 在服务」，更不等于「后端 CNI 放行」：xDS ACK、warming、东西向策略是后两轴的事。

排障时先问「哪条不变量被触碰」，再落到对应轴。例如：跨 ns Secret 被拒 → 不变量 1；Accepted 仍 404 且 IR 无 route → 不变量 2；Gateway 200 后 Hubble deny → 不变量 3。

设计谱系：Ingress 表达力失败 → 角色导向 API → IR 编译管线

Kubernetes Ingress（host+path + 不可移植 annotation）
  → Gateway API GEP：角色分离、可移植核心、Policy Attachment（GEP-713）、跨 ns 握手（GEP-709）
  → Envoy 控制面/数据面分裂（xDS；站内 envoy/ 展开消费侧）
  → Envoy Gateway：watch → Translator → XdsIR/InfraIR → xDS/Infra（工程系统）
  → 仍争：标准 API 可移植 vs 实现扩展 CRD 分裂；status 条件是否足以当「配置已生效」SLO

1. Ingress 的失败模式不是「没有反向代理」，而是 spec 只承载 host+path，高级能力逃进 annotation，换控制器即失效。Gateway API 概念页把这写成 Ingress 的结构性缺陷，并用角色分层资源取代单一 Ingress 对象。
2. 声明式调和（Burns, Grant, Oppenheimer, Brewer & Wilkes, Borg, Omega, and Kubernetes, ACM Queue 2016）给出「期望状态写在 API 对象上、控制器把实际状态推向期望」的生产范式。Envoy Gateway 的 Kubernetes provider 是这条范式在南北向入口上的实例：静态启动配置（EnvoyGateway API）只决定 watch 范围与 controllerName，动态配置全部来自集群对象。
3. 生产分叉（v1.9.0）：独立控制面把 Gateway API 译成 IR，再分别生成 xDS 与数据面舰队；Cilium Gateway 把南北向 L7 嵌进同一发行；Istio 走 istiod 的 CRD/HTTPRoute→xDS，并另开 GAMMA 东西向。三条路径共享 Gateway API 表面，不共享翻译内核。

开放争论（先立靶，后各章拆）

不在第 1 篇宣布胜负；每组争论要求后续篇给出可核对机制或选型边界，而不是「看业务场景」空话。本系列不比较未实测的延迟排行榜，只比较失败模式是否可归因到五轴中的某一层。

三、16 篇阅读路线与不写边界

flowchart TD
  overview["01 Overview"] --> attach["02 Attach Status"]
  attach --> provider["03 Provider Watch"]
  provider --> ir["04 IR Translator"]
  ir --> xds["05 xDS Infra"]
  xds --> http["06 HTTPRoute"]
  http --> tls["07 TLS SDS"]
  tls --> l4["08 L4 Routes"]
  l4 --> pol["09 Policies"]
  pol --> infra["10 EnvoyProxy"]
  infra --> obs["11 Observability"]
  obs --> ops["12 Ops Upgrade"]
  ops --> trouble["13 Troubleshoot"]
  trouble --> vs["14 vs Alternatives"]
  vs --> seam["15 East West Seam"]
  seam --> select["16 Selection"]
  overview --> select

先修：会读 Kubernetes YAML；强烈建议 envoy/09–11；可选 k8s-network/18、cilium/15。

阅读时建议随身带一张「轴 → 锚点」卡片：YAML 已 apply 条件未绿先问附着；Accepted 仍 404 先问 IR；NACK 或旧快照先问 xDS；监听器在上游耗尽先问数据面；Gateway 200 后后端黑洞先问东西向。把现象翻译成轴，比翻译成「重启 envoy-gateway Deployment」更接近本系列目标。

版本门不要在第 1 篇拆完，但读后续篇时应带着它们：升级 EG 而不升 Gateway API CRDs，L4 会在 Provider 轴静默缺席；Lua 与 tracing 默认值会让人以为「策略/观测没配上」；mergeType 挂错父资源会在 admission 被拒，根本进不了翻译。这些都不是「Envoy 比别人慢」，而是坐标系上的已知门闩。

五个关键问题到第 1 篇结尾仍然够用：

1. 一次南北向请求的失败落在哪一层？
2. 为何 Accepted=True 仍可能 404 / 无监听器？
3. 为何不升 Gateway API CRDs 到 v1.6 时，TCP/UDP 路由会静默消失？
4. Policy 写了不生效，是 mergeType、Lua 默认关，还是 Patch 匹配了旧 xDS 名？
5. 何时选 Envoy Gateway，而非 Cilium Gateway / Istio / Ingress？

后续每一篇应能把问题收束到某一轴上的可核对锚点。若一篇写完仍只能回答「看场景」，说明证据或机制还不够。

本系列明确不写：Helm values 百科；把 gateway.envoyproxy.io/latest/ 的后版本能力写成 v1.9.0；伪造命令输出；把 Cilium identity/map 或 istiod GAMMA 再讲一遍；跨方案延迟榜。

四、小结

1. 定位：补 k8s-network/18、cilium/15、envoy、istio-xds 之间的南北向控制面内核层，不重写产品百科或 Filter 全书。
2. 五轴：附着/status、IR、xDS、Envoy 数据面、入口之后东西向；每轴有可核对锚点。
3. 三不变量：status 写在对象上、必须经过 IR、「已推送」≠「在服务」≠「CNI 放行」。
4. 谱系：Ingress 表达力失败 → Gateway API 角色导向 → Envoy Gateway v1.9.0 的 IR 编译管线。
5. 路线：核心「1→2→4→5→13」；版本门「8→9→12」；选型「1→14→16」。

下一篇进入附着轴：没有 Accepted 与 Programmed 的语言，后面的 IR 空洞和「条件绿了仍 404」都无处锚定。

五、参考资料

规范 / 官方文档（A）

• Envoy Gateway v1.9.0 Release Notes — gateway.envoyproxy.io/news/releases/notes/v1.9.0/（TCP/UDP v1 静默跳过、Lua 默认关、tracing client sampling 0%、mergeType 仅 xRoute）。
• Envoy Gateway Compatibility Matrix — gateway.envoyproxy.io/news/releases/matrix/（v1.9：Envoy distroless-v1.39.0、Gateway API v1.6.1、Kubernetes v1.33–v1.36）。
• Envoy Gateway Concepts @ /v1.9/concepts/（资源表：GatewayClass / Gateway / Route / EG Policy）。
• Envoy Gateway System Design — gateway.envoyproxy.io/community/design/system-design/（Provider、Translator、IR、xDS、Infra Manager）。
• Gateway API v1.6 规范与排障文档 — gateway-api.sigs.k8s.io/reference/api-spec/1.6/spec/、docs/concepts/troubleshooting/（Accepted / Programmed / ResolvedRefs）。
• Gateway API GEP-713 Metaresources and Policy Attachment；GEP-709 Cross Namespace References（后更名为 ReferenceGrant）。

源码（A）

• envoyproxy/gateway tag v1.9.0：internal/gatewayapi/translator.go（Translator.Translate）、internal/ir/xds.go / internal/ir/infra.go、internal/provider/kubernetes/、go.mod（sigs.k8s.io/gateway-api v1.6.1）。

核心论文 / 奠基 work

• Burns, Grant, Oppenheimer, Brewer & Wilkes, Borg, Omega, and Kubernetes, ACM Queue 2016 —— 声明式调和与控制器回路。
• Gateway API GEP 过程文档（GEP Overview）—— 角色导向 API 相对 Ingress annotation 模型的分叉点。

实验 / 工具

• 本篇无集群命令输出；不写 RPS / 延迟数字，不粘贴伪造 egctl / status / config_dump。实验台账：未跑。

站内对照

• 系列目录
• Gateway API 产品教程（k8s-network/18，v1.2）
• Cilium Gateway / 南北向边界
• Envoy 数据面内核
• Istio 网格控制面

→ 系列目录 · 下一篇：角色与附着