Kubernetes Gateway API 深度指南：下一代入口流量管理如何超越传统 Ingress

在 Kubernetes 集群的流量入口管理领域，Ingress 资源在过去五年中一直是事实标准。然而，随着云原生应用架构日益复杂——微服务数量激增、多团队共享集群、南北向与东西向流量交织——Ingress 的设计局限逐渐暴露。Kubernetes Gateway API（网关 API）正是在这一背景下诞生的新一代流量管理规范，它由 SIG-NETWORK 主导开发，目前已进入 GA（General Availability）阶段，并得到 Istio、Contour、Traefik、NGINX Gateway Fabric、Cilium 等主流项目的广泛支持。

本文将从实战角度深入解析 Gateway API 的核心概念、架构设计、与 Ingress 的对比，以及如何在生产环境中落地使用。

Kubernetes Network Architecture

一、Ingress 的局限性：为什么需要 Gateway API

要理解 Gateway API 的价值，首先需要认清传统 Ingress 的设计瓶颈。Ingress 诞生于 2016 年，当时 Kubernetes 生态的需求相对简单——将外部 HTTP/HTTPS 流量路由到集群内部的服务。但经过近十年的发展，以下几个痛点日益突出：

1.1 缺乏角色职责分离

在真实的运维场景中，集群通常由不同角色共同管理：基础设施团队负责网络设备和负载均衡器的部署，平台团队管理集群的网络策略和流量策略，应用团队只关心自己的服务如何暴露。然而 Ingress 将所有配置集中在一个资源对象中，任何应用开发者都能修改全局的流量规则。这种”扁平化”设计导致以下问题：

权限粒度不够——无法限制某个团队只能配置特定域名或路径
配置冲突——多个团队同时修改同一个 Ingress 资源可能导致规则覆盖
安全风险——应用开发者可能无意中暴露内部服务到公网

1.2 协议支持单一

Ingress 天然只支持 HTTP/HTTPS 协议。虽然部分 Ingress 控制器（如 NGINX Ingress）通过 annotation 扩展支持了 TCP/UDP，但这种扩展方式既不标准化也不可移植。对于需要暴露 gRPC、WebSocket、TCP 或 UDP 协议的服务，开发者不得不依赖控制器的私有扩展机制。

1.3 后端协议协商缺失

Ingress 规范中没有定义后端协议协商的能力。比如，前端需要 HTTPS 暴露，但后端服务运行的是 HTTP，Ingress 无法明确表达这种终止 TLS 后再用 HTTP 转发到后端的意图。部分控制器通过 annotation 实现了类似功能，但不同厂商的 annotation 五花八门，造成严重的供应商锁定。

1.4 缺乏跨命名空间支持

Ingress 只能引用同命名空间的 Service。在多租户场景下，如果需要将来自不同命名空间的服务聚合到同一域名下，运维人员必须通过额外的配置手段（如 ExternalName Service）绕道实现，增加了运维复杂度。

# Ingress 只能引用同命名空间的 Service
# 如果 app 和 api 在不同 namespace，Ingress 无法直接转发
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: frontend
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /app
        pathType: Prefix
        backend:
          service:
            name: app-service      # 必须在同一个 namespace
            port:
              number: 80

二、Gateway API 的核心架构：三层模型

Gateway API 引入了三层角色模型将基础设施操作、平台策略和应用配置清晰分离：

Gateway API 架构分层

2.1 第一层：GatewayClass（基础设施提供商）

GatewayClass 是集群维度的资源，类似于 StorageClass 在存储领域的角色。它由基础设施提供商（云厂商、平台团队）定义，描述了一种负载均衡器的类别：

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: istio-internal
spec:
  controllerName: istio.io/gateway-controller
  parametersRef:
    group: istio.io
    kind: IstioGatewayConfig
    name: internal-config
  description: "Istio internal gateway for microservice mesh"

每个 GatewayClass 对应一个控制器名称（controllerName），确定由哪个实现来管理这个类别的网关实例。集群管理员可以通过 parameterRef 传入额外的实现特定配置。

2.2 第二层：Gateway（平台团队）

Gateway 资源代表一个具体的负载均衡器实例。它由平台管理员创建，描述了监听器的地址、端口和协议。一个 Gateway 实例可以绑定到实际的云负载均衡器（如 AWS ALB、GCP HTTP LB）或集群内的代理 Pod：

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: infra
spec:
  gatewayClassName: istio-internal
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: example-com-tls
        namespace: cert-manager
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            tier: frontend
  - name: http-redirect
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: All

注意这里的 allowedRoutes 字段——平台管理员可以精确控制哪些命名空间的应用可以绑定到这个 Gateway。这是 Ingress 无法实现的重要能力。

2.3 第三层：HTTPRoute（应用开发者）

HTTPRoute 是应用开发者创建的资源，定义了具体的流量路由规则。开发者不需要关心底层负载均衡器的细节，只需要将他们的 HTTPRoute 绑定到目标 Gateway 即可：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: user-service-routes
  namespace: user-team
spec:
  parentRefs:
  - name: public-gateway
    namespace: infra
  hostnames:
  - "api.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /users
    backendRefs:
    - name: user-svc
      port: 8080
      weight: 90
    - name: user-svc-canary
      port: 8080
      weight: 10
  - matches:
    - headers:
      - type: Exact
        name: X-User-Type
        value: admin
      path:
        type: PathPrefix
        value: /admin
    backendRefs:
    - name: admin-svc
      port: 8080

上面这个路由规则展示了 Gateway API 的几个关键特性：跨命名空间引用（user-team 的 HTTPRoute 绑定到 infra 命名空间的 Gateway）、流量权重分配（90:10 的金丝雀发布）、基于 header 的匹配（管理员请求路由到独立服务）。

三、Gateway API 的核心能力详解

3.1 跨命名空间路由

这是 Gateway API 相比 Ingress 最显著的优势之一。HTTPRoute 可以引用任意命名空间的 Service，只要目标命名空间被 Gateway 的 allowedRoutes 规则允许。这为多租户集群提供了极大的灵活性：

# team-a 的 HTTPRoute 引用 team-b 的 Service（需要双方配合）
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cross-ns-route
  namespace: team-a
spec:
  parentRefs:
  - name: shared-gateway
    namespace: gateway-ns
  rules:
  - backendRefs:
    - name: team-b-service
      namespace: team-b   # 跨命名空间引用
      port: 80

要实现跨命名空间引用，目标命名空间（team-b）需要创建一个 ReferenceGrant 资源来显式授信：

apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-team-a
  namespace: team-b
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: team-a
  to:
  - group: ""
    kind: Service

这种显式授权机制是安全设计的最佳实践——避免了 Ingress 中那种”谁都能引用任何 Service”的隐式信任模型。

3.2 流量分割与金丝雀发布

Gateway API 原生支持基于权重的流量分发，无需借助额外的 Service Mesh 或 annotation：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-rollout
  namespace: app
spec:
  parentRefs:
  - name: prod-gateway
  hostnames:
  - "app.example.com"
  rules:
  - backendRefs:
    - name: app-stable
      port: 80
      weight: 95
    - name: app-canary
      port: 80
      weight: 5

结合 HTTPRouteFilter，还可以实现更精细的流量控制：

过滤类型	功能说明	使用场景
URLRewrite	重写请求路径或 Host	路径映射、后端路由适配
RequestHeaderModifier	添加/修改/删除请求头	认证信息注入、CORS 配置
ResponseHeaderModifier	修改响应头	安全头注入（HSTS 等）
RequestMirror	流量镜像到另一个后端	流量录制、灰度验证
RequestRedirect	返回重定向响应	HTTP→HTTPS 跳转

3.3 多协议支持

除了 HTTPRoute，Gateway API 定义了多种路由类型以支持不同协议：

HTTPRoute——HTTP/HTTPS/gRPC 路由（最常用）
TLSRoute——非 HTTP 的 TLS 流量，如 RPC over TLS
TCPRoute——四层 TCP 流量，支持端口和非 HTTP 协议
UDPRoute——UDP 流量路由
GRPCRoute——专门针对 gRPC 协议优化的路由（v1.2+）

例如，暴露一个 TCP 服务的配置如下：

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: redis-external
  namespace: database
spec:
  parentRefs:
  - name: internal-tcp-gateway
  rules:
  - backendRefs:
    - name: redis-master
      port: 6379

3.4 后端 TLS 配置

Gateway API 支持前端与后端独立的 TLS 配置。前端可以终止 TLS 或透传 TLS；后端可以要求 mTLS、自定义 CA 证书等：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mtls-backend
spec:
  parentRefs:
  - name: app-gateway
  rules:
  - backendRefs:
    - name: secure-backend
      port: 8443
    backendTLS:
      hostname: internal.backend.svc.cluster.local
      caCertRefs:
      - kind: ConfigMap
        name: backend-ca

四、Gateway API vs Ingress：对比总结

特性	Ingress v1	Gateway API
角色分离	无	GatewayClass/Gateway/Route 三层
跨命名空间路由	不支持	原生支持 + ReferenceGrant 授权
协议支持	仅 HTTP/HTTPS	HTTP、TLS、TCP、UDP、gRPC
流量分割	需控制器 annotation	原生 weight 字段
Header 匹配/修改	需 annotation	原生 filter 机制
金丝雀发布	需额外 CRD	原生支持
后端 TLS 配置	不支持	原生 backendTLS 字段
可扩展性	annotation 方式（非标准化）	Policy Attachment 机制
Kuberentes 版本	v1.19+ GA	v1.27+ beta，v1.30+ 逐渐成熟

五、生产环境落地指南

5.1 选择合适的实现

目前主流的 Gateway API 实现包括：

Istio——通过 istio.io/gateway-controller 支持，最适合已有 Istio Service Mesh 的环境
Contour——Envoy 标准实现，功能完整且成熟
Traefik——v3 版本原生支持 Gateway API，配置简洁
NGINX Gateway Fabric——NGINX 官方实现，兼容 NGINX 配置生态
Cilium——通过 CiliumEnvoyConfig 提供 Gateway API 支持，适合已使用 Cilium CNI 的集群
Kong——Kong Gateway Operator 实现了 Gateway API

选择建议：如果你的集群已经运行 Istio，优先使用 Istio 的实现；如果追求轻量且兼容性，Contour 和 NGINX Gateway Fabric 都是稳妥的选择。

5.2 安装 Gateway API CRD

大多数实现会自动安装 Gateway API 的 CRD，也可以手动安装标准 CRD：

# 安装标准 Gateway API CRD（v1.2.0）
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml

# 安装包含实验性功能的 CRD（如 TLSRoute、TCPRoute 等）
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/experimental-install.yaml

5.3 基于 Istio 的完整示例

下面是一个完整的生产级示例，展示如何使用 Istio 作为 Gateway API 的实现：

# 1. 确保 Istio 已安装并启用 Gateway API 支持
istioctl install --set profile=default -y
kubectl label namespace default istio-injection=enabled

# 2. 创建 GatewayClass（Istio 会自动创建默认的）
kubectl get gatewayclass
# 输出示例：
# NAME           CONTROLLER                    ACCEPTED   AGE
# istio          istio.io/gateway-controller   True       10m

# 3. 创建 Gateway
cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: prod-web-gateway
  namespace: istio-system
spec:
  gatewayClassName: istio
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            kubernetes.io/metadata.name: default
EOF

# 4. 部署示例应用
kubectl create deployment httpbin --image=public.ecr.aws/k8s/httpbin:latest
kubectl expose deployment httpbin --port=80

# 5. 创建 HTTPRoute 绑定
cat <<EOF | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
  namespace: default
spec:
  parentRefs:
  - name: prod-web-gateway
    namespace: istio-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /post
    backendRefs:
    - name: httpbin
      port: 80
EOF

# 6. 验证访问
kubectl port-forward svc/prod-web-gateway-istio -n istio-system 8080:80 &
curl http://localhost:8080/get

5.4 从 Ingress 迁移到 Gateway API

迁移过程建议分阶段进行：

评估阶段——盘点现有 Ingress 规则，确定使用到的 annotation 和功能
并行运行阶段——部署 Gateway API 实现，创建对应的 Gateway 和 HTTPRoute，保留 Ingress 作为回退
DNS 切换——将域名解析指向新的 Gateway 负载均衡器
清理阶段——确认流量正常后，删除旧的 Ingress 资源

大多数实现提供了 Ingress 兼容模式，可以自动将 Ingress 资源转换为 Gateway API 规则使用。例如 Istio 的 PILOT_ENABLE_GATEWAY_API_DEPLOYMENT=true 环境变量可以使 Istio 自动处理 Ingress 资源。

六、进阶话题：Policy Attachment 与可扩展性

Gateway API 的一个独特设计是 Policy Attachment（策略挂载）机制——允许将外部策略资源挂载到 Gateway 或 Route 上。策略通过标签选择器或直接引用进行关联，无需修改核心 API 资源：

# 通过标签选择器将速率限制策略应用到所有匹配的 HTTPRoute
apiVersion: trafficcontrol.example.com/v1
kind: RateLimitPolicy
metadata:
  name: global-rate-limit
  labels:
    environment: production
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
  rateLimit:
    requests: 1000
    per: minute

这种机制使得策略与路由解耦，平台团队可以统一管理安全策略、速率限制、认证等横切关注点，而应用团队只需关注业务路由。这也是 Gateway API 在大型组织中最具吸引力的特性之一。

七、总结与展望

Kubernetes Gateway API 不仅仅是 Ingress 的替代品，更是云原生流量管理的一次范式升级。它通过三层角色分离解决了多团队协作中的权限和配置冲突问题；通过原生支持多种协议和流量策略，消除了对控制器特定 annotation 的依赖；通过 Policy Attachment 机制提供了强大的可扩展性。

截至 Kubernetes 1.31，Gateway API 的 GA 标准（v1.0+）已经稳定，主流实现全部可用。对于新建集群，建议直接采用 Gateway API；对于现有集群，也可以逐步从 Ingress 迁移。虽然 Ingress 短期内不会消失，但 Gateway API 显然代表了 Kubernetes 流量管理的未来方向。

建议读者关注 Gateway API 官方文档和各自控制器实现的 Release Notes，持续跟踪这一领域的最新进展。