Gateway API

注意
Gateway API 作为替代 Ingress 的下一代资源,既可以处理南北向流量,还可以处理东西向流量。关于 Gateway API 的详细介绍和发展趋势,请参考 Gateway API:Kubernetes 和服务网格入口中网关的未来

概述

Gateway API 是由 Kubernetes SIG-NETWORK 管理的开源项目,旨在为 Kubernetes 生态系统提供现代化的服务网络 API。该项目在 2023 年 10 月宣布 GA,并在 2024 年 5 月发布 v1.1,将多项功能升级为正式可用,特别是对服务网格和 GRPCRoute 的支持。

Gateway API 提供了一套完整的资源对象来暴露 Kubernetes 应用:

  • GatewayClass - 网关类定义
  • Gateway - 网关实例
  • HTTPRoute - HTTP 路由规则
  • TLSRoute - TLS 路由规则
  • TCPRoute / UDPRoute - 四层路由规则
  • GRPCRoute - gRPC 路由规则

目前已有大量网关和服务网格项目支持 Gateway API,详细的支持状况可在官方文档中查看。

设计理念

Gateway API 通过提供表现性强、可扩展且面向角色的接口来改善服务网络管理。其核心设计理念包括:

分层架构

Gateway API 采用分层架构,将网络配置分解为不同的关注点,实现配置解耦和角色分离:

Gateway API 的分层架构
Gateway API 的分层架构

面向角色的设计

Gateway API 为不同的使用场景定义了四类角色:

  • 基础设施提供方:云服务提供商或基础设施厂商,负责提供 GatewayClass 实现
  • 集群运维人员:管理集群资源,创建和维护 Gateway 实例
  • 应用程序开发者:开发和部署应用程序,定义应用的路由需求
  • 应用管理员:管理复杂应用系统,负责应用级别的策略配置
Gateway API 管理时的角色划分
Gateway API 管理时的角色划分

相比 Ingress 的优势

核心改进

Gateway API 相比 Ingress 有以下关键改进:

表现力更强

  • 支持基于 Header 的匹配
  • 内置流量权重分配
  • 原生支持多种协议(HTTP/HTTPS/TLS/TCP/UDP/gRPC)

扩展性更好

  • 允许在 API 各层次链接自定义资源
  • 支持更精细的定制化配置
  • 提供标准化的策略附件机制

角色分离

  • 不同 API 资源映射到不同的管理角色
  • 实现关注点分离和权责明确

通用性强

  • 设计为可移植的通用规范
  • 支持多厂商实现和互操作性

共享基础设施

  • 支持独立路由资源绑定到同一网关
  • 实现负载均衡器和 VIP 的安全共享

类型化后端引用

  • 支持引用 Kubernetes Service 和其他自定义资源
  • 提供更灵活的后端配置能力

跨命名空间支持

  • 支持跨命名空间的路由绑定
  • 在保持工作负载隔离的同时共享网络基础设施

资源模型详解

GatewayClass

GatewayClass 是集群级别的资源,定义了一组具有共同配置和行为的网关。它类似于 IngressClassStorageClass,由基础设施提供方创建。

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cloud-gateway
spec:
  controllerName: "example.com/gateway-controller"
  description: "云服务提供商的网关实现"

参数化配置

GatewayClass 支持通过 parametersRef 字段进行参数化配置:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: premium-gateway
spec:
  controllerName: "example.com/gateway-controller"
  parametersRef:
    group: example.com/v1alpha1
    kind: GatewayConfig
    name: premium-config
---
apiVersion: example.com/v1alpha1
kind: GatewayConfig
metadata:
  name: premium-config
spec:
  loadBalancerType: "premium"
  ipAddressPool: "premium-pool"
  enableDDoSProtection: true

Gateway

Gateway 描述如何将外部流量路由到集群内的服务。它定义了网络入口点的具体配置:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: production-gateway
  namespace: gateway-system
spec:
  gatewayClassName: cloud-gateway
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            environment: production
  - name: https
    port: 443
    protocol: HTTPS
    hostname: "*.example.com"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: wildcard-tls-cert
  addresses:
  - type: NamedAddress
    value: "production-lb"

监听器配置

每个监听器可以配置:

  • 端口和协议:定义监听的端口和协议类型
  • 主机名:指定处理的域名(支持通配符)
  • TLS 设置:配置 SSL/TLS 证书和终止策略
  • 路由限制:控制哪些路由可以附加到此监听器

Route 资源

HTTPRoute

HTTPRoute 是最常用的路由类型,用于处理 HTTP 和 HTTPS 流量:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: production
spec:
  parentRefs:
  - name: production-gateway
    namespace: gateway-system
  hostnames:
  - api.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/
    - headers:
      - name: X-API-Version
        value: v1
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        add:
        - name: X-Forwarded-Host
          value: api.example.com
    backendRefs:
    - name: api-v1-service
      port: 8080
      weight: 90
    - name: api-v1-canary-service
      port: 8080
      weight: 10
  - matches:
    - path:
        type: PathPrefix
        value: /v2/
    backendRefs:
    - name: api-v2-service
      port: 8080
流量经过网关和 HTTPRoute 发送到服务中的过程
流量经过网关和 HTTPRoute 发送到服务中的过程

其他路由类型

GRPCRoute

用于 gRPC 流量路由,支持基于 gRPC 方法的匹配:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GRPCRoute
metadata:
  name: grpc-route
spec:
  parentRefs:
  - name: production-gateway
  hostnames:
  - grpc.example.com
  rules:
  - matches:
    - method:
        service: com.example.User
        method: GetUser
    backendRefs:
    - name: user-service
      port: 9090

TLSRoute

用于基于 SNI 的 TLS 路由:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TLSRoute
metadata:
  name: tls-route
spec:
  parentRefs:
  - name: production-gateway
  hostnames:
  - secure.example.com
  rules:
  - backendRefs:
    - name: secure-service
      port: 8443

TCPRoute 和 UDPRoute

用于四层流量路由:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: database-route
spec:
  parentRefs:
  - name: production-gateway
    sectionName: database
  rules:
  - backendRefs:
    - name: postgres-service
      port: 5432

路由类型对比

路由类型OSI 层路由鉴别器TLS 支持主要用途
HTTPRoute第 7 层HTTP 协议中的任何内容仅终止HTTP/HTTPS 应用路由
GRPCRoute第 7 层gRPC 方法和服务仅终止gRPC 应用路由
TLSRoute第 4-7 层SNI 和其他 TLS 属性直通或终止基于 SNI 的 TLS 路由
TCPRoute第 4 层目的端口直通或终止TCP 流量转发
UDPRoute第 4 层目的端口不支持UDP 流量转发

ReferenceGrant

ReferenceGrant 用于启用跨命名空间引用,提供细粒度的访问控制:

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

路由绑定机制

绑定过程

路由附加到网关需要满足以下条件:

  1. 路由引用:Route 在 parentRefs 字段中引用 Gateway
  2. 监听器允许:Gateway 至少有一个监听器允许该路由附加
  3. 命名空间策略:符合 Gateway 的命名空间访问策略
  4. 主机名匹配:路由的主机名与监听器的主机名匹配
路由绑定示意图
路由绑定示意图

限制机制

主机名限制

listeners:
- name: api
  hostname: api.example.com  # 只接受匹配的主机名
  protocol: HTTPS
  port: 443

命名空间限制

listeners:
- name: production
  allowedRoutes:
    namespaces:
      from: Selector
      selector:
        matchLabels:
          environment: production

路由类型限制

listeners:
- name: grpc-only
  allowedRoutes:
    kinds:
    - group: gateway.networking.k8s.io
      kind: GRPCRoute

策略附件系统

策略附件概念

策略附件(Policy Attachment)允许将自定义策略(如超时、重试、限流等)附加到 Gateway API 资源上:

apiVersion: networking.example.com/v1alpha1
kind: RateLimitPolicy
metadata:
  name: api-rate-limit
spec:
  default:
    requestsPerSecond: 100
  override:
    requestsPerSecond: 1000
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route

策略继承层次

策略支持 defaultoverride 两种模式,其优先级如下:

策略优先级
策略优先级

优先级规则

  • Override 值:上层覆盖下层
  • Default 值:下层覆盖上层

常见策略类型

超时策略

apiVersion: networking.example.com/v1alpha1
kind: TimeoutPolicy
metadata:
  name: api-timeout
spec:
  default:
    request: 30s
    backend: 10s
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route

重试策略

apiVersion: networking.example.com/v1alpha1
kind: RetryPolicy
metadata:
  name: api-retry
spec:
  default:
    maxRetries: 3
    backoffPolicy: exponential
    retryOn: ["5xx", "gateway-error"]
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: api-route

TLS 配置

概念说明

在 Gateway API 中,TLS 配置涉及两个方向:

  • 下游:客户端到网关的连接
  • 上游:网关到后端服务的连接

在 Gateway API 的 TLS 配置中:

  • 下游 TLS:指从客户端到网关的连接,网关作为 TLS 服务器,负责处理客户端的 TLS 握手和证书验证
  • 上游 TLS:指从网关到后端服务的连接,网关作为 TLS 客户端,与后端服务建立加密连接

这种双向的 TLS 配置使得可以实现端到端的加密通信,确保数据在传输过程中的安全性。

下游 TLS 配置

基本 HTTPS 配置

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: https-gateway
spec:
  gatewayClassName: standard
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    hostname: api.example.com
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: api-tls-cert

通配符证书配置

listeners:
- name: wildcard-https
  port: 443
  protocol: HTTPS
  hostname: "*.example.com"
  tls:
    mode: Terminate
    certificateRefs:
    - kind: Secret
      name: wildcard-cert
- name: specific-https
  port: 443
  protocol: HTTPS
  hostname: api.example.com
  tls:
    mode: Terminate
    certificateRefs:
    - kind: Secret
      name: api-specific-cert

跨命名空间证书引用

# Gateway 配置
listeners:
- name: https
  port: 443
  protocol: HTTPS
  tls:
    certificateRefs:
    - kind: Secret
      name: shared-cert
      namespace: cert-manager
---
# ReferenceGrant 配置
apiVersion: gateway.networking.k8s.io/v1beta1
kind: ReferenceGrant
metadata:
  name: allow-cert-access
  namespace: cert-manager
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: Gateway
    namespace: gateway-system
  to:
  - group: ""
    kind: Secret
    name: shared-cert

TLS 模式对比

监听器协议TLS 模式支持的路由类型使用场景
HTTPSTerminateHTTPRoute标准 Web 应用
TLSTerminateTCPRoute需要 TLS 终止的 TCP 应用
TLSPassthroughTLSRoute端到端 TLS 加密

流量管理

请求流程

典型的请求处理流程:

  1. DNS 解析:客户端解析域名到 Gateway 地址
  2. 监听器匹配:Gateway 根据 Host header 匹配监听器
  3. 路由匹配:根据路径、Header 等条件匹配 Route 规则
  4. 过滤器处理:应用请求/响应过滤器
  5. 后端转发:将请求转发到匹配的后端服务
Gateway API 流程图
Gateway API 流程图

高级流量管理

流量分割

rules:
- matches:
  - path:
      type: PathPrefix
      value: /api/
  backendRefs:
  - name: api-v1
    port: 8080
    weight: 80
  - name: api-v2
    port: 8080
    weight: 20

请求过滤

rules:
- matches:
  - path:
      type: PathPrefix
      value: /api/
  filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      add:
      - name: X-Service-Version
        value: v2
      remove:
      - X-Internal-Header
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /v2/api/
  backendRefs:
  - name: api-service
    port: 8080

请求重定向

rules:
- matches:
  - path:
      type: PathPrefix
      value: /old-api/
  filters:
  - type: RequestRedirect
    requestRedirect:
      scheme: https
      hostname: new-api.example.com
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /api/
      statusCode: 301

扩展机制

自定义后端

Gateway API 支持引用非标准的后端资源:

backendRefs:
- group: networking.example.com
  kind: S3Bucket
  name: static-assets
- group: networking.example.com  
  kind: LambdaFunction
  name: api-handler

自定义过滤器

实现可以提供自定义的 HTTP 过滤器:

filters:
- type: ExtensionRef
  extensionRef:
    group: networking.example.com
    kind: AuthFilter
    name: oauth2-filter

自定义路由类型

对于 Gateway API 不支持的协议,可以创建自定义路由类型:

apiVersion: networking.example.com/v1alpha1
kind: WebSocketRoute
metadata:
  name: chat-route
spec:
  parentRefs:
  - name: production-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /chat/
    backendRefs:
    - name: chat-service
      port: 8080

最佳实践

生产环境部署

网关分层部署

# 边缘网关 - 处理外部流量
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: edge-gateway
  namespace: gateway-system
spec:
  gatewayClassName: edge-class
  listeners:
  - name: https
    port: 443
    protocol: HTTPS
    allowedRoutes:
      namespaces:
        from: All
---
# 内部网关 - 处理内部服务通信  
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: internal-gateway
  namespace: gateway-system
spec:
  gatewayClassName: internal-class
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Selector
        selector:
          matchLabels:
            network-policy: internal

安全配置

# 限制路由访问
listeners:
- name: production
  allowedRoutes:
    namespaces:
      from: Selector
      selector:
        matchLabels:
          environment: production
          security-level: high
    kinds:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute

可观测性配置

# 通过注解启用监控
metadata:
  annotations:
    gateway.networking.k8s.io/enable-metrics: "true"
    gateway.networking.k8s.io/enable-tracing: "true"
    gateway.networking.k8s.io/log-level: "info"

迁移策略

从 Ingress 迁移

  1. 并行部署:同时运行 Ingress 和 Gateway API
  2. 逐步迁移:按服务逐步迁移到 Gateway API
  3. 验证测试:确保功能一致性
  4. 切换流量:完成迁移后切换流量
  5. 清理资源:移除旧的 Ingress 资源

配置转换示例

# 原 Ingress 配置
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 8080
---
# 对应的 Gateway API 配置
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: /
    backendRefs:
    - name: api-service
      port: 8080

总结

Gateway API 作为 Kubernetes 网络的下一代标准,提供了比 Ingress 更强大、更灵活的流量管理能力。通过其面向角色的设计、丰富的路由类型和强大的扩展机制,Gateway API 能够满足从简单 Web 应用到复杂微服务架构的各种网络需求。

随着越来越多的实现支持和社区采用,Gateway API 正在成为 Kubernetes 集群网络入口的标准选择。对于新项目,建议直接采用 Gateway API;对于现有项目,可以考虑逐步从 Ingress 迁移到 Gateway API,以获得更好的功能和扩展性。

参考资料

文章导航

章节内容

这是章节的内容页面。

章节概览

评论区