K8s Docs

Appearance

Gateway API 入门 ​

欢迎使用 Gateway API！无论你是新用户，还是正在从其他 Ingress 方案迁移过来，本页面都是最佳起点。

新用户 ​

如果你是第一次接触 Gateway API，我们推荐以下路径：

1. 安装 Gateway API 的 CRD 和一个 Controller（控制器） ​

你可以选择直接安装一个 Gateway 控制器（它通常会顺带把 CRD 装好），也可以手动安装 Gateway API 的 CRD。

2. 动手尝试各篇指南 ​

一旦有控制器在运行，你就可以从一个简单示例开始，再逐步探索更高级的功能：

  • 部署一个简单的 Gateway（适合作为第一个上手示例）
  • HTTP 路由
  • HTTP 重定向与重写
  • HTTP 流量切分
  • 跨 Namespace 路由
  • 配置 TLS
  • TCP 路由
  • gRPC 路由
  • ListenerSet

从 Ingress 迁移 ​

如果你打算从 Kubernetes Ingress 迁移过来，我们也有专门指南帮助你起步：

  • 从 Ingress 迁移：一份通用的迁移指南，适用于从任何 Ingress 实现迁移到 Gateway API。它涵盖了关键差异，并提供了一个手把手的迁移示例。
  • Ingress-NGINX 用户欢迎指南：专门为最流行的 Ingress 实现 Ingress-NGINX 用户准备的指南。它提供了一系列资源以及常见问题的解答。

安装 Gateway 控制器 ​

有多个项目支持 Gateway API。只要在 Kubernetes 集群中安装一个 Gateway 控制器，就可以尝试上面列出的那些指南。这能让你验证：所声明的路由配置，确实被你的 Gateway 资源（以及它们所代表的底层网络基础设施）落地实现了。请注意，许多 Gateway 控制器的安装流程会自动安装/卸载 Gateway API 的安装包。

安装 Gateway API ​

从更早的 Experimental 通道版本升级 ​

如果你之前安装过更早版本的 experimental 通道，请参考 v1.1 升级说明。

一个 Gateway API 安装包（bundle）对应某个 Gateway API 版本所关联的一组 CRD。每一个发布版本都包含两个稳定程度不同的通道（channel）：

安装标准通道（Standard Channel） ​

标准发布通道包含所有已晋升为 GA（正式发布）或 Beta 的资源，包括 GatewayClass、Gateway、HTTPRoute 和 ReferenceGrant。要安装该通道，请运行以下 kubectl 命令：

bash
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml

可参阅 server-side apply 文档 以了解上述 kubectl 命令选项的更多细节。

安装实验通道（Experimental Channel） ​

实验发布通道包含标准发布通道中的全部内容，外加一些实验性的资源和字段，例如 TCPRoute、TLSRoute 和 UDPRoute。

请注意：未来 API 版本可能对实验性资源和字段引入破坏性变更。例如，任何实验性资源或字段都可能在后续版本中被移除。关于实验通道的更多信息，请参阅我们的 版本化（versioning）文档。

要安装实验通道，请运行以下 kubectl 命令：

bash
kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/experimental-install.yaml

可参阅 server-side apply 文档 以了解上述 kubectl 命令选项的更多细节。

v1.2 升级说明 ​

在升级到 Gateway API v1.2 之前，你需要先确认：所有正在使用的 Gateway API 实现都已升级到这些资源的 v1 API 版本（而不是 v1alpha2）。请注意，即使你的 YAML 清单中已经在使用 v1，某些控制器仍可能使用 v1alpha2，这会导致本次升级过程中失败。

一旦确认你所依赖的实现都已升级到 v1，就可以开始安装 v1.2 的 CRD 了。在大多数情况下，这一步直接执行就能顺利完成，无需额外操作。

如果在安装这些 CRD 时遇到问题，通常意味着某个（或全部）CRD 的 storedVersions 字段中仍包含 v1alpha2。该字段用于记录曾经被用于持久化某资源的所有 API 版本。遗憾的是，它并不会被自动清理。要检查这些值，可以运行以下命令：

bash
kubectl get crd grpcroutes.gateway.networking.k8s.io -ojsonpath="{.status.storedVersions}"
kubectl get crd referencegrants.gateway.networking.k8s.io -ojsonpath="{.status.storedVersions}"

如果其中任何一条返回的列表中包含 "v1alpha2"，就说明我们需要手动把该版本从 storedVersions 中移除。

在动手之前，最好先确保所有的 ReferenceGrant 和 GRPCRoute 都已更新到最新的存储版本：

bash
crds=("GRPCRoutes" "ReferenceGrants")

for crd in "${crds[@]}"; do
  output=$(kubectl get "${crd}" -A -o json)

  echo "$output" | jq -c '.items[]' | while IFS= read -r resource; do
    namespace=$(echo "$resource" | jq -r '.metadata.namespace')
    name=$(echo "$resource" | jq -r '.metadata.name')
    kubectl patch "${crd}" "${name}" -n "${namespace}" --type='json' -p='[{"op": "replace", "path": "/metadata/annotations/migration-time", "value": "'"$(date +%Y-%m-%dT%H:%M:%S)"'" }]'
  done
done

等所有 ReferenceGrant 与 GRPCRoute 资源都已经更新到最新的存储版本后，就可以对 ReferenceGrant 与 GRPCRoute 的 CRD 本身打补丁了：

bash
kubectl patch customresourcedefinitions referencegrants.gateway.networking.k8s.io --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1beta1"]}}'
kubectl patch customresourcedefinitions grpcroutes.gateway.networking.k8s.io --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1"]}}'

完成上述步骤之后，再升级到最新的 GRPCRoute 与 ReferenceGrant 就可以顺利完成。

v1.1 升级说明 ​

如果你之前已经在用更早版本 Gateway API 中实验通道的 GRPCRoute 或 BackendTLSPolicy CRD，本次升级就需要特别小心。如果你从未安装过 Gateway API，或只用过标准通道，可以直接跳过本节。

GRPCRoute ​

小结：如果你已经在用 v1alpha2 的 GRPCRoute，在 v1.1 阶段请继续使用实验通道版本的 GRPCRoute，直到你所依赖的实现都已升级到支持 GRPCRoute v1 为止。

说明：随着 GRPCRoute 升级为 GA，它已经被纳入标准通道。问题在于，对于已经在用实验通道版本 GRPCRoute 的用户来说，标准通道不再向下兼容——标准通道下的 CRD 默认不会暴露 alpha API 版本，以避免在标准通道中引入任何弃用版本。这意味着标准通道下的 GRPCRoute 不再包含 v1alpha2。所有在 v1.1 之前构建的 GRPCRoute 实现都只依赖 v1alpha2，因此必须升级以支持 GRPCRoute v1。在实现支持 v1 之前，你可以安全地升级到 v1.1 中实验通道版本的 GRPCRoute（它会同时暴露 v1 与 v1alpha2）。

升级顺序：如果你已经在用 v1alpha2 的 GRPCRoute，我们建议按以下顺序升级：

  1. 安装实验通道下的 v1.1 GRPCRoute CRD
  2. 将所有清单从 v1alpha2 改为 v1
  3. 升级到你所选择的、支持 GRPCRoute v1 API 版本的实现
  4. 安装标准通道下的 v1.1 GRPCRoute CRD

BackendTLSPolicy ​

小结：如果你之前安装过 BackendTLSPolicy，请先等待你所依赖的实现升级到支持 v1alpha3。当升级到一个支持 v1alpha3 的实现时，还需要先把旧的 BackendTLSPolicy CRD 卸载掉，再安装新的。

说明：BackendTLSPolicy 在 v1.1 中对若干字段做了重大重命名，因此版本号提升到 v1alpha3。由于它属于实验通道，我们不为这次变更提供原地升级路径——你需要把 CRD 的升级与你所依赖的 BackendTLSPolicy 实现一起协调进行。

升级顺序：如果你已经在用 v1alpha2 的 BackendTLSPolicy，我们建议按以下顺序升级：

  1. 等待你所选用的实现发布对 v1alpha3 的支持
  2. 删除 v1.1 之前版本的 BackendTLSPolicy CRD（这同时会删除集群中所有 BackendTLSPolicy 实例）
  3. 安装 v1.1 版本的新 BackendTLSPolicy CRD
  4. 部署支持 BackendTLSPolicy v1alpha3 的实现版本

请注意：部分实现可能更希望把步骤 3 和 4 的顺序调换，建议查阅你所选实现的相关发布说明。

清理 ​

使用完毕后，你可以通过把上面命令中的 apply 换成 delete 来卸载 Gateway API 的 CRD。如果这些资源正在被使用，或者它们是由某个 Gateway 控制器安装的，请不要卸载。该卸载操作会作用于整个集群，请勿在可能仍有其他人在使用这些资源时执行，否则会破坏所有依赖这些资源的工作负载。

关于 CRD 管理的更多内容 ​

本指南只提供了 Gateway API 上手的概览。如需深入了解 Gateway API CRD 的管理，请参阅我们的 CRD 管理指南。

基于 MIT 协议发布

Copyright © 2024-2026 K8s Docs