原文发布于 quant67.com，转载请保留出处。
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。
一、相对站内已有内容，缺口在哪
下表列出各已有系列的视角，以及本系列补的格子。规则是：不重写已有内容，只填真正空着的格子。
| 已有内容 | 视角 | 本系列补什么 |
|---|---|---|
| k8s-network/18 | Gateway API 角色模型、资源图、EG v1.2 金丝雀实验 | 机制路径与失败模式；版本钉升到 GAPI v1.6.1 / EG v1.9.0 |
| cilium/15--16 | 东西向五轴 vs 南北向边界；Cilium Gateway 嵌入 Envoy | 独立实现的 CR→IR→xDS 内核；不重写 Cilium 身份/map |
| envoy/ 09--11、15--16 | 数据面 xDS 消费、warming/ACK、排除树 | 生产侧：EG 如何生成那棵资源树 |
| istio-xds/ | istiod watch→model→ADS；mesh HTTPRoute/GAMMA | 南北向 EG 翻译；不抢 GAMMA/istiod |
| network/60 | Nginx/HAProxy/Envoy/Traefik 产品对照 | 不重做产品勾选；只补 EG 控制面失败落格 |
结论 ：读者会贴 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：
| 门 | v1.9.0 事实 | 主篇 |
|---|---|---|
| TCPRoute / UDPRoute | 经 gateway.networking.k8s.io/v1 调和；未装 Gateway API v1.6 CRDs 则静默跳过，不是报错后才发现 |
08、12 |
| Lua EnvoyExtensionPolicy | 默认关闭 ；需 extensionApis.enableLua |
09 |
| tracing client sampling | 默认 0%（不再默认 100%） | 11 |
Policy mergeType |
仅允许挂 xRoute；挂 Gateway / ListenerSet 父资源被拒 | 09 |
二、五条坐标系（后续章节回指）
后面每一篇都落到下面某一条轴上。本篇钉名字、关键锚点与失败表象 ；具体生命周期、源码与停顿点在对应篇展开。排障口诀：先点名轴，再下钻模块------不要一上来改 HTTPRoute YAML 或重装控制器。
官方 System Design 把控制面拆成 Provider、Resource Watcher、Gateway API Translator（产出 Infra IR 与 xDS IR）、xDS Translator、基于 go-control-plane 的 Delta xDS Server、以及 Infra Manager。五轴是把这条管线按值班可核对的失败落格重新切开，而不是另造一套架构名词。
图：一次南北向配置沿五轴从 Gateway API 对象走到 Envoy，再进入入口之后的东西向 CNI。节点为英文，避免窄框折行；正文用中文解释每条轴。
| 轴 | 可核对锚点 | 失败表象 | 主篇 |
|---|---|---|---|
| 附着 / status | Accepted / Programmed / ResolvedRefs / RouteRulesOverlap；ReferenceGrant |
YAML 已 apply、条件未绿、跨 ns 引用被拒 | 02、13 |
| IR | Gateway API Translator 产出的 XdsIR / InfraIR | status 看似绿、IR 无对应 Listener/Route | 04、13 |
| xDS | xDS Translator + go-control-plane；xdsNACKTotal |
NACK、快照未送达、代理停在上一份 known-good | 05、11、13 |
| Envoy 数据面 | Filter 链、cluster、warming（外链 envoy 系列） | 监听器在、上游耗尽、证书/协议错 | 05、13；envoy/15 |
| 入口之后东西向 | Cilium 15 四元组：CNI 模式、KPR、加密、Gateway | Gateway 200 后后端 deny / 跨节点黑洞且 Hubble 无 drop | 15；cilium/13、cilium/15 |
附着 / 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 南北向控制面同时钉住三条不变量：
- 意图以 Gateway API 对象及其 status 为键，不以控制器日志为键 ：规范要求状态尽量写在对象上；
observedGeneration对不上metadata.generation时，status 本身就是过期证据。 - Gateway API 与 Envoy 资源树之间必须经过 IR ：多一跳换来的是 Provider 可替换、翻译顺序可测、status 与 IR 同一次
Translate计算。代价是排障必须问「IR 里有没有」，不能问「控制器开了没有」。 - 「控制面已推送」不等于「Envoy 在服务」，更不等于「后端 CNI 放行」：xDS ACK、warming、东西向策略是后两轴的事。
排障时先问「哪条不变量被触碰」，再落到对应轴。例如：跨 ns Secret 被拒 → 不变量 1；Accepted 仍 404 且 IR 无 route → 不变量 2；Gateway 200 后 Hubble deny → 不变量 3。
设计谱系：Ingress 表达力失败 → 角色导向 API → IR 编译管线
text
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- Ingress 的失败模式不是「没有反向代理」，而是 spec 只承载 host+path，高级能力逃进 annotation，换控制器即失效。Gateway API 概念页把这写成 Ingress 的结构性缺陷，并用角色分层资源取代单一 Ingress 对象。
- 声明式调和 （Burns, Grant, Oppenheimer, Brewer & Wilkes, Borg, Omega, and Kubernetes , ACM Queue 2016）给出「期望状态写在 API 对象上、控制器把实际状态推向期望」的生产范式。Envoy Gateway 的 Kubernetes provider 是这条范式在南北向入口上的实例：静态启动配置（
EnvoyGatewayAPI）只决定 watch 范围与 controllerName，动态配置全部来自集群对象。 - 生产分叉（v1.9.0） ：独立控制面把 Gateway API 译成 IR，再分别生成 xDS 与数据面舰队；Cilium Gateway 把南北向 L7 嵌进同一发行；Istio 走 istiod 的 CRD/HTTPRoute→xDS，并另开 GAMMA 东西向。三条路径共享 Gateway API 表面，不共享翻译内核。
| 维度 | Ingress / 早期 | Envoy Gateway v1.9.0 默认叙事 | 开放分叉 |
|---|---|---|---|
| 意图载体 | 单对象 + annotation | GatewayClass / Gateway / Route / EG Policy | 核心可移植 vs 扩展 CRD |
| 生效信号 | 控制器日志、Ingress status 稀疏 | Conditions：Accepted / Programmed / ResolvedRefs |
status 能否当 SLO |
| 编译 | 实现私有 | 显式 IR 两份（Xds / Infra） | IR 对账是否一等公民 |
| 数据面 | 各家代理 | Envoy v1.39 + Infra Manager 舰队 | 是否应内嵌进 CNI |
开放争论（先立靶，后各章拆）
| 争论 | A 侧 | B 侧 | 本系列落点 |
|---|---|---|---|
| 标准 API 可移植 vs 实现扩展 CRD | 核心 Route/Gateway 跨实现可搬 | SecurityPolicy 等 EG CRD 才能表达生产策略 | 第 9、14 篇 |
| status 条件当 SLO vs 只当排障线索 | 规范要求状态写在对象上 | Programmed 的「soon」由实现定义；IR/xDS 仍可能空 |
第 2、4、13 篇 |
| IR 多一层 vs 直接 CRD→xDS | 解耦、可测、Provider 可替换 | 排障多一跳；Istio 走另一条 | 第 4--5、14 篇 |
| 南北向独立控制面 vs CNI 内嵌 Gateway | 爆炸半径隔离、发布节奏解耦 | 品牌统一、world→ingress→Pod 观测链更短 | 第 14--16 篇；cilium/15 |
不在第 1 篇宣布胜负；每组争论要求后续篇给出可核对机制或选型边界，而不是「看业务场景」空话。本系列不比较未实测的延迟排行榜，只比较失败模式是否可归因到五轴中的某一层。
三、16 篇阅读路线与不写边界
| 路径 | 篇目 | 适合 |
|---|---|---|
| 必读核心 | 1 → 2 → 4 → 5 → 13 | 快速建立坐标系 |
| 版本门与策略 | 8 → 9 → 12 | 升级与 Policy 脚枪 |
| 对照选型 | 1 → 14 → 16 | 路径选型 |
| 完整通读 | 1 → ... → 16 | 系统掌握 |
先修：会读 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 篇结尾仍然够用：
- 一次南北向请求的失败落在哪一层？
- 为何
Accepted=True仍可能 404 / 无监听器？ - 为何不升 Gateway API CRDs 到 v1.6 时，TCP/UDP 路由会静默消失？
- Policy 写了不生效，是
mergeType、Lua 默认关，还是 Patch 匹配了旧 xDS 名？ - 何时选 Envoy Gateway，而非 Cilium Gateway / Istio / Ingress？
后续每一篇应能把问题收束到某一轴上的可核对锚点。若一篇写完仍只能回答「看场景」，说明证据或机制还不够。
本系列明确不写 ：Helm values 百科；把 gateway.envoyproxy.io/latest/ 的后版本能力写成 v1.9.0；伪造命令输出；把 Cilium identity/map 或 istiod GAMMA 再讲一遍；跨方案延迟榜。
四、小结
- 定位：补 k8s-network/18、cilium/15、envoy、istio-xds 之间的南北向控制面内核层，不重写产品百科或 Filter 全书。
- 五轴：附着/status、IR、xDS、Envoy 数据面、入口之后东西向；每轴有可核对锚点。
- 三不变量：status 写在对象上、必须经过 IR、「已推送」≠「在服务」≠「CNI 放行」。
- 谱系：Ingress 表达力失败 → Gateway API 角色导向 → Envoy Gateway v1.9.0 的 IR 编译管线。
- 路线：核心「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/UDPv1静默跳过、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/gatewaytag 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。实验台账：未跑。