Kubernetes Gateway API 深度实战：当 ingress-nginx 正式退役——从 Ingress 到 Gateway API 的生产级迁移完全指南（2026）

一、分水岭时刻：ingress-nginx 走入历史

2026 年 3 月，Kubernetes 社区正式宣布 ingress-nginx 控制器进入 EOL（End of Life）阶段。不再提供安全补丁，不再有 bug 修复，不再发布新版本。

这不仅仅是一个项目的退役——它标志着 Kubernetes 网络入口管理的十年范式宣告终结。

ingress-nginx 长期以来是全球部署量最大的 Kubernetes 入口控制器，据估计约 50% 的云原生环境依赖它。它的退役意味着数十万集群面临一个现实问题：下一步该往哪走？

答案已经很明确：Kubernetes Gateway API。

Gateway API 由 Kubernetes SIG-NETWORK 社区维护，经历了漫长的 beta 阶段后已于 2024 年正式进入 GA（General Availability），并在 2026 年持续演进到 v1.4 版本。它不是 Ingress 的"补丁升级"，而是一次根本性的架构重构。

本文将从程序员的实战视角出发，深入剖析 Gateway API 的设计哲学、核心架构、从 Ingress 迁移的完整流程，以及 Envoy Gateway、Istio、Cilium 等主流实现的生产级部署方案。无论你是正在规划迁移的架构师，还是想掌握新一代 Kubernetes 网络标准的开发者，这篇文章都能给你一个清晰的路线图。

二、为什么 Ingress 注定要被淘汰？

在讨论 Gateway API 之前，我们必须先理解：Ingress 到底哪里不行？

2.1 单体设计：一个对象扛所有职责

Ingress 的核心问题在于它的设计太简单了——简单到不够用。

Ingress 资源 = 基础设施配置 + 路由规则 + TLS 证书 + 注解hack

这种"什么都是，什么都不精"的设计，在 Kubernetes 早期的小规模集群中可以凑合。但当集群规模扩大、团队变多、流量复杂度提升时，问题就彻底暴露了。

角色混乱：管理负载均衡器的基础设施团队、管理网关策略的平台团队、定义路由规则的应用团队——这三类角色在 Ingress 中操作的是同一个资源对象。权限怎么分？改了路由会不会影响别人的服务？谁有权修改注解？全靠人工协调。

注解地狱：Ingress 的注解问题是 Kubernetes 社区公认的痛点。以灰度发布为例：

# Ingress 实现 Canary 发布——纯注解 hack
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  annotations:
    # NGINX 方式
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "10"
    nginx.ingress.kubernetes.io/canary-header: "X-Canary"
    nginx.ingress.kubernetes.io/use-regex: "true"
---
# 同样的需求，Traefik 的注解完全不同
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-app
  annotations:
    traefik.ingress.kubernetes.io/weighted-route: "canary@10"

从 NGINX 迁移到 Traefik？重写所有注解。从 Traefik 迁移到 AWS ALB？再重写一遍。注解把配置绑死在了特定控制器上，这从根本上破坏了可移植性。

2.2 表达力不足：高级功能全靠注解

Ingress 规范本身只支持最基本的 HTTP 路由：

• 基于路径的路由（Path-based routing）
• 基于域名的虚拟主机（Host-based routing）
• 简单的 TLS 终止

以下这些在 2026 年已经是标配的能力，Ingress 原生一个都不支持：

2.3 安全隐患："代码片段注入"

ingress-nginx 退役的另一个重要原因是安全问题。其核心注解机制 nginx.ingress.kubernetes.io/configuration-snippet 允许用户直接注入任意 NGINX 配置代码片段。这个功能在早期为灵活性加分，但在安全审计中却是噩梦——它等价于在集群中开了一个直接修改服务器配置的后门。

Kubernetes 安全审计工具多次标记该功能为高危风险。随着安全合规要求日益严格，这种"灵活但危险"的设计已不可持续。

三、Gateway API 的核心设计哲学

Gateway API 的设计不是"让 Ingress 更好用"，而是重新定义 Kubernetes 的服务网络模型。它的设计建立在四个核心原则之上。

3.1 面向角色（Role-Oriented）

这是 Gateway API 最大的创新，也是理解它的关键。

在真实的企业中，有三类人在和网络入口打交道：

1. 基础设施提供商（Infra Provider）——管理底层负载均衡器、云服务等基础设施
2. 集群操作员（Cluster Operator）——配置网关实例、TLS 证书、监听端口
3. 应用开发人员（App Developer）——定义路由规则，把流量引到自己的服务

Gateway API 为每个角色分配了独立的资源类型：

GatewayClass  →  基础设施提供商管理（集群级）
     ↓
Gateway      →  集群操作员管理（命名空间级）
     ↓
HTTPRoute    →  应用开发人员管理（命名空间级）

这意味着什么？开发人员不需要集群管理员权限就能配置自己的路由。

# 基础设施团队定义网关"类"
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway-class
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

---

# 平台团队实例化网关
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: ingress-system
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: wildcard-cert
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            gateway-access: "allowed"

---

# 应用开发人员定义路由（在自己的命名空间里）
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payment-service-route
  namespace: payment
spec:
  parentRefs:
  - name: production-gateway
    namespace: ingress-system
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2/payments
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: X-Request-Source
          value: gateway-api
    backendRefs:
    - name: payment-service
      port: 8080

通过 RBAC 配合，平台团队可以这样授权：

# 开发团队只能管理 HTTPRoute
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: route-manager
  namespace: payment
rules:
- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["httproutes", "grpcroutes"]
  verbs: ["get", "list", "watch", "create", "update", "delete"]
# 注意：没有 Gateway 和 GatewayClass 的权限

这就是真正的职责分离。开发人员在自己的命名空间里自治，平台团队控制基础设施，互不干扰。

3.2 可移植（Portable）

Gateway API 的核心规范（Core API）由所有实现共同遵守。高级功能不再是控制器特有的注解，而是标准化的 API 字段。

这意味着什么？你用 Envoy Gateway 写的 HTTPRoute 配置，可以几乎原封不动地迁移到 Istio、Cilium、Kong 或 Traefik 上。因为它们的字段定义是一样的——都来自同一份规范。

这是 Ingress 永远做不到的。

3.3 表达力强（Expressive）

所有高级流量管理能力都是一等公民：

• 多维度匹配（路径 + Header + 查询参数 + 方法）
• 权重流量分配（灰度发布）
• 请求镜像
• Header 增删改
• CORS 配置
• 超时/重试策略
• 请求/响应转换

3.4 可扩展（Extensible）

通过 Policy Attachment 机制，可以在任何层级附加自定义策略：

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: BackendTLSPolicy
metadata:
  name: require-mtls
spec:
  targetRefs:
  - group: ""
    kind: Service
    name: payment-service
    port: 8443
  tls:
    caCertificateRefs:
    - kind: ConfigMap
      name: internal-ca

四、核心资源模型详解

4.1 GatewayClass：网关的"类别"

GatewayClass 定义了网关的实现类型，类似于 StorageClass 之于 PV。它回答了"这个网关用什么控制器实现"的问题。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: envoy-proxy-config
    namespace: envoy-gateway-system
  description: "Envoy Gateway 控制器 - 高性能 L4/L7 网关"

controllerName 字段是实现控制器的标识符。Kubernetes 中部署的 Gateway API 控制器会 Watch 这个字段，自动管理匹配的 GatewayClass。

4.2 Gateway：网关的"实例"

Gateway 是集群中的具体网关实例，配置了监听器和路由策略。

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-web-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway
  infrastructure:  # v1.4 新增 - 基础设施配置
    parametersRef:
      group: ""
      kind: ConfigMap
      name: infra-config
  listeners:
  # HTTPS 主监听器
  - name: https-web
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - group: ""
        kind: Secret
        name: example-com-tls
      options:
        name: modern-tls-profile
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            access: web
  # gRPC 监听器
  - name: grpc-internal
    protocol: HTTPS
    port: 8443
    hostname: "grpc.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - group: ""
        kind: Secret
        name: grpc-tls
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            access: grpc
      kinds:
      - group: gateway.networking.k8s.io
        kind: GRPCRoute
  # TCP 透传（数据库直连）
  - name: tcp-db
    protocol: TCP
    port: 3306
    allowedRoutes:
      kinds:
      - group: gateway.networking.k8s.io
        kind: TCPRoute

这个配置展示了 Gateway API 的核心优势：一个 Gateway 实例可以同时承载多种协议的流量，这在 Ingress 中是不可能做到的。

4.3 HTTPRoute：HTTP 路由规则

HTTPRoute 是开发者日常使用最频繁的资源。它的 matches 字段提供了丰富的匹配能力：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-v2-route
  namespace: api-team
spec:
  parentRefs:
  - name: prod-web-gateway
    namespace: gateway-system
    sectionName: https-web  # 指定绑定的 Listener
  hostnames:
  - "api.example.com"
  rules:
  # 规则1：精确路径 + Header 匹配
  - matches:
    - path:
        type: Exact
        value: /api/v2/health
      headers:
      - name: X-Internal-Request
        value: "true"
    backendRefs:
    - name: health-checker
      port: 8080
  # 规则2：前缀匹配 + 多个 Filter
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2
      queryParams:
      - name: version
        value: "v2"
    filters:
    # 请求超时
    - type: RequestTimeout
      requestTimeout: "10s"
    # 重试策略
    - type: Retry
      retry:
        codes:
        - "502"
        - "503"
        - "504"
        attempts: 3
        perTryTimeout: "5s"
    # 请求 Header 修改
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-API-Version
          value: "v2"
        remove:
        - "X-Debug"
    backendRefs:
    - name: api-v2-service
      port: 8080
      weight: 90
    - name: api-v2-canary
      port: 8080
      weight: 10  # 10% 流量到金丝雀版本
  # 规则3：请求镜像
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2/analytics
    filters:
    - type: RequestMirror  # v1.3+ 功能
      requestMirror:
        backendRef:
          name: analytics-shadow
          port: 8080
        percentage: 100  # 100% 请求镜像
    backendRefs:
    - name: api-v2-service
      port: 8080

注意：权重流量分配（weight 字段）是 Gateway API 原生支持的，不需要任何注解。上面的配置直接实现了金丝雀发布：90% 流量到正式版本，10% 流量到金丝雀版本。

4.4 GRPCRoute、TCPRoute、UDPRoute、TLSRoute

Gateway API 的协议覆盖是完整的：

# gRPC 路由
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: user-service-grpc
spec:
  parentRefs:
  - name: prod-web-gateway
    namespace: gateway-system
    sectionName: grpc-internal
  hostnames:
  - "grpc.example.com"
  rules:
  - matches:
    - method:
        service: "user.v2.UserService"
        method: "GetProfile"
    backendRefs:
    - name: user-grpc-service
      port: 50051

---

# TCP 路由（直连数据库）
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: mysql-route
spec:
  parentRefs:
  - name: prod-web-gateway
    namespace: gateway-system
    sectionName: tcp-db
  rules:
  - backendRefs:
    - name: mysql-proxy
      port: 3306

---

# TLS 透传路由（后端服务自己处理 TLS）
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: legacy-secure
spec:
  parentRefs:
  - name: prod-web-gateway
    sectionName: tls-passthrough
  hostnames:
  - "legacy.example.com"
  rules:
  - backendRefs:
    - name: legacy-service
      port: 8443

4.5 ReferenceGrant：跨命名空间的安全桥梁

在多租户环境中，HTTPRoute 需要引用 Gateway（另一个命名空间），Service 可能需要引用其他命名空间的后端。ReferenceGrant 提供了这种跨命名空间引用的显式授权。

# 允许 payment 命名空间的 HTTPRoute 绑定到 gateway-system 的 Gateway
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-payment-to-gateway
  namespace: gateway-system
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: payment
  to:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: prod-web-gateway

---

# 允许 api-team 的路由引用 shared-namespace 的认证服务
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-api-to-auth-service
  namespace: shared-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: api-team
  to:
  - group: ""
    kind: Service
    name: auth-service

没有 ReferenceGrant 的跨命名空间引用会被拒绝——这是 Gateway API 安全模型的基石。

五、主流实现对比与选型指南

Gateway API 的生态系统已经非常成熟。以下是目前主要实现的对比：

5.1 实现全景图

5.2 选型决策树

你的情况是什么？
│
├── 正在用 ingress-nginx，想平滑迁移
│   → Nginx Gateway Fabric（最小改动）
│
├── 正在用/计划用 Istio 服务网格
│   → Istio（统一网关 + 网格）
│
├── 追求极致性能，有 eBPF 经验
│   → Cilium（内核级加速 + sidecar-less）
│
├── 需要最强的功能覆盖和最新特性
│   → Envoy Gateway（参考实现，迭代最快）
│
├── API 管理是核心需求（限流、认证、开发者门户）
│   → Kong（最成熟的 API 网关）
│
├── 团队小，运维资源有限
│   → Traefik（配置最简单）
│
└── 传统工作负载 + AI 推理混合场景
    → Kgateway（统一网关 + AI Gateway）

六、Envoy Gateway 生产级部署实战

Envoy Gateway 是 Gateway API 的参考实现，功能最全、迭代最快。下面我们用实际代码演示完整的生产级部署。

6.1 环境准备

# 创建 Kind 集群（实验环境）
kind create cluster --image kindest/node:v1.31.0

# 安装 Envoy Gateway
helm repo add oci https://oci.github.io/projects/envoy-gateway
helm install envoy-gateway oci://ghcr.io/envoyproxy/gateway-helm \
  --namespace envoy-gateway-system \
  --create-namespace

# 验证
kubectl get gatewayclass envoy-gateway-class

6.2 生产级 Gateway 配置

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: envoy-gateway-system
  labels:
    app.kubernetes.io/name: envoy-gateway
    app.kubernetes.io/environment: production
spec:
  gatewayClassName: envoy-gateway-class
  addresses:
  - type: IPAddress
    value: 10.0.0.100
  listeners:
  # 主站 HTTPS
  - name: https-primary
    protocol: HTTPS
    port: 443
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: wildcard-example-com
      options:
        name: tls-profile-modern  # TLS 1.3 only
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            gateway-access: production
  # HTTP → HTTPS 重定向
  - name: http-redirect
    protocol: HTTP
    port: 80
    hostname: "*.example.com"
    allowedRoutes:
      namespaces:
        from: Same
    # Envoy Gateway v1.4 自动配置 HTTP→HTTPS 重定向

6.3 灰度发布实战

# 生产版本 + 金丝雀版本
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web-app-route
  namespace: web-team
spec:
  parentRefs:
  - name: production-gateway
    namespace: envoy-gateway-system
  hostnames:
  - "www.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    # 正式版本 - 95% 流量
    - name: web-app-v2-stable
      port: 8080
      weight: 95
    # 金丝雀版本 - 5% 流量
    - name: web-app-v2-canary
      port: 8080
      weight: 5
    filters:
    # 限流保护
    - type: ExtensionRef
      extensionRef:
        group: gateway.envoyproxy.io
        kind: RateLimitFilter
        name: global-rate-limit
    # 超时配置
    - type: RequestTimeout
      requestTimeout: "30s"

灰度发布流程：

# 第1天：5% 金丝雀
kubectl patch httproute web-app-route \
  --type='json' -p='[{"op":"replace","path":"/spec/rules/0/backendRefs/1/weight","value":5}]'

# 观察指标，确认无异常...

# 第2天：提升到 20%
kubectl patch httproute web-app-route \
  --type='json' -p='[{"op":"replace","path":"/spec/rules/0/backendRefs/1/weight","value":20}]'

# 第3天：50%
# 第4天：80%
# 第5天：100% 全量，删除金丝雀

# 最终：完成发布，清理金丝雀
kubectl delete deployment web-app-v2-canary -n web-team

6.4 多租户隔离配置

# 租户A的 Gateway（独立监听器）
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tenant-a-gateway
  namespace: tenant-a-infra
spec:
  gatewayClassName: envoy-gateway-class
  listeners:
  - name: tenant-a-https
    protocol: HTTPS
    port: 443
    hostname: "tenant-a.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: tenant-a-cert
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            tenant: "a"

# 租户A的开发人员在 tenant-a-apps 命名空间里创建路由
# 通过 ReferenceGrant 授权 + RBAC 限制权限
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-api
  namespace: tenant-a-apps
spec:
  parentRefs:
  - name: tenant-a-gateway
    namespace: tenant-a-infra
  hostnames:
  - "tenant-a.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: tenant-a-api-svc
      port: 8080

七、从 Ingress 迁移的完整方案

7.1 迁移策略选择

策略一：全量重构（适合新集群或配置量少的环境）

直接用 Gateway API 重写所有 Ingress 配置。好处是一步到位，坏处是工作量大。

策略二：渐进式迁移（适合大规模生产环境，推荐）

阶段1：部署 Gateway API 控制器（与现有 Ingress 并行）
阶段2：新服务全部用 Gateway API
阶段3：分批将旧 Ingress 配置转换为 HTTPRoute
阶段4：验证流量，逐步切换 DNS/负载均衡器
阶段5：移除旧 Ingress 控制器

7.2 Ingress → HTTPRoute 配置转换示例

原 Ingress 配置：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "https://app.example.com"
spec:
  tls:
  - hosts:
    - "api.example.com"
    secretName: api-tls
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api/v2(/|$)(.*)
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 8080

转换后的 HTTPRoute 配置：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
spec:
  parentRefs:
  - name: production-gateway
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2
    filters:
    # 路径重写（替代 rewrite-target 注解）
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /
    # 超时（替代 proxy-connect/read-timeout 注解）
    - type: RequestTimeout
      requestTimeout: "300s"
    # CORS（替代 enable-cors 注解）
    - type: CORS
      cors:
        allowOrigins:
        - exact: "https://app.example.com"
        allowMethods:
        - "GET"
        - "POST"
        - "PUT"
        - "DELETE"
        allowHeaders:
        - "Authorization"
        - "Content-Type"
    # 金丝雀权重（替代 canary-weight 注解）
    backendRefs:
    - name: api-service
      port: 8080
      weight: 80
    - name: api-service-canary
      port: 8080
      weight: 20

关键变化：

• 所有注解被替换为结构化的 API 字段——类型安全、IDE 可补全、可校验
• 权重分配从字符串注解变成了原生 weight 整数字段
• CORS 配置从布尔开关变成了细粒度的策略声明

7.3 自动化迁移工具

对于大规模迁移，建议编写自动化脚本：

#!/bin/bash
# ingress-to-gateway-migrator.sh
# 将集群中所有 Ingress 资源转换为 HTTPRoute

for ns in $(kubectl get ingress --all-namespaces -o jsonpath='{.items[*].metadata.namespace}' | tr ' ' '\n' | sort -u); do
  echo "=== Processing namespace: $ns ==="
  kubectl get ingress -n $ns -o yaml > /tmp/ingress-$ns.yaml
  # 这里可以接入 convert 工具（如 kubectl ing2route 插件）
  # 或使用自定义的 conversion script
done

也可以使用社区的迁移工具（如 Helm chart 转换器）进行批量处理。

7.4 迁移验证清单

完成迁移后，必须逐项验证：

□ 所有 Ingress 注解已转换为 Gateway API 原生字段
□ TLS 证书引用正确（Secret/Certificate 资源位置正确）
□ 跨命名空间引用已添加 ReferenceGrant
□ RBAC 权限已更新（开发团队只有 Route 管理权限）
□ 灰度发布权重配置正确
□ 健康检查端点路由正常
□ 自定义 Header 路由行为一致
□ 压测结果与原 Ingress 性能对比在可接受范围
□ 监控告警已覆盖 Gateway API 资源
□ 回滚预案已就绪（保留旧 Ingress 配置备份）

八、可观测性：Gateway API 的监控体系

8.1 Prometheus 指标采集

Envoy Gateway 自动暴露 Prometheus 指标：

# ServiceMonitor 配置
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: envoy-gateway-metrics
  namespace: envoy-gateway-system
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: envoy-gateway
  endpoints:
  - port: metrics
    interval: 15s
    path: /stats/prometheus

关键指标包括：

8.2 访问日志与分布式追踪

# Envoy Gateway 访问日志配置
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: envoy-proxy-config
  namespace: envoy-gateway-system
spec:
  telemetry:
    accessLog:
      settings:
      - format: "%[START_TIME] %REQ(:METHOD) %REQ(X-ENVOY-ORIGINAL-PATH?:PATH) %PROTOCOL% %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %UPSTREAM_HOST% %UPSTREAM_CLUSTER% %UPSTREAM_SERVICE_TIME% %REQ(X-REQUEST-ID)% %REQ(:AUTHORITY)% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%"
      - formatType: JSON
        jsonFields:
        - name: "timestamp"
          value: "%START_TIME%"
        - name: "method"
          value: "%REQ(:METHOD)%"
        - name: "path"
          value: "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%"
        - name: "status_code"
          value: "%RESPONSE_CODE%"
        - name: "duration_ms"
          value: "%DURATION%"
        - name: "upstream_service_time"
          value: "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%"
        - name: "route_name"
          value: "%ROUTE_NAME%"
        - name: "upstream_host"
          value: "%UPSTREAM_HOST%"

分布式追踪（OpenTelemetry）：

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: envoy-proxy-config
spec:
  telemetry:
    tracing:
      provider:
        type: OpenTelemetry
        openTelemetry:
          host: otel-collector.monitoring.svc
          port: 4317
      samplingRate: 10  # 10% 采样率
      customTags:
        "gateway.name":
          type: Literal
          literal: "production-gateway"

九、GAMMA：Gateway API 的东西向扩展

GAMMA（Gateway API for Mesh Management and Administration）是 Gateway API 最令人兴奋的前沿方向之一。

传统上，Kubernetes 的流量管理分为两个割裂的世界：

• 南北向（Ingress）：管理外部到集群的流量
• 东西向（Service Mesh）：管理集群内部服务间的流量

GAMMA 的目标是用同一套 Gateway API 同时管理这两个方向的流量。

9.1 Cilium 的 sidecar-less 实现

Cilium 通过 eBPF 技术实现了无需 sidecar 的服务网格——这对资源消耗和运维复杂度是巨大的优化。

# 安装 Cilium（Gateway API + Mesh）
helm install cilium cilium/cilium \
  --namespace kube-system \
  --set gatewayAPI.enabled=true \
  --set mesh.enabled=true \
  --set hubble.enabled=true \
  --set hubble.relay.enabled=true

# 同一套 API 管理东西向流量
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: internal-auth-route
  namespace: auth
spec:
  parentRefs:
  - name: mesh  # Cilium Mesh 内置 Gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /auth
    backendRefs:
    - name: auth-service
      port: 8080

9.2 Istio 的 GAMMA 路线

Istio 1.24+ 已全面支持 Gateway API 作为默认的流量管理 API：

# Istio 中用 Gateway API 定义东西向策略
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: payment-to-inventory
  namespace: payment
spec:
  parentRefs:
  - name: istio-mesh  # Istio Mesh Gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /inventory
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Source-Service
          value: payment-service
    backendRefs:
    - name: inventory-service
      port: 8080

GAMMA 的意义：开发者只需要学一套 API（Gateway API），就能管理集群内外所有的流量。这是 Ingress + Service Mesh 两套 API 的巨大简化。

十、Gateway API 与 AI 工作负载

2026 年 AI 推理服务在 Kubernetes 上的部署已成常态。Gateway API 也开始向 AI 网关方向扩展。

10.1 Kgateway 的 AI Inference Extension

Kgateway 在 v1.3.0 中引入了 Inference Extension v1.0.0，支持 LLM 推理的路由管理：

apiVersion: inference.networking.x-k8s.io/v1alpha1
kind: InferenceRoute
metadata:
  name: llm-router
spec:
  parentRefs:
  - name: ai-gateway
  rules:
  - matches:
    - headers:
      - name: X-Model-ID
        value: "gpt-5"
    backendRefs:
    - name: gpt5-inference-svc
      port: 8000
      weight: 70
    - name: gpt5-fallback-svc
      port: 8000
      weight: 30
    filters:
    - type: InferenceRequestTimeout
      timeout: "120s"  # LLM 长超时

10.2 多模型路由与负载均衡

AI 推理网关的特殊需求：

• 模型级路由：根据请求中的模型 ID 路由到不同的 GPU 推理服务
• 长超时：LLM 推理可能需要数十秒甚至数分钟
• 流式响应：支持 SSE（Server-Sent Events）流式输出
• Token 级别计费：在网关层统计 Token 消耗
• 模型降级：当 GPU 服务过载时自动降级到轻量模型

这些需求正在推动 Gateway API 向 AI 推理场景扩展，预计将在 v1.5+ 版本中看到更多标准化支持。

十一、安全最佳实践

11.1 最小权限 RBAC

# 开发团队 Role（最小权限）
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gateway-route-editor
  namespace: team-a
rules:
- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["httproutes", "grpcroutes", "tcproutes"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
# 不能管理 Gateway、GatewayClass
# 不能管理 Secret（TLS 证书）
# 不能修改 ReferenceGrant（跨命名空间授权）

---

# 平台团队 ClusterRole（Gateway 管理）
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gateway-admin
rules:
- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["gatewayclasses", "gateways", "referencegrants"]
  verbs: ["*"]
- apiGroups: [""]
  resources: ["secrets"]  # TLS 证书管理
  verbs: ["get", "list", "watch", "create", "update"]

---

# 安全团队（策略管理）
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gateway-policy-admin
rules:
- apiGroups: ["gateway.networking.k8s.io"]
  resources: ["backendtlspolicies", "ratelimitpolicies", "securitypolicies"]
  verbs: ["*"]

11.2 TLS 安全加固

# TLS 监听器配置 - 安全加固
listeners:
- name: secure-https
  protocol: HTTPS
  port: 443
  tls:
    mode: Terminate
    certificateRefs:
    - kind: Secret
      name: production-tls
    options:
      name: tls-profile-modern  # TLS 1.3 only, 强密码套件
      # Envoy Gateway 支持 TLS Profile
      # modern: TLS 1.3 only
      # intermediate: TLS 1.2 + 1.3
      # old: 兼容老旧客户端（不推荐）

11.3 速率限制策略

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: RateLimitFilter
metadata:
  name: global-rate-limit
spec:
  type: Global
  global:
    rules:
    - clientSelectors:
      - sourceCIDR:
          type: CIDR
          value: "0.0.0.0/0"
      limit:
        requests: 1000
        unit: second
      # 每个 IP 每秒 1000 请求

十二、GitOps 集成

Gateway API 的声明式特性使其天然适合 GitOps 工作流：

# 项目结构
infra/
├── gateway-classes/
│   └── envoy-gateway-class.yaml
├── gateways/
│   ├── production-gateway.yaml
│   └── staging-gateway.yaml
├── policies/
│   ├── rate-limits/
│   └── tls-profiles/
apps/
├── api-team/
│   ├── httproutes/
│   │   └── api-v2-route.yaml
│   └── referencegrants/
├── payment-team/
│   └── httproutes/
└── web-team/
    └── httproutes/

# ArgoCD Application 示例
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: gateway-infra
  namespace: argocd
spec:
  project: infrastructure
  source:
    repoURL: https://github.com/your-org/k8s-configs.git
    targetRevision: main
    path: infra/gateways
  destination:
    server: https://kubernetes.default.svc
    namespace: envoy-gateway-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

每个应用团队管理自己的 HTTPRoute 配置，ArgoCD 自动同步到集群。平台团队通过 Gateway 的 allowedRoutes 控制谁可以把路由挂到哪个网关上。

GitOps 流程的核心价值：

1. 所有配置变更都有 Git 提交记录——可追溯、可审计
2. PR Review 机制——变更需要经过代码审查
3. 自动同步——消除手动 kubectl apply 的风险
4. 自动回滚——配置出错时 ArgoCD 自动回滚到上一个稳定状态

十三、性能调优实战

13.1 连接池与缓冲区

# Envoy Gateway 连接池优化
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: proxy-config
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: ClusterIP
  # 环境变量配置
  extraEnv:
  - name: ENVOY_CONCURRENCY
    value: "4"  # 每个 Envoy 实例的工作线程数

13.2 不同实现的性能特征

建议：根据你的主要流量类型选择实现。如果大部分是 L4 流量（TCP/UDP），Cilium 的 eBPF 加速有明显优势；如果是复杂的 L7 路由（HTTP/gRPC），Envoy Gateway 的表现最好。

13.3 高可用部署

# Envoy Gateway 高可用配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: envoy-gateway
  namespace: envoy-gateway-system
spec:
  replicas: 3  # 至少 3 副本
  selector:
    matchLabels:
      app: envoy-gateway
  template:
    metadata:
      labels:
        app: envoy-gateway
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                app: envoy-gateway
            topologyKey: topology.kubernetes.io/zone
        preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: envoy-gateway
              topologyKey: kubernetes.io/hostname
      topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: topology.kubernetes.io/zone
        whenUnsatisfiable: DoNotSchedule
        labelSelector:
          matchLabels:
            app: envoy-gateway

十四、未来展望：Gateway API 的下一个十年

14.1 规范演进路线

Gateway API 的演进方向：

• v1.4（2026 当前）：Infrastructure 字段、增强的 TLS Profile、改进的 GAMMA 支持
• v1.5：验证准入策略（Validating Admission Policy）、请求镜像进入 Core API、CORS 稳定化
• v1.6+：QUIC 协议支持、增强的 AI 推理网关特性、跨集群 Gateway 联邦

14.2 混合基础设施的统一网关

现代企业的工作负载已经不只在 Kubernetes 集群里——虚拟机、边缘计算、Serverless、AI 推理集群构成了混合的基础设施。Gateway API 正在向跨环境的统一应用接入层演进：

• 统一的路由策略（无论后端是 Pod、VM 还是边缘节点）
• 统一的安全执行（mTLS、OAuth、Zero Trust）
• 统一的可观测性（全链路追踪、指标聚合）

14.3 结论

ingress-nginx 的退役是一个时代的结束，也是另一个时代的开始。

Gateway API 不是 Ingress 的简单替代品，而是 Kubernetes 服务网络的"操作系统"——它为集群内外所有流量管理提供了统一的、声明式的、类型安全的 API 标准。

对于正在规划未来流量管理策略的组织：

1. 新项目：直接用 Gateway API，不要回头
2. ingress-nginx 用户：制定迁移计划，优先考虑 Nginx Gateway Fabric 或 Envoy Gateway
3. Istio/Cilium 用户：检查是否已升级到最新版本以支持 GAMMA
4. 大规模集群：采用渐进式迁移策略，分批次验证

Gateway API 的核心价值已经超越了技术本身——它代表了云原生网络管理的最佳实践：角色分离、声明式配置、类型安全、可移植性。这些原则将支撑 Kubernetes 网络管理的下一个十年。

参考资料

1. Kubernetes SIG-NETWORK. Gateway API Specification. https://gateway-api.sigs.k8s.io/
2. Kubernetes Documentation. Gateway API. https://kubernetes.io/docs/concepts/services-networking/gateway/
3. Envoy Gateway Documentation. https://gateway.envoyproxy.io/
4. Istio Documentation. Gateway API. https://istio.io/latest/docs/tasks/traffic-management/ingress/gateway-api/
5. Cilium Documentation. Gateway API. https://docs.cilium.io/en/latest/network/servicemesh/gateway-api/
6. Kubernetes Blog. Introducing Gateway API. 2024.
7. CNCF Blog. Ingress-nginx Retirement Announcement. 2026.