从 Ingress NGINX 迁移到 Gateway API

适用场景

Ingress NGINX 的注解生态复杂，跨团队共享网关时权限边界模糊。Gateway API 用角色分离的 GatewayClass、Gateway、HTTPRoute 表达路由，适合平台团队统一管理入口。

前置条件

• Kubernetes 集群支持 Gateway API CRD。
• 选择实现：Envoy Gateway、Istio、Cilium、Traefik 等。
• 梳理现有 Ingress 的 host、path、TLS、重写、限流和灰度注解。
• 准备新网关的 LoadBalancer 地址或域名。

步骤

1. 安装 Gateway API CRD 和所选实现（以 Envoy Gateway 为例）：

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.0/standard-install.yaml
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.2.0 \
  --namespace envoy-gateway-system --create-namespace

2. 创建 GatewayClass 和 Gateway：

kubectl apply -f - <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public
  namespace: demo
spec:
  gatewayClassName: eg
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: demo-tls
EOF

3. 把 Ingress 路由翻译成 HTTPRoute：

kubectl apply -f - <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo
  namespace: demo
spec:
  parentRefs:
  - name: public
  hostnames:
  - demo.example.com
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    backendRefs:
    - name: api
      port: 8080
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: web
      port: 80
EOF

4. 处理 Ingress 注解差异：

• rewrite-target 对应 URLRewrite 过滤器。
• canary 对应权重或 Header 匹配。
• proxy-body-size、超时和限流对应实现侧的 ClientTrafficPolicy/BackendTrafficPolicy。
• auth-url 对应 ExtAuth 或外部认证过滤器。

5. 测试新网关地址。用 curl --resolve 或临时 hosts 验证，不要先改 DNS：

curl -k --resolve demo.example.com:443:$GW_IP https://demo.example.com/api/health

6. 灰度切换：先切一个低风险域名，再逐步扩大。保留旧 Ingress 和 DNS 记录。

验证

• 所有 host/path 路由与旧 Ingress 行为一致。
• TLS 证书正确加载，HTTP 能按预期跳转 HTTPS。
• 重写、超时、请求体大小和限流行为符合预期。
• WebSocket/SSE 长连接正常。
• 网关指标和访问日志可观测。
• 旧 Ingress 流量降为 0 后再考虑删除。

回滚

• 保留旧 Ingress 和 LoadBalancer，DNS 切回即可。
• 不删除旧证书和 Secret，直到新网关稳定运行一个完整周期。
• Gateway API 资源可以并行存在，回滚不需要重建应用。
• 记录旧 Ingress 的注解清单，避免遗漏。

常见坑

• 只翻译了 path，没有处理 rewrite 和 trailing slash。
• Ingress 的注解语义在 Gateway API 中没有一一对应，需要实现侧策略。
• 证书没有放在 Gateway 所在命名空间，certificateRefs 解析失败。
• 多个团队共用 Gateway，没有用 allowedRoutes 限制命名空间。
• 新网关的 LoadBalancer 地址没有加入 DNS，测试时看似 404。
• HTTPRoute 的 parentRefs 指向错误命名空间的 Gateway。
• 旧 Ingress 和新 Gateway 同时处理同一域名，流量随机分流。

相关命令

• kubectl — 管理 GatewayClass、Gateway、HTTPRoute
• curl — 按 host 验证路由
• openssl — 检查 TLS 证书
• istioctl / egctl — 网关诊断
• dig — 检查 DNS 切换