Kubernetes Gateway API 到底是什么？新手如何快速上手配置？

Kubernetes Gateway API 是社区在 Ingress 基础上提出的新一代流量管理标准，目标是用更清晰的对象模型替代过去五花八门的 Ingress 注解。它将网关能力抽象成多个协作的资源类型，让集群管理员、基础设施供应商和应用开发者各司其职。对于刚接触云原生的新手来说，理解这套模型比死记命令更重要。

Gateway API 的核心资源与角色划分

在 Gateway API 中，最重要的三个资源是 GatewayClass、Gateway 和 HTTPRoute。GatewayClass 类似于存储领域的 StorageClass，由网关实现方（比如 Envoy、Istio 或 Nginx）注册，描述一类网关的能力与参数。集群管理员负责创建 GatewayClass，应用团队通常只能引用而不能修改它。

Gateway 则是 GatewayClass 的一个实例，定义了监听端口、证书以及允许哪些命名空间附加路由。比如你可以让一个 Gateway 只监听 80 和 443，并声明仅接受来自 team-a 命名空间的 HTTPRoute。这种约束让平台团队能把网关部署和租户隔离做得非常干净，而不用在 Ingress 控制器里配一大堆命令行参数。

最后是 HTTPRoute，它才是应用开发者真正要写的对象。一条 HTTPRoute 可以把特定主机名和路径映射到后端 Service，并指定权重、请求头匹配等规则。下面是一段最基础的 HTTPRoute 示例，把 shop.ippipp.com 的 /cart 路径转发到 cart-svc：

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cart-route
  namespace: team-a
spec:
  parentRefs:
    - name: public-gateway
      namespace: infra
  hostnames:
    - "shop.ippipp.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /cart
      backendRefs:
        - name: cart-svc
          port: 8080

从这段配置能看出，HTTPRoute 通过 parentRefs 指向了 infra 命名空间里的 Gateway，这就是跨命名空间引用的典型用法。应用团队不需要知道网关 Pod 跑在哪台机器上，只要规则被接受，流量就能通。

从 Ingress 迁移到 Gateway API 的实际差异

很多新手之前只用过 Ingress，迁移时最不习惯的就是注解消失。过去我们写 nginx.ingress.kubernetes.io/canary: "true" 来做灰度，在 Gateway API 里变成了 HTTPRoute 规则里的 weight 字段。这种改变看似只是换写法，实质是把厂商私有逻辑变成了标准字段，以后换网关实现不用重写业务配置。

另一个差异是匹配能力。Ingress 基本只能按路径和主机名分流，而 HTTPRoute 的 matches 支持请求头、查询参数、HTTP 方法等多种条件。例如你想把带了 x-debug: true 头的请求导到调试版本，只要加一个 header 匹配项即可，不必借助 Lua 脚本或自定义注解。

下面用一段对比代码展示新旧写法。左边是 Ingress 的 canary 注解，右边是 Gateway API 的权重路由：

# 旧 Ingress 灰度写法
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
  name: old-ing
spec:
  rules:
    - host: shop.ippipp.com
      http:
        paths:
          - path: /
            backend:
              service:
                name: shop-v2
                port:
                  number: 80

# 新 Gateway API 权重写法
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: shop-route
spec:
  parentRefs:
    - name: public-gateway
  hostnames:
    - "shop.ippipp.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: shop-v1
          port: 80
          weight: 80
        - name: shop-v2
          port: 80
          weight: 20

可以看到，Gateway API 把权重直接放在 backendRefs 数组里，同一个规则就能描述稳定版和灰度版的比例。这种结构化的方式让 GitOps 工具校验配置更方便，也减少了人为写错注解格式的概率。

新手部署 Gateway 与排查路由失败的方法

实际动手时，第一步是在集群里安装支持 Gateway API 的控制器，比如 Nginx Gateway Fabric 或 Envoy Gateway。安装完后，先用 kubectl get gatewayclass 确认有可用的 GatewayClass。如果没有，说明控制器没注册成功，需要检查其 Deployment 日志。

创建 Gateway 之后，新手常遇到 HTTPRoute 不生效的问题。优先看 Gateway 的 status.addresses 有没有分配到 IP，再看 HTTPRoute 的 parentRefs 是否指向了正确的 Gateway 名称和命名空间。跨命名空间引用时，还要确认 Gateway 的 spec.listeners.allowedRoutes 放开了对应命名空间，否则路由会被拒绝。

当流量还是进不来，可以借助以下命令排查：用 kubectl describe httproute 看事件里有没有 ResolvedRefs 错误；用 kubectl logs 看网关 Pod 是否报证书不匹配。下面是一段检查路由状态的简单脚本思路：

# 查看 HTTPRoute 是否被 Gateway 接受
kubectl get httproute shop-route -o jsonpath='{.status.parents[0].conditions[?(@.type=="Accepted")].status}'

# 查看 Gateway 监听地址
kubectl get gateway public-gateway -n infra -o jsonpath='{.status.addresses}'

把这些排查动作养成习惯，你就能在几分钟内定位是配置写错、权限不足还是底层网络问题。比起过去在 Ingress 控制器里翻几百行日志，Gateway API 的状态字段让新手也能有条理地调试。

KubernetesGateway_APIingress修改时间：2026-08-18 00:44:30