Gateway API
概念引入
在文章 03 中，你学了 Ingress——K8s 的"大门保安"，负责根据域名和路径把流量分发到不同 Service。但 Ingress 有几个痛点：
- 表达能力弱：只支持 HTTP 的 host + path 匹配，想做 header 匹配、权重分流？不行
- 配置不标准：每个 Ingress Controller 用不同的 annotation，换个 Controller 就要重写配置
- 角色不分离：运维管网关基础设施，开发管路由规则，但 Ingress 把两者混在一个资源里
Gateway API 就是为了解决这些问题而生的新一代标准。
原理讲解
Gateway API 的三个核心资源
| 资源 | 谁管 | 作用 | 类比 |
|---|---|---|---|
| GatewayClass | 基础设施提供商 | 定义网关类型（如 nginx、envoy） | “我要买什么型号的门” |
| Gateway | 集群运维 | 创建网关实例，定义监听器和端口 | “把门装在哪里，开几个口” |
| HTTPRoute | 应用开发者 | 定义路由规则（路径、header、权重） | “进哪个门走哪条路” |
Ingress vs Gateway API 对比
| 维度 | Ingress | Gateway API |
|---|---|---|
| 标准化 | ❌ 各 Controller 用不同 annotation | ✅ 统一标准，跨 Controller 兼容 |
| 路由能力 | 仅 host + path | host + path + header + query + method |
| 流量分割 | ❌ 不支持 | ✅ 权重分流（金丝雀发布） |
| 角色分离 | ❌ 一个资源 | ✅ 三层分离（Class/Gateway/Route） |
| 协议支持 | HTTP/HTTPS | HTTP/HTTPS/TCP/TLS/gRPC |
| 状态 | 稳定但功能受限 | GA（正式可用），持续演进 |
HTTPRoute 的强大能力
apiVersion:gateway.networking.k8s.io/v1kind:HTTPRoutemetadata:name:advanced-routespec:parentRefs:-name:my-gatewaysectionName:httphostnames:-"app.example.com"rules:# 规则 1：按 header 路由-matches:-headers:-name:x-versionvalue:"v2"backendRefs:-name:v2-svcport:80# 规则 2：按权重分流（金丝雀发布）-matches:-path:value:/apibackendRefs:-name:api-v1port:80weight:90# 90% 流量到 v1-name:api-v2port:80weight:10# 10% 流量到 v2# 规则 3：请求重定向-matches:-path:value:/old-pathfilters:-type:RequestRedirectrequestRedirect:path:type:ReplaceFullPathreplaceFullPath:/new-path迁移路径
大多数 Ingress Controller（Nginx Ingress、Traefik、Kong）已经支持 Gateway API。迁移步骤：
- 安装支持 Gateway API 的 Controller
- 创建 GatewayClass 和 Gateway
- 把 Ingress 规则逐一转换为 HTTPRoute
- 验证无误后删除旧 Ingress
动手实验
配套实验位于
docs/labs/beginner/gateway-api/⚠️ 本实验安装 Gateway API CRD（资源定义），但不安装 Gateway Controller（需要额外网络下载镜像）。学习重点是资源结构和角色分离——Gateway 和 HTTPRoute 的定义方式、与 Ingress 的对比。
本实验用 Gateway API 重新实现 Ingress 的路由规则。
步骤 1：安装 CRD 并创建后端服务
cddocs/labs/beginner/gateway-apibashsetup.sh步骤 2：认识 Gateway 资源
# 查看已创建的 Gatewaykubectl get gateway# 查看 Gateway 的 YAML 定义kubectl describe gateway my-gatewaycatmanifests/gateway.yaml解读：gatewayClassName: nginx指定用哪种网关实现，listeners定义监听的端口和协议。这个资源由运维管理——决定网关实例的规格。
步骤 3：认识 HTTPRoute 资源
# 查看已创建的 HTTPRoutekubectl get httproute# 查看路由规则kubectl describe httproute app-routecatmanifests/httproute.yaml解读：/api → api:5678，/ → web:80。这个资源由开发管理——决定路由规则，不需要关心网关是用 nginx 还是 envoy 实现的。
步骤 4：验证后端服务
# 通过 port-forward 直接访问后端（无需网关控制器）kubectl port-forward svc/web8080:80&curl-slocalhost:8080|head-5kill%12>/dev/null kubectl port-forward svc/api8081:5678&curl-slocalhost:8081kill%12>/dev/null💡 在完整部署中，Gateway Controller 会自动配置代理，你不需要手动 port-forward。这里直接访问后端是为了验证服务可用。
步骤 5：理解流量分割（金丝雀发布）
# 查看权重分流路由定义catmanifests/canary-route.yaml# 创建资源（没有 Controller 不会有实际分流效果，但能学习 API 结构）kubectl apply-fmanifests/canary-route.yaml kubectl get httproute canary-route-oyaml|grep-A10backendRefs关键字段：weight: 80和weight: 20——声明式地定义流量比例，不需要 annotation。
步骤 6：清理
bashteardown.sh自检问题
- Gateway API 的三层结构（GatewayClass / Gateway / HTTPRoute）分别由谁管理？
- Ingress 的 annotation 有什么问题？Gateway API 怎么解决的？
- 你的团队要做一个灰度发布（10% 流量到新版本），用 Ingress 和 Gateway API 分别怎么实现？
下一步
Gateway API 是 Ingress 的未来。你的基础功已经扎实了，接下来进入进阶实战阶段！
🎉恭喜！你已经完成了 K8s Guide 初学者轨道的全部 11 篇文章。
从零基础到能独立部署、排查、运维 K8s 应用——你已经掌握了核心知识。接下来的面试轨道会帮你把这些知识转化为 Offer。
📚本文来自 K8s Guide—— 开源免费的 Kubernetes 中文学习指南
- 🗺️ 初学者轨道 + 面试轨道，从零基础到拿 Offer 一站式覆盖
- 🧪 每篇文章配套 Kind 实验脚本，本地一键运行
- 🔗 本文源码：docs/beginner/20-gateway-api.md
⭐如果对你有帮助，欢迎 Star！github.com/callmebg/k8s-guide
 agent和组件)