升级版本规则

了解当前版本和目标版本如何影响集群升级，有助于您在开始之前验证版本偏差、升级顺序和操作系统要求。

特定于版本的升级信息

下表介绍了特定于版本的升级信息。在表格下方，您可以找到有关特定版本的详细信息。版本按从新到旧的顺序排列。找到您要升级到的版本，了解适用于您的集群的具体细节和规则。

版本	优先升级	控制平面 (CP) 版本	工作器节点池版本	高级集群状态	是否支持旧版功能？	默认和必需的操作系统映像	Kubeception 节点升级行为	一起统计 cert-manager
1.36	管理员集群	1.36、1.35、1.34	1.36、1.35、1.34	必填	无	ubuntu_cgv2，cos_cgv2	不支持	绑定
1.35	管理员集群	1.35、1.34、1.33	1.35、1.34、1.33	必填	无	ubuntu_cgv2、cos_cgv2 强制性（cgroup v1 已弃用）	不支持	绑定
1.34	管理员集群	1.34、1.33、1.32	1.34、1.33、1.32	强制（无法选择退出；非高级广告系列会自动转换）	无	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	不支持	绑定
1.33	管理员集群	1.33、1.32、1.31	1.33、1.32、1.31	默认（自动转换）（仅限 1.32 至 1.33 版本可选择退出）	无	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	不支持	高级集群捆绑包
1.32	管理员集群	1.32、1.31、1.30	1.32、1.31、1.30	正式版（支持升级；支持单独升级和跳过节点升级）	无	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	不受支持（必须迁移到 Controlplane V2）	高级集群捆绑包
1.31	管理员集群	1.31、1.30、1.29	1.31、1.30、1.29	预览版（无法升级到 1.32；无法单独升级节点或跳过节点升级）	是（Seesaw、F5、Kubeception、非高可用性）；强烈建议迁移到推荐功能；必须使用 Dataplane V2	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	管理员节点随管理员集群一起升级；用户控制平面节点随用户集群一起升级	未捆绑
1.30	用户集群	1.30	1.30、1.29、1.28	不可用	是（Seesaw、F5、Kubeception、非高可用性）；强烈建议迁移到推荐功能	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	在管理员集群升级期间，控制平面和管理员节点也会升级	未捆绑
1.29	用户集群	1.29、1.30	1.29、1.28、1.16	不可用	是（Seesaw、F5、Kubeception、非高可用性）	ubuntu_cgv2（默认）、cos_cgv2、ubuntu_containerd、cos	在管理员集群升级期间，控制平面和管理员节点也会升级	未捆绑
1.28	用户集群	1.28、1.29、1.30	1.28、1.16、1.15	不可用	是（Seesaw、F5、Kubeception、非高可用性）	ubuntu_containerd（默认）、cos、ubuntu_cgv2、cos_cgv2	在管理员集群升级期间，控制平面和管理员节点也会升级	未捆绑

对于所有版本，您必须同时将负载均衡器节点池版本（具有 enableLoadBalancer: true 的节点池）升级到与用户集群控制平面相同的版本。

按发布版本列出的升级信息

找到您要升级到的版本对应的部分，了解升级到该版本所需的具体信息。

版本 1.36

首先升级：管理员集群

版本偏差规则：

• 1.36 版管理员集群可以管理 1.36、1.35 和 1.34 版用户集群。
• 用户集群控制平面版本：1.36、1.35 或 1.34。
• 工作器节点池版本：1.36、1.35 或 1.34。

高级集群状态：必须使用高级集群。

跳过节点升级：支持。

是否支持旧版功能：否。会阻止升级。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2。新配置的默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：不支持。Blocks 升级。

升级工具：

• gkectl：管理员集群必需。支持的版本为 1.36、1.37 和 1.38。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持此方法。
• Google Cloud 控制台：支持用户集群升级。
• Google Cloud CLI：支持用户集群升级。

其他要求：

• 您可以使用 gkectl upgrade admin --async 异步运行管理员集群升级。

版本 1.35

首先升级：管理员集群

版本偏差规则：

• 版本为 1.35 的管理员集群可以管理版本为 1.35、1.34 和 1.33 的用户集群。
• 用户集群控制平面版本：1.35、1.34 或 1.33。
• 工作器节点池版本：1.35、1.34 或 1.33。

高级集群状态：必须使用高级集群。

跳过节点升级：支持。

是否支持旧版功能：否。会阻止升级。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2 强制（cgroup v1 已弃用）。新配置的默认 osImageType 为 ubuntu_cgv2。您必须先将集群迁移到 cgroup v2，然后才能升级。

Kubeception 节点升级行为：不支持。Blocks 升级。

升级工具：

• gkectl：管理员集群必需。支持的版本为 1.35、1.36 和 1.37。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持此方法。
• 控制台：支持用户集群升级。
• gcloud CLI：支持用户集群升级。

其他要求：

• 您可以使用 gkectl upgrade admin --async 异步运行管理员集群升级。

版本 1.34

首先升级：管理员集群

版本偏差规则：

• 1.34 版管理员集群可以管理 1.34、1.33 和 1.32 版用户集群。
• 用户集群控制平面版本：1.34、1.33 或 1.32。

• 工作器节点池版本：1.34、1.33 或 1.32。

  注意：将非高级集群转换为高级集群时，不允许存在版本偏差。您必须同时升级控制平面和所有节点池。

高级集群状态：必须使用高级集群。

跳过节点升级：支持。

是否支持旧版功能：否。会阻止升级。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：不支持。Blocks 升级。

升级工具：

• gkectl：管理员集群必需。需要将非高级集群转换为高级集群（在 1.34 中为强制性要求；gkectl 二进制文件版本必须与目标发布版本完全匹配）。支持的版本为 1.34、1.35 和 1.36。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持此方法。
• 控制台：支持高级用户集群升级。
• gcloud CLI：支持高级用户集群升级。

其他要求：

升级到 1.34 版还需满足以下额外要求：

• 当您升级到 1.34 版时，非高级集群会自动转换为高级集群。如需了解从非高级集群升级到高级集群的具体规则，请参阅将集群更新或升级为高级集群。

• 捆绑的 cert-manager 是强制性的，并已更新到 1.19 版，会覆盖预先存在的自定义 cert-manager 安装。如需详细了解如何升级到绑定的 cert-manager，请参阅使用绑定的 cert-manager。

• 节点容器运行时已升级到 containerd 2.0。这可能产生以下影响：

  • containerd 2.0 不支持旧版 Docker Image Manifest v2 或 Schema 1 映像。在升级到 1.34 之前，请确保工作负载使用 Docker Schema 2 或符合 OCI 的格式拉取容器映像。
  • 在 containerd 2.0 中，注册表镜像配置已迁移到 hosts.toml 格式。如果您直接在节点上管理自定义镜像配置或经过网闸隔离的注册表端点，请验证您的配置是否与 hosts.toml 一致。
  • 如果您使用自定义 DaemonSet 或脚本来修补 /etc/containerd/config.toml，请确保它们不使用已弃用的 containerd v1 配置选项，否则可能会导致 containerd 2.0 启动失败。

• nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate 字段的默认值在 1.34.300 版中发生了变化。如果您希望在 1.34.300 及更高版本中依序升级节点池，请在用户集群配置文件中设置 nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate: 1：

  • 对于 1.34.0-1.34.200 版，nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate 默认为 1，即按顺序逐个更新节点池。
  • 对于 1.34.300 及更高版本，nodePoolUpdatePolicy.maximumConcurrentNodePoolUpdate 默认为 0，这会同时更新所有节点池。

  如需了解详情，请参阅配置节点池更新政策。

• 升级预检检查会主动验证整个集群中的所有 PodDisruptionBudget (PDB) 配置。在升级之前，请验证您的工作负载是否没有过于严格的 PDB（例如，maxUnavailable: 0 或 minAvailable 匹配总副本数），这些 PDB 会阻止节点排空或导致预检失败。

• 如果升级中断，请直接升级到 1.34.300-gke.59 版或更高版本。此版本可防止在发生故障后需要重新运行 gkectl upgrade admin 时删除引导集群。如需了解详情，请参阅重新运行 gkectl upgrade admin 会删除引导集群。

• 对于高级集群，您可以使用 gkectl upgrade admin --async 异步运行管理员集群升级，但从非高级集群转换为高级集群时除外。

版本 1.33

首先升级：管理员集群

版本偏差规则：

• 版本为 1.33 的管理员集群可以管理版本为 1.33、1.32 和 1.31 的用户集群。
• 用户集群控制平面版本：1.33、1.32 或 1.31。

• 工作器节点池版本：1.33、1.32 或 1.31。

  注意：将非高级集群转换为高级集群时，不允许存在版本偏差。您必须同时升级控制平面和所有节点池。

高级集群状态：高级集群是默认集群类型，会自动转换。允许选择退出。如需了解详情，请参阅升级和维护非高级集群。如果您将 enableAdvancedCluster 设置为 false，则新集群创建会失败。

跳过节点升级：支持。

是否支持旧版功能：否。会阻止升级。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：不支持。Blocks 升级。

升级工具：

• gkectl：将非高级集群转换为高级集群时需要（gkectl 二进制文件版本必须与目标发布版本完全匹配）。管理员集群必须提供此字段。支持的版本为 1.33、1.34 和 1.35。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持此方法。
• 控制台：支持高级用户集群升级。
• gcloud CLI：支持高级用户集群升级。

其他要求：

升级到 1.33 版还需满足以下额外要求：

• 从 1.32 升级到 1.33 时，默认情况下，非高级集群会自动转换为高级集群。您可以让集群保持非高级状态。如需详细了解如何使集群保持非高级状态，请参阅升级和维护非高级集群。

• 高级集群会自动安装并捆绑 cert-manager v1.18，从而覆盖预先存在的自定义 cert-manager 安装。如需详细了解如何升级到绑定的 cert-manager，请参阅使用绑定的 cert-manager。

• 如果您在此版本中升级到高级集群，则在从非高级集群转换为高级集群时，gkectl 二进制文件版本必须与目标发布版本完全一致。此要求仅在升级到高级集群期间适用。对于高级集群的所有其他升级，标准版本偏差规则均适用。

• 如果升级中断，请直接升级到 1.33.700-gke.71 或更高版本。此版本可防止在失败后需要重新运行 gkectl upgrade admin 时删除引导集群。

• 如果所有用户集群都运行 Controlplane V2，则您可以使用 gkectl upgrade admin --async 异步运行管理员集群升级，以升级高级集群和非高级高可用性集群。从非高级集群转换为高级集群时，您无法使用 --async 标志。

版本 1.32

首先升级：管理员集群

版本偏差规则：

• 1.32 版管理员集群可以管理 1.32、1.31 和 1.30 版用户集群。
• 用户集群控制平面版本：1.32、1.31 或 1.30。

• 工作器节点池版本：1.32、1.31 或 1.30。

  注意：将非高级集群转换为高级集群时，不允许存在版本偏差。您必须同时升级控制平面和所有节点池。

高级集群状态：受支持。

跳过节点升级：支持。

是否支持旧版功能：否。会阻止升级。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：不支持。Blocks 升级。必须迁移到 Controlplane V2。

升级工具：

• gkectl：将非高级集群转换为高级集群时需要（gkectl 二进制文件版本必须与目标发布版本完全匹配）。管理员集群必须提供此字段。支持的版本为 1.32、1.33 和 1.34。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持此方法。
• 控制台：支持高级用户集群升级。
• gcloud CLI：支持高级用户集群升级。

其他要求：

升级到 1.32 版时，还需满足以下额外要求：

• 这是第一个允许选择升级到完全受支持的GA高级集群的版本。您可以选择：

  • 升级到非高级集群并维护非高级集群。如果您选择此选项，则从该版本开始，您可以执行以下操作：

    • 分别升级用户集群的控制平面和工作器节点池。工作器节点池最多可以比控制平面低 2 个次要版本。
    • 为管理员集群和用户集群异步运行升级。

  • 升级到非高级集群，然后将非高级集群转换为高级集群。 如果您选择此选项，则从该版本开始，您可以执行以下操作：

    • 在升级非高级集群时，请分别升级用户集群的控制平面和工作器节点池，但在转换为高级集群时，请勿这样做。工作器节点池最多可以比控制平面低 2 个次要版本。
    • 升级非高级集群时，为管理员集群和用户集群异步运行升级。
    • 转换为高级集群时，请升级到 1.32.1000-gke.57 或更高版本，因为该版本包含针对已知问题的修复，该问题会导致引导集群无法删除。

  • 直接升级到高级集群。如果您选择此选项，则从本版本开始，以下内容适用：

    • 您必须同时升级控制平面和所有节点池。
    • 您可以为用户集群（而非管理员集群）异步运行升级。
    • 升级到 1.32.1000-gke.57 发布版本或更高版本，因为该版本包含针对已知问题的修复，该问题会导致引导集群无法删除。

• 从该版本开始，以下旧版功能不再受支持。 如需了解详情，请参阅旧版功能：

  • Dataplane V1 (Calico)。在升级到 1.32 之前，请先升级到 Dataplane V2。
  • Seesaw。在升级到 1.32 之前，请先升级到替代负载均衡器。
  • 集成式 F5 BIG-IP。在升级到 1.32 之前，请升级到替代负载均衡器。
  • Kubeception。在升级到 1.32 版之前，请先升级到非 Kubeception 集群。
  • 非高可用性管理员集群。在升级到 1.32 版之前，请先升级到高可用性管理员集群。

• 从非高级集群转换为高级集群时，gkectl 二进制文件版本必须与目标发布版本完全匹配。此要求仅在升级到高级集群期间适用。对于高级集群的所有其他升级，标准版本偏差规则均适用。

• 如果升级中断，请直接升级到 1.32.1000-gke.57 版或更高版本。此版本可防止在失败后需要重新运行 gkectl upgrade admin 时删除引导集群。

• 在 1.32 及更高版本中，如果所有用户集群都运行 Controlplane V2，则您可以使用 gkectl upgrade admin --async 异步运行高级集群和非高级高可用性集群的管理员集群升级。从非高级集群转换为高级集群时，您无法使用 --async 标志。

版本 1.31

首先升级：管理员集群

版本偏差规则：

• 1.31 版管理员集群可以管理 1.31、1.30 和 1.29 版用户集群。
• 用户集群控制平面版本：1.31、1.30 或 1.29。
• 工作器节点池版本：1.31、1.30 或 1.29。（1.31 高级集群不支持）。
• 如需从 1.29/1.30 升级到 1.31，您必须先将所有集群升级到 1.30 版，然后再将管理员集群升级到 1.31。

高级集群状态：仅限预览版。无法升级到更高版本。

跳过节点升级：支持。

支持的旧版功能：Dataplane V2 强制性；Kubeception、Seesaw 和 F5 仍受支持。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：管理员节点随管理员集群一起升级；用户控制平面节点随用户集群一起升级。

升级工具：

• gkectl：管理员集群、非高级集群和高级集群（预览版，适用于此版本）必需。支持的版本为 1.31、1.32 和 1.33。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持已注册的用户集群。
• 控制台：支持已注册的用户集群升级。
• gcloud CLI：支持已注册的用户集群升级。

其他要求：

升级到 1.31 版时，还需满足以下额外要求：

• 此版本引入了预览模式下的高级集群。在此版本中，您无法将非高级集群迁移到高级集群。您可以将新集群创建为高级集群，但无法将这些预览版高级集群升级到更高版本。我们不建议在此版本中创建高级集群。如需详细了解产品发布阶段（例如预览版），请参阅产品发布阶段。

• 在 1.31 及更高版本中，升级架构已更改为管理员集群现在必须高于或等于其用户集群的模型。以前，用户集群最多可以比管理员集群高两个次要版本。

• 您必须先升级管理员集群，然后再升级由管理员集群管理的用户集群。管理员集群可以管理具有相同次要版本或最多低 2 个次要版本的用户集群。例如，1.31 版管理员集群可以管理 1.31 版、1.30 版和 1.29 版用户集群。

• 如需从 1.29 升级到 1.31，您必须将 1.30 软件包作为中间步骤进行暂存。您必须在管理员工作站上下载 1.30 和 1.31 软件包，才能升级到 1.31。如需执行从 1.29 到 1.31 的跳过版本升级，请执行以下操作：

  1. 仅将用户集群控制平面从 1.29 升级到 1.30（将工作器节点池保留在 1.29）。
  2. 将管理员集群从 1.29 升级到 1.30。
  3. 将管理员集群从 1.30 升级到目标版本 1.31。
  4. 将用户集群控制平面和工作器节点池一起升级到 1.31。

• 如果您使用 Kubeception，则管理员集群节点会在管理员集群升级期间升级，用户集群控制平面节点会在用户集群升级期间升级。

• 如需升级到 1.31，您必须启用 Dataplane V2。为防止在 CNI 迁移期间发生网络政策冲突和流量丢弃，您必须手动保存并删除所有 NetworkPolicy 对象，并在升级后恢复这些对象。如需改用 Dataplane V2，请执行以下操作：

  1. 导出并保存所有自定义网络政策：

     kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
         get networkpolicy -A -o wide \
         --field-selector metadata.namespace!=kube-system
     kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
         get networkpolicy POLICY_NAME \
         -n NAMESPACE -o yaml > policy.yaml
     

     替换以下内容：

     • USER_CLUSTER_KUBECONFIG：用户集群的 kubeconfig 文件的路径
     • POLICY_NAME：NetworkPolicy 对象的名称
     • NAMESPACE：NetworkPolicy 对象的命名空间

  2. 从集群中删除网络政策：

     kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
         delete networkpolicy POLICY_NAME \
         -n NAMESPACE
     

  3. 在用户集群配置文件中设置 enableDataplaneV2: true，然后执行升级到 1.31。

  4. 在 1.31 升级完成后应用已保存的政策，以便 Cilium 将其干净地编译为扩展 Berkeley 数据包过滤器 (eBPF)：

     kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
         apply -f policy.yaml
     

• 如果您有高可用性管理员集群，并且所有用户集群都运行 Controlplane V2，则可以使用 gkectl upgrade admin --async 命令异步运行升级。

• 所有用户集群都必须使用 Dataplane V2。在将用户集群升级到 1.31 版之前，请按照启用 Dataplane V2 中的步骤操作。

• 1.32 版不支持旧版功能，您可以在 1.30 版和 1.31 版中替换这些功能，以防止在升级到 1.32 版时出现问题。

版本 1.30

首先升级：用户集群

版本偏差规则：

• 版本为 1.30 的用户集群可由版本为 1.30、1.29 或 1.28 的管理员集群管理。
• 1.30 版管理员集群只能管理 1.30 版用户集群。所有用户集群和管理员集群都必须达到 1.30 版，然后您才能将管理员集群升级到 1.31 版，并且您必须先将管理员集群升级到 1.31 版，然后任何用户集群才能升级到 1.31 版。
• 用户集群控制平面版本：1.30。
• 工作器节点池版本：1.30、1.29 或 1.28。

高级集群状态：不可用。

跳过节点升级：支持。

支持旧版功能：支持。强烈建议迁移到推荐功能。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

• Kubeception 节点升级行为：控制平面和管理员节点在管理员集群升级期间升级

升级工具：

• gkectl：管理员集群必需。支持的版本为 1.30、1.31 和 1.32。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持已注册的用户集群。
• 控制台：支持已注册的用户集群升级。
• gcloud CLI：支持已注册的用户集群升级。

其他要求：

升级到 1.30 版还需满足以下额外要求：

• 对于此版本和所有先前版本，您必须先迁移所有用户集群，然后才能升级管理管理员集群。管理员集群必须与任何受管理的用户集群处于相同或更低的次要版本。

• 如果您使用 Kubeception，则在升级期间会发生以下情况：

  1. 升级用户集群。由于用户控制平面位于管理员集群内，因此运行 gkectl upgrade cluster 只会升级工作器节点池。
  2. 升级管理员集群。管理员集群升级会升级管理员节点，并同时自动升级所有用户集群控制平面。

• 如果您使用的是 Controlplane V2，则升级期间会发生以下情况：

  1. 升级用户集群。这会升级控制平面和工作器节点池。
  2. 升级管理员集群。这会升级管理员节点。

• 从该版本开始，创建新的用户集群时，您必须将 enableControlplaneV2 字段设置为 true（默认值）。如果您将 enableControlplaneV2 字段设置为 false，gkectl 会拒绝该文件，并且不会创建集群。

• 如果您有高可用性管理员集群，并且所有用户集群都运行 Controlplane V2，则可以使用 gkectl upgrade admin --async 命令异步运行升级。

• 1.32 版不支持旧版功能，您可以在 1.30 版和 1.31 版中替换这些功能，以防止在升级到 1.32 版时出现问题。

版本 1.29

首先升级：用户集群

版本偏差规则：

• 1.29 版用户集群可由 1.29、1.28 或 1.16 版管理员集群管理。
• 1.29 版管理员集群可以管理 1.29 版和 1.30 版用户集群。1.29 版的管理员集群无法管理 1.31 版的用户集群，因为所有集群都必须先达到 1.30 版，并且管理员集群必须升级到 1.31 版，然后任何用户集群才能升级到 1.31 版。
• 用户集群控制平面版本：1.29 或 1.30，最多高 1 个次要版本。
• 工作器节点池版本：1.29、1.28 或 1.16。

高级集群状态：不可用。

跳过节点升级：支持。

支持的旧版功能：支持。

默认和必需的操作系统映像：ubuntu_cgv2、cos_cgv2、ubuntu_containerd、cos。默认 osImageType 为 ubuntu_cgv2。

Kubeception 节点升级行为：控制平面和管理员节点在管理员集群升级期间升级

升级工具：

• gkectl：管理员集群必需。支持的版本为 1.29、1.30 和 1.31。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持已注册的用户集群。
• 控制台：支持已注册的用户集群升级。
• gcloud CLI：支持已注册的用户集群升级。

其他要求：

升级到 1.29 版还需满足以下额外要求：

• 工作器节点最多可以比控制平面低 2 个次要版本 (n+2)。
• 升级工作器节点池时，您可以跳过某个次要版本。例如，您可以将工作器节点池从 1.28 升级到 1.30。
• 预检检查在管理员集群或临时引导 kind 集群内作为 Pod 运行，而不是在管理员工作站上运行。
• 从该版本开始，您可以使用 gkectl upgrade cluster --dry-run 运行预检检查，而无需升级集群。
• 如果您有高可用性管理员集群，并且所有用户集群都运行 Controlplane V2，则可以使用 gkectl upgrade admin --async 命令异步运行升级。

版本 1.28

首先升级：用户集群

版本偏差规则：

• 1.28 版用户集群可由 1.28、1.16 或 1.15 版管理员集群管理。
• 1.28 版管理员集群可以管理 1.28、1.29 和 1.30 版用户集群。
• 用户集群控制平面版本：1.28、1.29 或 1.30，最多高 2 个次要版本。
• 工作器节点池版本：1.28、1.16 或 1.15，最多低 2 个次要版本。

高级集群状态：不可用。

跳过节点升级：支持。

支持的旧版功能：支持。

默认和必需的操作系统映像：ubuntu_containerd、cos、ubuntu_cgv2、cos_cgv2。默认 osImageType 为 ubuntu_containerd。

Kubeception 节点升级行为：控制平面和管理员节点在管理员集群升级期间升级

升级工具：

• gkectl：管理员集群必需。支持的版本为 1.28、1.29 和 1.30。
• Terraform：如果您使用 Terraform 创建了用户集群，则支持已注册的用户集群。
• 控制台：支持已注册的用户集群升级。
• gcloud CLI：支持已注册的用户集群升级。

其他要求：

升级到 1.28 版时，还需满足以下额外要求：

• 您必须启用 kubernetesmetadata.googleapis.com 并向日志记录监控服务账号授予 roles/kubernetesmetadata.publisher。否则，预检检查可能会失败，或者您可能会看到 403 PERMISSION_DENIED 错误。启用该 API 并向现有日志记录和监控服务账号授予该角色：

  gcloud services enable kubernetesmetadata.googleapis.com
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member="serviceAccount:LOGGING_SA" \
      --role="roles/kubernetesmetadata.publisher"
  

  替换以下内容：

  • PROJECT_ID：用户集群所属的舰队宿主项目的 ID。
  • LOGGING_SA：日志记录监控服务账号的电子邮件地址。

• 尽管在技术上可以在节点池升级期间跳过版本，但此功能是作为预览版功能引入的，不建议用于此版本。如需详细了解产品发布阶段（例如预览版），请参阅产品发布阶段。

• 具有捆绑式负载均衡器的节点池必须与集群版本完全匹配。

• 您可以通过设置 nodePools[i].updateStrategy.rollingUpdate.maxSurge 字段同时升级多个节点。您的 vSphere 集群必须有足够的 CPU、RAM 和可用 IP 地址，才能在升级期间容纳额外的激增虚拟机：

  • 设置为 maxSurge: 1（默认）可一次升级一个节点（排空、替换、验证，然后重复）。
  • 设置 maxSurge: N（其中 N > 1），以同时预配和排空最多 N 个工作器节点（例如，maxSurge: 3 会同时升级 3 个工作器节点）。

• 管理员工作站上必须至少有 100 GB 的磁盘可用空间，才能升级管理员工作站。

• 您用于升级的 gkectl 版本最多可以比当前集群高两个次要版本。您无法使用较低的次要版本。

1.28 之前的版本

以下额外要求适用于升级到 1.28 版之前的版本。1.16 到 1.28 之间没有发布版本：

版本 1.16：

• 管理员集群与用户集群之间以及控制平面与节点池之间的版本偏差只能相差 1 个次要版本。例如，版本为 1.15 的管理员集群只能管理版本为 1.15 或 1.16 的用户集群。升级到 1.16 的用户集群控制平面可以管理运行 1.15 或 1.16 版的工作器节点池。1.14 版的池必须升级到 1.15 版，然后控制平面才能升级到 1.16 版。如需详细了解版本偏差，请参阅版本偏差规则。
• 集群在创建或升级到 1.16 版时会自动在 GKE On-Prem API 中注册。通过此更改，您可以使用控制台、gcloud CLI 和 Terraform（而不仅仅是管理员工作站 shell）查看、监控和升级用户集群。

版本 1.14：

• 您可以先仅升级用户集群控制平面，这样就不必同时排空和升级每个工作器节点池。
• 在升级期间，系统会自动检查并更新工作站上的现有管理员和用户集群 kubeconfig 文件，从而自动续订凭据。

版本 1.13：

• 在此版本之前，您可以拥有离线管理员集群。此版本要求您将管理员集群注册到 Google Cloud。如需了解如何注册集群，请参阅注册现有集群。
• 如需将集群升级到 Google Distributed Cloud 软件（仅限 VMware 1.13 版或更高版本），您必须先将仍使用 Docker Engine 的所有用户集群节点池更新为 containerd。

使用捆绑的 cert-manager

您必须使用捆绑的 cert-manager，它会自动安装在高级集群上。从非高级集群迁移到高级集群时，集成的 cert-manager 会自动覆盖客户安装的所有 cert-manager 版本。在更新或升级到高级集群之前，请确保您没有对现有 cert-manager 应用关键自定义配置或功能。

如需查看您是否对 cert-manager 应用了关键自定义配置或功能，请执行以下操作：

• 暂停持续部署工具。如果您使用 GitOps 工具（例如 Config Sync、ArgoCD 或 Flux）管理 cert-manager，请在升级前暂停同步或从代码库中移除 cert-manager 清单。如果 GitOps 控制器在集群升级运行期间尝试将 cert-manager 协调回旧版本或自定义清单，则会创建一个协调循环，这可能会导致集群升级停滞。
• 升级前，请勿手动卸载或删除 cert-manager pod、命名空间或 CRD。gkectl 会就地管理这些升级。
• 如果您修改了 cert-manager 部署标志、节点选择器或 Pod 资源限制，请将其还原。高级集群不支持 cert-manager 上的自定义二进制参数或部署级替换。
• 如果您使用专用外部颁发者、专用 ACME DNS-01 网络钩子插件或自定义网络钩子，请验证您的第三方插件是否与您要升级到的版本的捆绑 cert-manager 版本兼容。

如需了解详情，请参阅升级到与高级集群捆绑的 cert-manager。

下表列出了哪些发布版本需要捆绑 cert-manager：

版本	新集群的状态	现有集群升级的状态	是否需要捆绑 cert-manager？
1.34+	必填	强制转换（捆绑了 v1.19）	所有客户都必须遵守。非高级集群无法再存在。
1.33	标准/所有新集群的默认设置	默认自动转换为高级集群（捆绑了 v1.18）	几乎所有集群都需要此功能，除非明确使用 enableAdvancedCluster: false 选择停用（仅限 1.32 → 1.33）。
1.32（正式版）	默认处于启用状态	可选择转换为高级集群	如果启用了高级集群，则此字段为必填字段。
1.31（预览版）	可选 (enableAdvancedCluster: true)	不支持	如果启用了高级集群，则此字段为必填字段。

如需查看每个受支持版本中捆绑的 cert-manager 版本，请参阅捆绑的 cert-manager 版本。

控制平面 V2

启用 Controlplane V2 后，用户集群的控制平面在用户集群本身的节点上运行。对于 Controlplane V2，用户集群控制平面节点在用户集群升级期间升级，管理员集群控制平面节点在管理员集群升级期间升级。

旧版功能

下表列出了在 1.32 及更高版本中被屏蔽的旧版功能。如果您使用这些功能，则必须先迁移到推荐的替代方案，然后才能升级到 1.32 或更高版本。

| 旧版功能（在 1.32 中被屏蔽） | 替换为（推荐） | 迁移说明链接 | | --- | --- | --- | | Dataplane V1 (Calico) | Dataplane V2 (Cilium / eBPF) | 迁移到 Dataplane V2| | Kubeception | Controlplane V2 | 迁移到 Controlplane V2 | | 非高可用性管理员集群（1 个副本） | 高可用性管理员集群（3 个副本） | 迁移到高可用性管理员集群 | | Seesaw 负载均衡器 | MetalLB 或 ManualLB | 迁移到 MetalLB 或迁移负载均衡器类型| | 集成式 F5 BIG-IP (loadBalancer.kind: "F5BigIP") | ManualLB（与 F5 Big-IP Controller 或 CCGI 配对） | 迁移到 ManualLB |

如需详细了解如何从旧版功能迁移到推荐功能，请参阅规划将集群迁移到推荐功能。

Kubeception 迁移和版本行为

Kubeception 是一项旧版功能，必须先迁移到 Controlplane V2，然后才能升级到 1.32 版或更高版本。

对于具有 Kubeception 的集群，升级行为因版本而异：

• 对于 1.28：控制平面和管理员节点在管理员集群升级期间升级
• 对于 1.29：控制平面和管理员节点在管理员集群升级期间升级

• 对于 1.30：控制平面和管理员节点会在管理员集群升级期间升级。如果您使用 Kubeception，则在升级期间会发生以下情况：

  1. 升级用户集群。由于用户控制平面位于管理员集群内，因此运行 gkectl upgrade cluster 只会升级工作器节点池。
  2. 升级管理员集群。管理员集群升级会升级管理员节点，并同时自动升级所有用户集群控制平面。

• 对于 1.31：管理员节点随管理员集群一起升级；用户控制平面节点随用户集群一起升级。

• 对于 1.32 及更高版本：不支持 Kubeception。您必须先迁移到 Controlplane V2，然后才能升级到 1.32 或更高版本。

  如需详细了解如何将 Kubeception 迁移到 Controlplane V2，请参阅规划将集群迁移到推荐功能。

版本偏差与升级期间跳过某个版本

版本偏差是管理员集群与其管理的用户集群之间允许的次要版本差异，或用户集群的控制平面与用户集群中的节点池之间的次要版本差异。

版本偏差不同于升级时跳过次要版本。

只有在升级控制平面后，您才能在升级工作器节点池时跳过次要版本。这适用于高级和非高级集群，但运行 1.31 版和 1.28 版之前版本的高级集群除外。例如，如果工作器节点池的版本为 1.29，请将用户集群控制平面更新到 1.30，然后再更新到 1.31。控制平面升级到 1.31 后，将工作器节点池直接从 1.29 升级到 1.31，而无需升级到 1.30。如需了解详情，请参阅升级节点池时跳过某个版本。

如需升级到比下一个依序次要版本更高的次要版本，请先升级到下一个次要版本，然后再升级到更高的次要版本。升级管理员和用户集群控制平面时，您无法跳过次要版本。例如，如果您要从 1.34.x 版升级到 1.36.x 版，则无法直接升级。您必须先从 1.34.x 升级到 1.35.x，然后再升级到 1.36.x。

用户集群的控制平面最多可以比集群中的工作器节点池高 2 个次要版本。例如，如果用户集群的控制平面的版本为 1.36，则集群中的工作器节点池的版本可以为 1.34、1.35 或 1.36。

允许哪些版本偏差？

管理员集群最多可以管理低 2 个次要版本的用户集群。例如，如果管理员集群的版本为 1.31，则管理员集群管理的用户集群的版本可以为 1.29、1.30 或 1.31。

在 1.31 版之前，适用以下版本偏差规则：

• 对于 1.28 至 1.30 版，用户集群最多可以比管理员集群高 2 个次要版本。例如，如果管理员集群的版本为 1.15，则管理员集群管理的用户集群的版本可以为 1.15、1.16 或 1.28。在管理员集群升级到至少 1.16 之前，您无法将 1.28 版用户集群升级到 1.29 版。由于 1.31 版更改了升级顺序，要求先升级管理员集群，因此 1.29 或 1.30 版的管理员集群无法管理 1.31 或 1.32 版的用户集群。所有用户集群和管理员集群都必须达到 1.30 版，然后您才能将管理员集群升级到 1.31 版。
• 对于 1.16 及更低版本，用户集群只能比管理员集群高 1 个次要版本。例如，如果管理员集群的版本为 1.15，则管理员集群管理的用户集群的版本可以为 1.15 或 1.16。

我是否必须一次性升级所有用户集群？

升级用户集群时，您可以选择以下任一方法：

• 同时升级整个用户集群，包括控制平面和集群中的所有节点池。
• 升级用户集群的控制平面，并将节点池保留为当前版本。
• 升级用户集群的控制平面，并选择性地升级节点池。

您采用哪种方法取决于多种因素，例如：

• 集群所在的环境（生产环境或非生产环境）。
• 维护窗口的长度。
• 用户集群的版本。

例如，您可能希望在开发环境中同时升级用户集群的控制平面和所有节点池。但在维护窗口较短的生产环境中，您可能希望仅升级控制平面，因为这样可以节省时间，并且控制平面升级不应中断用户工作负载。

负载均衡器节点池（具有 enableLoadBalancer: true 的节点池）的版本必须与集群的版本相同。

gkectl 的版本规则

您可以用于升级的 gkectl 版本取决于目标集群版本（即您要升级到的集群版本）。通常，您使用的 gkectl 版本应与集群目标版本相同。在升级期间，系统会强制执行以下规则：

• gkectl 版本必须与目标集群的次要版本相同或更高。例如，如果您要将 1.29 集群升级到 1.30，则必须使用 gkectl 1.30 或更高版本。补丁版本无关紧要。

• gkectl 版本最多可以比当前集群版本高两个次要版本。例如，如需将 1.28 集群升级到 1.29，请使用 gkectl 1.29 版或 1.30 版，但不能使用 1.31 版，因为它比集群版本高三个次要版本。

从非高级集群转换为高级集群时，gkectl 二进制文件版本必须与目标发布版本完全匹配。此严格的版本要求仅在升级到高级集群期间适用。对于所有其他高级集群升级，标准版本偏差规则适用。

补丁版本升级规则

建议您尽可能升级到最新的补丁版本，以确保您的集群拥有最新的安全修复。补丁版本不会影响版本偏差和升级规则。对于给定的次要版本，您可以升级到任何更高的补丁版本。例如，您可以从 1.35.0 升级到 1.35.1，也可以从 1.35.1 升级到 1.35.3。

后续步骤

• 查看升级最佳实践，并制定升级集群的计划。

• 创建启用了高级集群的集群：

  • 创建管理员集群
  • 创建用户集群
  • 将集群更新或升级为高级集群