Gateway 与 Ingress

Kubernetes 的七层入口正在从 Ingress 转向 Gateway API。Ingress 仍然是稳定 API，不会从 Kubernetes 里消失，但官方已将其标为 frozen，新功能全部进入 Gateway API。社区维护的 ingress-nginx 控制器已于 2026 年 3 月退役。

这里要分清三个对象：Ingress API 是 Kubernetes 资源类型（规则怎么写）；Ingress Controller 是真正处理流量的程序（谁执行规则）；Gateway API 是新的入口资源模型（拆成 GatewayClass、Gateway、HTTPRoute 三个角色）。

入口链路的位置

Ingress 和 Gateway 都不直接等于 Nginx、Envoy 或负载均衡器。它们是 Kubernetes 资源对象，描述"域名、路径、证书、后端 Service"这类规则。真正接收和转发请求的是控制器。

Gateway API 拆成三层后，平台侧和应用侧的边界更清楚：

Ingress 的现状

项目	现状
Ingress API	稳定 API，无移除计划，但已 frozen
新功能	官方方向是 Gateway API
ingress-nginx	社区维护的 kubernetes/ingress-nginx 已于 2026 年 3 月退役
老集群	现有 Ingress 仍能工作，但控制器维护状态要单独评估

ingress-nginx 退役不等于"所有 NGINX 控制器都失效"。F5 NGINX Ingress Controller、商业 NGINX、云厂商控制器、HAProxy、Traefik、Envoy Gateway、Cilium Gateway 都是独立项目。

老集群里从 Ingress 迁走，最麻烦的通常不是普通路由，而是 annotation：

常见能力	迁移关注
rewrite	Gateway API filter 或控制器扩展是否支持
canary	HTTPRoute 权重、Header 匹配或 Argo Rollouts
限流	控制器插件、外部网关或 Service Mesh
鉴权	控制器扩展、外部认证服务
大 body / 超时	控制器是否有对应策略

Gateway API 对象模型

GatewayClass 声明由哪个控制器处理：

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy
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
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All  # 允许其他 namespace 绑定路由，生产里配合 RBAC 收紧

HTTPRoute 声明具体域名、路径和后端：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: web
  namespace: demo
spec:
  parentRefs:
    - name: main-gateway
      namespace: gateway-system
  hostnames:
    - web.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: web
          port: 80

权重金丝雀也放在 HTTPRoute 里，不需要额外注解：

rules:
  - backendRefs:
      - name: web-v1
        port: 80
        weight: 90
      - name: web-v2
        port: 80
        weight: 10

控制器选型

控制器	特点
Envoy Gateway	Gateway API 原生方向
Traefik	上手轻，Gateway API 支持积极
HAProxy Ingress/Gateway	传统负载均衡能力强
Cilium Gateway	和 Cilium/eBPF 网络栈结合
云厂商 Gateway/LB Controller	云上和 SLB/ALB/NLB 集成
F5 NGINX Ingress Controller	NGINX 生态，和社区 ingress-nginx 不是同一项目

选型关注点：Gateway API 支持程度、现有注解迁移成本、访问日志和指标、CRD 运维复杂度、CNI 配合、社区维护情况。

排查和验证

确认集群是否还在使用社区 ingress-nginx：

kubectl get pods -A -l app.kubernetes.io/name=ingress-nginx

查看 Ingress 和 Gateway API 资源：

kubectl get ingress -A
kubectl get ingressclass
kubectl get gatewayclass
kubectl get gateway -A
kubectl get httproute -A

从客户端验证入口（绕过 DNS）：

curl -H 'Host: web.example.com' http://<gateway-or-lb-ip>/

排查 HTTPRoute 未生效的关键是看 status：

kubectl get httproute web -n demo -o yaml | grep -A40 status:

Conditions	含义
Accepted=False	路由没被 Gateway 接受——parentRefs、权限或 listener 不匹配
ResolvedRefs=False	Service、Secret 或跨 namespace 引用解析失败
Programmed=False	控制器还没把规则下发到数据面

迁移思路

迁移前先盘点现有 Ingress 和 annotation：

kubectl get ingress -A
kubectl get ingress -A -o yaml | grep -n "nginx.ingress.kubernetes.io"

最小迁移对照：

Ingress 字段	Gateway API 对象
ingressClassName	GatewayClass / Gateway
rules.host	HTTPRoute.spec.hostnames
paths.path	HTTPRoute.rules.matches.path
backend.service	HTTPRoute.rules.backendRefs
tls.secretName	Gateway.listener.tls.certificateRefs 或控制器约定

迁移按入口链路拆分：低风险域名先迁，保留旧 Ingress 回退路径。一次性把所有 Ingress 换成 HTTPRoute，看起来省事，实际会把 rewrite、TLS、限流和日志差异全部叠在一起——入口层出问题影响面很大。