Kubernetes Gateway API替代Ingress控制器实现高级流量路由配置

Ingress控制器的局限性催生Gateway API

Kubernetes Ingress自K8s 1.1引入以来一直是集群外部流量入口的标准方案，但其API设计存在固有局限。Ingress资源仅支持基于Host和Path的七层路由，TLS配置通过注解（Annotation）传递且各控制器实现不统一，跨命名空间路由需要借助IngressClass间接管理。在多团队协作、多租户隔离、灰度发布等复杂场景中，Ingress的表达能力明显不足。

Gateway API作为Kubernetes SIG-Network的下一代标准，采用角色分离设计，将基础设施配置（Gateway）与应用路由规则（HTTPRoute）解耦，原生支持跨命名空间、流量拆分、Header操作等高级特性。

Gateway API核心资源模型与角色分离

Gateway API定义了三类核心资源，对应不同运维角色的职责边界：

GatewayClass与Gateway

GatewayClass定义了Gateway的实现类型（如Envoy Proxy、Nginx、HAProxy），由基础设施管理员创建。Gateway实例化一个具体的网关，绑定监听端口和TLS证书，由平台运维团队管理。

# GatewayClass定义
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

---
# Gateway实例
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: main-gateway
  namespace: gateway-system
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All  # 允许所有命名空间的路由规则绑定
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: wildcard-cert
            namespace: cert-system
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              shared-gateway-access: "true"

HTTPRoute实现应用层路由

HTTPRoute由应用开发团队在各业务命名空间中创建，定义具体的路由匹配规则和后端服务引用。通过parentRefs将路由规则附加到Gateway的指定监听器上。

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: production
  labels:
    shared-gateway-access: "true"
spec:
  parentRefs:
    - name: main-gateway
      namespace: gateway-system
      sectionName: https
  hostnames:
    - "api.yunthe.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      backendRefs:
        - name: api-service-v1
          port: 8080
          weight: 90
        - name: api-service-v2
          port: 8080
          weight: 10  # 10%流量到v2，实现灰度发布
    - matches:
        - path:
            type: PathPrefix
            value: /v2
      backendRefs:
        - name: api-service-v2
          port: 8080
          weight: 100

流量拆分与灰度发布配置实践

HTTPRoute的backendRefs支持权重字段，原生实现流量按比例分配到不同后端服务。这与Ingress控制器通过Nginx配置文件或Istio VirtualService实现流量拆分的方式相比，具有声明式、可审计、跨控制器兼容的优势。

基于Header的金丝雀发布

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: canary-route
  namespace: production
spec:
  parentRefs:
    - name: main-gateway
      namespace: gateway-system
  hostnames:
    - "app.yunthe.com"
  rules:
    # 内部测试用户通过Header路由到新版本
    - matches:
        - headers:
            - name: X-Canary-User
              value: "true"
      backendRefs:
        - name: app-service-v2
          port: 80
    # 其余流量到旧版本
    - backendRefs:
        - name: app-service-v1
          port: 80

TLS终端与Passthrough模式选择

Gateway API支持两种TLS处理模式：Terminate模式下Gateway解密TLS流量并转发明文到后端服务，适用于需要Layer 7路由的HTTP场景；Passthrough模式下Gateway保持TLS加密隧道透传到后端，适用于gRPC、数据库代理等需要端到端加密的场景。

# TLS Passthrough模式（TLSRoute）
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: passthrough-gateway
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: grpc
      protocol: TLS
      port: 8443
      tls:
        mode: Passthrough  # 透传TLS，不做解密
      allowedRoutes:
        namespaces:
          from: All

---
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
  name: grpc-route
  namespace: grpc-services
spec:
  parentRefs:
    - name: passthrough-gateway
      namespace: gateway-system
      sectionName: grpc
  hostnames:
    - "grpc.yunthe.com"
  backendRefs:
    - name: grpc-backend
      port: 50051

跨命名空间路由的引用授权机制

Gateway API通过ReferenceGrant资源实现跨命名空间引用的安全控制。当HTTPRoute需要引用不同命名空间的Service或Gateway时，目标命名空间必须存在ReferenceGrant明确授权。

# 在Gateway所在命名空间授权业务命名空间的引用
apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-production-routes
  namespace: gateway-system
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: production
  to:
    - group: ""
      kind: Service
    - group: gateway.networking.k8s.io
      kind: Gateway

Envoy Gateway作为Gateway API控制器的部署

Envoy Gateway是Envoy社区提供的Gateway API实现，以Envoy Proxy作为数据面，支持完整的Gateway API v1标准。部署流程包括安装CRD、部署控制器和创建GatewayClass。

# 安装Envoy Gateway
helm install eg-helm oci://docker.io/envoyproxy/gateway-helm --version v1.2.0 -n envoy-gateway-system --create-namespace

# 等待控制器就绪
kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

# 创建GatewayClass
kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
EOF

# 部署Gateway和测试应用后验证
kubectl get gateway -A
kubectl get httproute -A
kubectl get tcproute -A

# 检查Envoy Proxy Pod状态
kubectl get pods -n envoy-gateway-system
# 期望输出：envoy-xxxxx  1/1  Running  0  2m

从Ingress迁移到Gateway API的策略

生产环境迁移需保证流量不中断。推荐采用双写并行阶段，新旧控制器同时运行，逐步将DNS权重切到Gateway API入口。

# 迁移工具：ingress2gateway自动转换Ingress资源
# 安装ingress2gateway
go install github.com/kubernetes-sigs/ingress2gateway@latest

# 批量转换现有Ingress资源
ingress2gateway print --providers ingress > gateway-api-resources.yaml

# 转换后会生成HTTPRoute和Gateway资源，需人工检查路由规则
# 特别是TLS证书引用和annotation中的自定义配置

# 应用转换后的资源
kubectl apply -f gateway-api-resources.yaml

# 验证路由规则生效
kubectl get httproute -A
kubectl describe httproute api-route -n production

常见部署问题与排查方法

Q: HTTPRoute状态显示Accepted但流量未到达后端服务
A: 检查HTTPRoute的conditions字段，确认Programmed条件为True。使用kubectl describe httproute查看控制器报告的错误。常见原因是Gateway的allowedRoutes未包含目标命名空间，或ReferenceGrant缺失。

Q: Envoy Proxy Pod频繁重启且日志显示配置加载失败
A: 检查Envoy Gateway控制器日志kubectl logs -n envoy-gateway-system deployment/envoy-gateway。配置加载失败通常由Gateway或HTTPRoute的YAML格式错误引起，控制器的reconcile日志会指出具体的字段校验失败信息。