Kubernetes Gateway API 深度实战：从 Ingress 废墟到下一代流量治理的完全指南（2026）

引言：为什么你该在 2026 年彻底扔掉 Ingress？

如果你做过 Kubernetes 集群运维，一定经历过这种痛苦：不同 Ingress Controller 的 annotations 完全不兼容，从 nginx-ingress 迁移到 Traefik 简直就是重写配置；想做灰度发布？只能靠自定义 annotations 各种 hack；TCP/gRPC 流量路由？对不住了，大部分 Ingress Controller 要么不支持，要么需要写一堆非标准配置。

2022 年 Gateway API 进入 Kubernetes 1.24 作为 Alpha 特性，到 2024 年 v1.0 正式 GA，再到 2026 年的 v1.3，这套 API 已经成为 Kubernetes 流量治理的事实标准。Envoy Gateway、Istio、Cilium、Nginx Gateway Fabric 等主流实现全部支持。本文将从架构设计到生产实战，带你全面掌握 Gateway API。

一、Ingress 的设计原罪：为什么它注定被淘汰

1.1 单一资源承载过多职责

Ingress 的核心问题是「一个 API 资源试图解决所有流量治理问题」。在实际项目中，一个 Ingress 资源往往承载了：

• 路由规则
• TLS 终止配置
• 限流策略
• CORS 设置
• 请求头改写
• 认证策略

所有这些功能全部堆在 annotations 里，而 annotations 最大的问题是——不标准。

# Nginx Ingress 的限流注解
nginx.ingress.kubernetes.io/limit-rps: "100"

# Traefik 的限流注解（完全不同的格式！）
traefik.ingress.kubernetes.io/rate-limit.average: 100

当你需要从 Nginx 迁移到 Traefik，或者同时使用两个 Ingress Controller 时，配置兼容性简直是噩梦。

1.2 角色混乱：谁该管什么？

在真实的企业环境中，流量治理涉及三个角色：

Ingress 没有任何角色分离机制。集群管理员和应用开发者都要修改同一个 Ingress 资源，RBAC 权限控制非常粗糙——你要么能改整个 Ingress，要么完全不能碰。

1.3 功能覆盖不足

二、Gateway API 架构设计：三层分离模型

2.1 核心设计哲学

Gateway API 的设计遵循三个原则：

1. 面向角色（Role-oriented）：不同角色操作不同的 API 资源
2. 可扩展（Extensible）：通过标准化的 Filter 机制扩展功能
3. 表达力丰富（Expressive）：原生支持高级路由匹配、流量管理等

┌─────────────────────────────────────────────────────────┐
│                    基础设施提供者                          │
│  GatewayClass（定义网关类型，类似 StorageClass）             │
├─────────────────────────────────────────────────────────┤
│                    集群管理员                              │
│  Gateway（创建具体网关实例，管理监听器）                     │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Listener │  │ Listener     │  │ Listener     │       │
│  │ :80 HTTP │  │ :443 HTTPS   │  │ :8443 gRPC   │       │
│  └──────────┘  └──────────────┘  └──────────────┘       │
├─────────────────────────────────────────────────────────┤
│                    应用开发团队                            │
│  HTTPRoute / GRPCRoute / TCPRoute（定义路由规则）           │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │ api-v1 (90%) │  │ api-v2 (10%) │ ← 流量加权          │
│  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────┘

2.2 四个核心资源

GatewayClass：基础设施层

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
  description: "生产级 Envoy Gateway 实现"
  parametersRef:
    group: gateway.envoyproxy.io
    kind: EnvoyProxy
    name: proxy-config
    namespace: envoy-gateway-system

GatewayClass 类似于 StorageClass，它定义了「用什么实现来创建 Gateway」。不同的 controllerName 对应不同的网关实现：

• gateway.envoyproxy.io/gatewayclass-controller → Envoy Gateway
• istio.io/gateway-controller → Istio
• io.cilium/gateway-controller → Cilium Gateway
• nginx.org/gateway-controller → Nginx Gateway Fabric

Gateway：集群管理层

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: envoy-gateway
  addresses:
    - type: IPAddress
      value: 10.0.1.100  # 可以指定固定 IP（LoadBalancer 自动分配）

  listeners:
    # 监听器 1：HTTP 重定向到 HTTPS
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All

    # 监听器 2：HTTPS 主站
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: wildcard-tls
            namespace: cert-manager
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              access: production

    # 监听器 3：内部 gRPC 服务
    - name: grpc-internal
      protocol: HTTPS
      port: 8443
      hostname: "*.internal.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: internal-tls
      allowedRoutes:
        namespaces:
          from: Same

allowedRoutes 是一个强大的访问控制机制，配合标签选择器，集群管理员可以精确控制哪些命名空间的路由可以绑定到哪个监听器。

HTTPRoute：应用路由层

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: user-service-route
  namespace: team-backend
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: https  # 绑定到特定监听器

  hostnames:
    - "api.example.com"
    - "api.internal.example.com"

  rules:
    # 规则 1：精确匹配用户查询
    - matches:
        - path:
            type: Exact
            value: /api/v2/users/me
          method: GET
          headers:
            - name: X-Request-ID
              value: ".*"  # 正则匹配
      backendRefs:
        - name: user-service
          port: 8080
          weight: 100

    # 规则 2：前缀匹配 + 条件过滤
    - matches:
        - path:
            type: PathPrefix
            value: /api/v2/users
          queryParams:
            - name: expand
              value: "profile"
          headers:
            - name: Authorization
              value: "Bearer .*"
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Backend-Version
                value: "v2.3.1"
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            remove:
              - "X-Powered-By"
              - "Server"
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301
      backendRefs:
        - name: user-service
          port: 8080

    # 规则 3：所有其他请求
    - matches:
        - path:
            type: PathPrefix
            value: /api/v2
      backendRefs:
        - name: api-gateway
          port: 8080

ReferenceGrant：跨命名空间安全引用

# 在 gateway-infra 命名空间中授权
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-team-backend-routes
  namespace: gateway-infra
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: team-backend
  to:
    - group: gateway.networking.k8s.io
      kind: Gateway

这是 Gateway API 最被低估的特性之一。没有 ReferenceGrant，任何命名空间都不能引用其他命名空间的 Gateway，彻底杜绝了越权路由。

三、高级路由实战：HTTPRoute 深入解析

3.1 匹配条件详解

HTTPRoute 支持四种匹配维度的组合：

spec:
  rules:
    - matches:
        # 维度 1：路径匹配
        - path:
            type: PathPrefix  # Exact | PathPrefix | RegularExpression
            value: /api/
          # 维度 2：HTTP 方法
          method: POST
          # 维度 3：请求头匹配
          headers:
            - name: Content-Type
              value: "application/json"
            - name: X-Feature-Flag
              value: "new-ui"
          # 维度 4：查询参数匹配
          queryParams:
            - name: debug
              value: "true"

路径匹配类型对比：

3.2 流量加权分割（金丝雀发布）

这是 Gateway API 最实用的特性之一，原生支持基于权重的流量分配：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-demo
  namespace: team-frontend
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  hostnames:
    - "www.example.com"

  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        # 稳定版本：90% 流量
        - name: web-app-v2
          port: 8080
          weight: 90
        # 金丝雀版本：10% 流量
        - name: web-app-v3
          port: 8080
          weight: 10

渐进式灰度发布脚本：

#!/bin/bash
# canary-rollout.sh — 基于 Gateway API 的渐进式灰度发布
# 用法: ./canary-rollout.sh web-app-v3 10 90

CANARY_DEPLOY=$1      # 金丝雀 Deployment 名称
INITIAL_WEIGHT=${2:-5}  # 初始流量权重（默认 5%）
MAX_WEIGHT=${3:-100}    # 最终目标权重（默认 100%）
ROUTE_NAME="canary-demo"
NAMESPACE="team-frontend"

echo "🚀 开始灰度发布: $CANARY_DEPLOY"
echo "   初始权重: ${INITIAL_WEIGHT}%"
echo "   目标权重: ${MAX_WEIGHT}%"

for weight in $(seq $INITIAL_WEIGHT 5 $MAX_WEIGHT); do
  echo ""
  echo "📊 切换流量到 ${weight}%..."

  kubectl patch httproute $ROUTE_NAME -n $NAMESPACE --type=merge -p "
  spec:
    rules:
      - matches:
          - path:
              type: PathPrefix
              value: /
        backendRefs:
          - name: web-app-v2
            port: 8080
            weight: $((100 - weight))
          - name: $CANARY_DEPLOY
            port: 8080
            weight: $weight
  "

  # 等待观察
  read -p "✅ 当前 ${weight}%，观察指标正常后按 Enter 继续，Ctrl+C 回滚..." -t 300

  if [ $? -ne 0 ]; then
    echo "⚠️  用户中断，回滚到 0%..."
    kubectl patch httproute $ROUTE_NAME -n $NAMESPACE --type=merge -p "
    spec:
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /
          backendRefs:
            - name: web-app-v2
              port: 8080
              weight: 100
            - name: $CANARY_DEPLOY
              port: 8080
              weight: 0
    "
    exit 1
  fi
done

echo ""
echo "🎉 灰度发布完成！流量已全部切换到 $CANARY_DEPLOY"

3.3 基于 Header 的流量路由

实现 A/B 测试的最佳方式：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ab-test-route
  namespace: team-frontend
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  hostnames:
    - "www.example.com"

  rules:
    # 新版本路由：带特定 Feature Flag 的请求走新版本
    - matches:
        - headers:
            - name: X-Feature-New-UI
              value: "enabled"
      backendRefs:
        - name: web-app-new-ui
          port: 8080

    # 默认路由：所有其他请求走稳定版本
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web-app-stable
          port: 8080

3.4 请求/响应 Filter

Gateway API 提供标准化的 Filter 机制，替代了 Ingress 的各种注解 hack：

rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api/
    filters:
      # Filter 1：请求头修改
      - type: RequestHeaderModifier
        requestHeaderModifier:
          set:
            - name: X-Request-Start
              value: "t=${unix_timestamp}"  # 记录请求开始时间
          add:
            - name: X-Forwarded-Proto
              value: "https"
          remove:
            - "X-Internal-Debug"

      # Filter 2：响应头修改
      - type: ResponseHeaderModifier
        responseHeaderModifier:
          set:
            - name: Strict-Transport-Security
              value: "max-age=31536000; includeSubDomains"
            - name: X-Content-Type-Options
              value: "nosniff"
          remove:
            - "X-Powered-By"
            - "Server"

      # Filter 3：请求重定向
      # - type: RequestRedirect
      #   requestRedirect:
      #     hostname: "new.example.com"
      #     statusCode: 301

      # Filter 4：URL 重写
      - type: URLRewrite
        urlRewrite:
          hostname: "api-backend.internal"
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: "/v2/"  # /api/users → /v2/users

      # Filter 5：请求镜像（用于流量录制和测试）
      # - type: RequestMirror
      #   requestMirror:
      #     backendRef:
      #       name: traffic-recorder
      #       port: 9090

四、gRPC 路由实战

4.1 为什么 gRPC 路由很重要

微服务架构中，gRPC 已经是服务间通信的主流协议。Ingress 完全不支持 gRPC 路由，而 Gateway API 提供了一流的 gRPCRoute 支持：

# gRPC 服务定义（protobuf）
# service OrderService {
#   rpc CreateOrder(CreateOrderRequest) returns (Order) {}
#   rpc GetOrder(GetOrderRequest) returns (Order) {}
#   rpc ListOrders(ListOrdersRequest) returns (stream Order) {}
#   rpc CancelOrder(CancelOrderRequest) returns (CancelResponse) {}
# }

4.2 GRPCRoute 配置

apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: order-service-route
  namespace: team-orders
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: grpc-internal
  hostnames:
    - "grpc.internal.example.com"

  rules:
    # 路由 1：写操作走 v2 版本
    - matches:
        - method:
            service: "order.v2.OrderService"
            method: "CreateOrder"
      backendRefs:
        - name: order-service-v2
          port: 9090

    # 路由 2：读操作走 v1（兼容旧版）
    - matches:
        - method:
            service: "order.v1.OrderService"
      backendRefs:
        - name: order-service-v1
          port: 9090

    # 路由 3：所有其他 gRPC 方法
    - matches:
        - method:
            service: "*"
      backendRefs:
        - name: order-service-v2
          port: 9090

4.3 gRPC + HTTP 混合路由

现代服务经常同时暴露 gRPC 和 REST 接口，Gateway API 可以优雅处理：

# gRPC 路由
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: grpc-routes
  namespace: team-api
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: grpc-internal
  rules:
    - matches:
        - method:
            service: "api.v1.UserService"
      backendRefs:
        - name: user-service
          port: 9090

---
# HTTP REST 路由（同一服务，不同协议）
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rest-routes
  namespace: team-api
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
      sectionName: https
  hostnames:
    - "api.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/
          headers:
            - name: Content-Type
              value: "application/json"
      backendRefs:
        - name: user-service
          port: 8080  # REST 端口

五、TCP 和 UDP 路由

5.1 TCPRoute：非 HTTP 协议的支持

apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: mysql-tcp-route
  namespace: team-database
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  rules:
    - backendRefs:
        - name: mysql-proxy
          port: 3306

# Gateway 上对应的 TCP 监听器
listeners:
  - name: mysql
    protocol: TCP
    port: 3306
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            access: database

5.2 UDPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: UDPRoute
metadata:
  name: dns-udp-route
  namespace: kube-system
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  rules:
    - backendRefs:
        - name: core-dns
          port: 53

六、生产级最佳实践

6.1 TLS 策略管理

在 v1.3 中，Gateway API 引入了更完善的 TLS 配置：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: prod-wildcard-cert
        options:
          # ALPN 协议协商
          alpnProtocols:
            - h2
            - http/1.1
          # 最低 TLS 版本
          minVersion: "1.3"
          # 密码套件
          cipherSuites:
            - TLS_AES_256_GCM_SHA384
            - TLS_CHACHA20_POLY1305_SHA256

自动化证书管理（cert-manager 集成）：

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: prod-wildcard-cert
  namespace: cert-manager
spec:
  secretName: prod-wildcard-cert
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - "*.example.com"
    - "example.com"
  privateKey:
    algorithm: ECDSA
    size: 256

6.2 多命名空间路由隔离

在企业级部署中，命名空间隔离是安全的基础：

# 命名空间标签定义
# team-frontend 命名空间：labels: {access: public-gateway}
# team-backend 命名空间：labels: {access: public-gateway, access: internal-gateway}
# team-data 命名空间：labels: {access: internal-gateway}

---
# 公开 Gateway：只允许 public 访问
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: public-cert
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              access: public-gateway

---
# 内部 Gateway：允许更多命名空间
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: internal-gateway
  namespace: gateway-infra
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: grpc
      protocol: HTTPS
      port: 8443
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: internal-cert
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              access: internal-gateway

6.3 超时、重试和错误处理

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: resilient-api-route
  namespace: team-backend
spec:
  parentRefs:
    - name: prod-gateway
      namespace: gateway-infra
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api/
      # 超时配置
      timeouts:
        request: 30s       # 整体请求超时
        backendRequest: 15s  # 后端请求超时

      filters:
        # 重试策略
        - type: ExtensionRef  # 具体重试配置依赖实现
          extensionRef:
            group: gateway.envoyproxy.io
            kind: RetryPolicy
            name: api-retry-policy

      backendRefs:
        - name: api-service
          port: 8080

6.4 健康检查与负载均衡

# Envoy Gateway 的健康检查配置（通过 EnvoyProxy CRD）
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: proxy-config
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
  telemetry:
    accessLog:
      settings:
        - format:
            text: '{"time":"%START_TIME%","method":"%REQ(:METHOD)%","path":"%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%","status":"%RESPONSE_CODE%","duration":"%DURATION%","upstream":"%UPSTREAM_HOST%"}'
  extraArgs:
    - name: "--service-cluster"
      value: "production"

七、从 Ingress 迁移的实战指南

7.1 迁移前的检查清单

#!/bin/bash
# ingress-audit.sh — 审计现有 Ingress 配置，评估迁移难度

echo "=== Ingress 资源统计 ==="
kubectl get ingress --all-namespaces --no-headers | wc -l

echo ""
echo "=== 使用的 IngressClass ==="
kubectl get ingress --all-namespaces -o custom-columns=NS:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.ingressClassName | sort

echo ""
echo "=== 注解使用统计（迁移难点分析）==="
kubectl get ingress --all-namespaces -o yaml | \
  grep -oP 'nginx\.ingress\.kubernetes\.io/[a-z-]+' | \
  sort | uniq -c | sort -rn

kubectl get ingress --all-namespaces -o yaml | \
  grep -oP 'traefik\.ingress\.kubernetes\.io/[a-z-]+' | \
  sort | uniq -c | sort -rn

echo ""
echo "=== TLS 配置 ==="
kubectl get ingress --all-namespaces -o custom-columns=NS:.metadata.namespace,NAME:.metadata.name,HOSTS:.spec.rules[*].host

echo ""
echo "=== 非 HTTP 路由检测 ==="
echo "检查是否有 TCP/UDP Service 通过 Ingress 暴露..."
kubectl get svc --all-namespaces -o custom-columns=NS:.metadata.namespace,NAME:.metadata.name,PORT:.spec.ports[*].port,PROTOCOL:.spec.ports[*].protocol | grep -v "TCP"

7.2 自动化迁移脚本

#!/bin/bash
# migrate-ingress.sh — 将 Ingress 转换为 Gateway API 资源
# 用法: ./migrate-ingress.sh <ingress-namespace> <ingress-name>

NS=$1
NAME=$2
GW_NS="gateway-infra"
GW_NAME="prod-gateway"

if [ -z "$NS" ] || [ -z "$NAME" ]; then
  echo "用法: $0 <namespace> <ingress-name>"
  exit 1
fi

echo "📋 分析 Ingress: $NS/$NAME"
INGRESS=$(kubectl get ingress $NAME -n $NS -o yaml)

# 提取 host
HOST=$(echo "$INGRESS" | yq '.spec.rules[0].host // "example.com"')
echo "  Host: $HOST"

# 生成 HTTPRoute
cat <<EOF
---
# 自动生成的 HTTPRoute（请人工审核！）
# 源自 Ingress: $NS/$NAME
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: migrated-${NAME}
  namespace: $NS
spec:
  parentRefs:
    - name: $GW_NAME
      namespace: $GW_NS
  hostnames:
    - "$HOST"
  rules:
EOF

# 转换路径规则
PATHS=$(echo "$INGRESS" | yq '.spec.rules[0].http.paths[]')
echo "$PATHS" | while read -r path; do
  PTYPE=$(echo "$path" | yq '.pathType // "Prefix"')
  PVALUE=$(echo "$path" | yq '.path // "/"')
  SVC=$(echo "$path" | yq '.backend.service.name')
  PORT=$(echo "$path" | yq '.backend.service.port.number // 80')

  cat <<EOF
    - matches:
        - path:
            type: $PTYPE
            value: $PVALUE
      backendRefs:
        - name: $SVC
          port: $PORT
EOF
done

echo ""
echo "⚠️  注意：以下内容需要手动迁移"
echo "  - TLS 配置（迁移到 Gateway Listener）"
echo "  - annotations（需要转换为 Filter 或 CRD 配置）"
echo "  - 重写规则（转换为 URLRewrite Filter）"

7.3 Ingress 与 Gateway API 共存策略

迁移不需要一步到位。Gateway API 可以与 Ingress 共存：

# 阶段 1：新建 Gateway + 新路由用 Gateway API
# 阶段 2：逐步将旧 Ingress 转换为 HTTPRoute
# 阶段 3：确认无问题后删除旧 Ingress Controller

# 共存期间，确保两个入口使用不同的 LB IP 或域名

八、性能优化与监控

8.1 Gateway Controller 选型对比（2026）

8.2 Envoy Gateway 生产配置

# 高性能 Envoy Gateway 配置
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: prod-proxy-config
  namespace: envoy-gateway-system
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: LoadBalancer
        annotations:
          # AWS NLB 注解
          service.beta.kubernetes.io/aws-load-balancer-type: nlb
          service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
  logging:
    level:
      default: warn
      http: info
      router: debug
  # 连接池优化
  bootstrap:
    static_resources:
      clusters:
        - name: admin
          typed_extension_protocol_options:
            envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
              common_http_protocol_options:
                idle_timeout: 300s
              http2_protocol_options:
                max_concurrent_streams: 1000
                initial_stream_window_size: 65536

8.3 监控指标采集

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

关键监控指标：

8.4 Grafana Dashboard 查询示例

# 请求 QPS（按 Host 分组）
sum(rate(envoy_http_downstream_rq_total[5m])) by (envoy_http_conn_manager_prefix)

# P99 延迟
histogram_quantile(0.99,
  sum(rate(envoy_cluster_upstream_rq_time_bucket[5m])) by (le, envoy_cluster_name)
)

# 错误率
sum(rate(envoy_http_downstream_rq_5xx[5m])) / sum(rate(envoy_http_downstream_rq_total[5m])) * 100

# 活跃连接数
envoy_listener_downstream_active_connections

九、Gateway API 2026 年新特性速览

9.1 v1.3 核心变更

• GRPCRoute 正式 GA：完整的 gRPC 路由支持，包括方法级匹配
• BackendTLSPolicy：为后端服务配置 mTLS
• Session Persistence：原生会话保持支持

# BackendTLSPolicy 示例
apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: mtls-policy
  namespace: team-backend
spec:
  targetRefs:
    - group: ""
      kind: Service
      name: api-service
  validation:
    caCertificateRefs:
      - kind: ConfigMap
        name: backend-ca
    hostname: "api-service.team-backend.svc.cluster.local"

9.2 实验性特性（值得关注）

• MultiClusterService：跨集群流量路由
• Extended Features（xRoutes）：基于 CEL 表达式的高级路由
• GAMMA Initiative：Gateway API for Mesh Management and Administration

十、踩坑实录与解决方案

坑 1：HTTPRoute 绑定失败

症状：HTTPRoute 创建后不生效，Gateway 的 Conditions 显示 Accepted: False

原因：缺少 ReferenceGrant 或命名空间标签不匹配

# 诊断
kubectl describe gateway prod-gateway -n gateway-infra
kubectl describe httproute your-route -n your-namespace

解决：检查 allowedRoutes 配置，确保目标命名空间有 ReferenceGrant

坑 2：路径匹配优先级混乱

规则：Gateway API 的路由匹配遵循以下优先级：

1. 更精确的匹配优先（Exact > PathPrefix > RegularExpression）
2. 同级别按 rules 数组顺序
3. Hostname 匹配优先于通配符

# ⚠️ 错误示例：PathPrefix 在 Exact 之前
rules:
  - matches:
      - path:
          type: PathPrefix
          value: /api/v2/users  # 会匹配 /api/v2/users/123
  - matches:
      - path:
          type: Exact
          value: /api/v2/users  # 永远不会命中！

# ✅ 正确：Exact 在前
rules:
  - matches:
      - path:
          type: Exact
          value: /api/v2/users
  - matches:
      - path:
          type: PathPrefix
          value: /api/v2/users

坑 3：Listener 冲突

症状：Gateway 创建后 Listener 状态为 Conflicted

原因：两个 Listener 监听了相同的端口和协议组合

# ❌ 冲突：两个 HTTPS 监听器在同一个端口
listeners:
  - name: https-1
    protocol: HTTPS
    port: 443
  - name: https-2
    protocol: HTTPS
    port: 443  # 冲突！

# ✅ 正确：使用 hostname 区分，或合并为一个 Listener
listeners:
  - name: https
    protocol: HTTPS
    port: 443
    # 所有 HTTPRoute 通过 hostname 匹配，无需多个 Listener

坑 4：Filter 依赖实现

注意：部分 Filter（如 RequestMirror、某些重试策略）的实现依赖具体的 Gateway Controller。在多实现环境中，需要验证兼容性。

十一、总结与展望

Gateway API 在 2026 年已经是一个成熟的、生产就绪的流量治理标准。它的核心优势在于：

1. 角色分离：基础设施、集群管理、应用开发三层解耦，RBAC 精细化控制
2. 协议全覆盖：HTTP/HTTPS、gRPC、TCP、UDP 一个 API 搞定
3. 原生流量管理：加权路由、Header 匹配、金丝雀发布零注解
4. 可观测性：Conditions 状态反馈，比 Ingress 黑盒式配置强太多
5. 标准化：不同 Controller 之间配置可迁移，不再被某个实现绑架

迁移建议：如果你的集群还在用 Ingress，建议按照以下节奏迁移：

Gateway API 的未来方向（GAMMA Initiative）将 Mesh 和 Gateway 统一，未来可能不再需要 Service Mesh 作为独立组件。这对于简化微服务基础设施意义重大。

别再往 Ingress 的 annotations 里塞配置了，2026 年，是时候拥抱 Gateway API 了。