Gateway API 入门指南 · 总结

本目录 gateway/ 收录了对 https://gateway-api.sigs.k8s.io/guides/getting-started/introduction/ 的中文翻译与要点总结。
完整中文翻译：getting-started.md
原始 HTML 快照：introduction.html
提取的纯文本：introduction.txt

一、文档定位

Gateway API 是 Kubernetes 中用于描述服务网络路由（L4/L7）的一组官方 API 资源，是传统 Ingress 资源的继任者。它由 GatewayClass、Gateway、HTTPRoute、ReferenceGrant 等 CRD 组成，目标是角色化、可表达、跨实现。

本文档（Introduction）是整个 Gateway API 文档体系中面向新用户的入口页，给出了上手路径、控制器选型建议、CRD 安装命令以及版本升级注意事项。

二、面向新用户的推荐路径

整个上手流程被简化为两步：

安装 Gateway API 的 CRD 与一个 Controller
- 简单做法：直接装一个 Gateway 控制器，它通常会顺带把 CRD 装好。
- 进阶做法：手动安装 CRD（便于先看清"地基"）。
跟着示例指南动手实践，按由浅入深顺序：
- 部署一个简单的 Gateway（首个示例）
- HTTP 路由
- HTTP 重定向 / 重写
- HTTP 流量切分
- 跨 Namespace 路由
- TLS 配置
- TCP 路由
- gRPC 路由
- ListenerSet

三、面向迁移用户

如果你正从 Kubernetes Ingress 迁过来，文档提供两份专门指南：

从 Ingress 迁移（通用版）：覆盖关键差异，并给出完整的迁移示例。
Ingress-NGINX 用户欢迎指南：为最常见的 Ingress-NGINX 用户准备，含资源映射与 FAQ。

核心动机：Ingress 表达力有限（注解地狱、厂商锁定），而 Gateway API 通过结构化字段和角色化（基础设施提供者 / 集群操作员 / 应用开发者）解决了这些问题。

四、Gateway 控制器的选型

有多个开源项目实现 Gateway API（Istio、NGINX、HAProxy、Envoy Gateway、Cilium、Kong、Traefik 等）。选型标准大致是：

维度	关注点
协议支持	HTTP/1.1、HTTP/2、gRPC、TCP、TLS
部署形态	Sidecar、Gateway Proxy、DaemonSet …
性能 / 规模	路由数、QPS、内存占用
多租户	Namespace 隔离、ReferenceGrant 模型
生态	与服务网格、可观测性组件的集成

许多控制器在安装/卸载时会自动管理 Gateway API CRD 的生命周期，省心但灵活性稍差。

五、CRD 的两个发布通道

Gateway API 每次发布都会同时提供两个通道：

通道	内容	适用场景
Standard（标准）	已晋升为 GA / Beta 的资源：`GatewayClass`、`Gateway`、`HTTPRoute`、`ReferenceGrant` 等	生产环境首选，稳定性优先
Experimental（实验）	标准通道的全部 + 实验性资源：`TCPRoute`、`TLSRoute`、`UDPRoute` 等	评估新特性、PoC 环境

安装命令

bash

# 标准通道
kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

# 实验通道
kubectl apply --server-side -f \
  https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

注意：使用 --server-side 是为了字段归属清晰、避免冲突，与 SIG CLI 推荐用法一致。

六、升级注意事项（重点）

v1.2 升级

升级前必须确认：

所有 Gateway API 实现（控制器）已升级到使用 v1 API 版本，而不是 v1alpha2。
即便你 YAML 中已写 v1，老控制器内部仍可能使用 v1alpha2，会导致升级失败。

如果 storedVersions 中残留 v1alpha2，需要：

先把 ReferenceGrant 与 GRPCRoute 实例的存储版本刷新到最新（用 kubectl patch + 注解触发）；
再把对应 CRD 的 status.storedVersions 字段裁剪掉 v1alpha2。

v1.1 升级

两个实验通道的 CRD 出现过破坏性变更：

GRPCRoute：从 v1alpha2 升 v1。在控制器尚未支持 v1 之前，应停留在 v1.1 的实验通道版本（同时暴露 v1 与 v1alpha2）。
BackendTLSPolicy：字段重命名，版本号升到 v1alpha3。没有原地升级路径，需先卸载旧 CRD，再安装新版本。

七、清理

结束试用时，把 apply 替换为 delete 即可卸载 CRD。注意：

如果资源正在被使用，或是由某个 Gateway 控制器安装的，不要卸载。
卸载是集群级的，会影响所有正在使用这些资源的工作负载。

八、关键术语速查

术语	含义
`GatewayClass`	集群范围的"网关类"，由基础设施提供者定义（如 `istio-waypoint`、`nginx`）
`Gateway`	一个具体的网关实例，绑定到 `GatewayClass` 与监听器（Listener）
`HTTPRoute`	HTTP/1.1、HTTP/2、HTTP/3 的 L7 路由规则
`TCPRoute` / `UDPRoute` / `TLSRoute`	L4 路由（实验通道）
`GRPCRoute`	gRPC 专用路由（已 GA）
`ReferenceGrant`	跨 Namespace 引用授权：让 `HTTPRoute` 跨 NS 引用 `Service` 成为可能
`BackendTLSPolicy`	后端 TLS 配置（实验通道，v1.1 起）
`ListenerSet`	同一 Gateway 下共享配置的监听器集合
Channel	Gateway API 的发布通道（Standard / Experimental）

九、与其他相关文档的衔接

本文档只覆盖最浅的上手层。继续深入建议按以下顺序：

CRD 管理指南（CRD Management Guide）—— 安装/升级/卸载 CRD 的细节。
API 概念（Concepts）—— 资源模型、角色、Listener、Route 之间的引用关系。
实现（Implementations）—— 各控制器的对比与功能矩阵。
迁移指南（Migrating from Ingress）—— 从 Ingress 平滑过渡。
安全模型（Security Model）—— ReferenceGrant、跨命名空间信任、mTLS 等。

十、一句话总结

Gateway API 入门 = "装控制器" + "装对应通道的 CRD" + "按示例动手"；生产用标准通道、玩新特性用实验通道；任何升级前先看控制器是否已经支持新版本 API。

Gateway API 入门指南 · 总结 ​

一、文档定位 ​

二、面向新用户的推荐路径 ​

三、面向迁移用户 ​

四、Gateway 控制器的选型 ​

五、CRD 的两个发布通道 ​

安装命令 ​

六、升级注意事项（重点） ​

v1.2 升级 ​

v1.1 升级 ​

七、清理 ​

八、关键术语速查 ​

九、与其他相关文档的衔接 ​

十、一句话总结 ​