升级集群

安装新版 bmctl 时，您可以升级使用较早版本创建的现有集群。将集群升级到最新的 Google Distributed Cloud 版本可为集群新增功能和修复，还可确保您的集群保持受支持状态。您可以使用 bmctl upgrade cluster 命令升级管理员集群、独立集群或用户集群，也可以使用 kubectl 来执行这些操作。

如需详细了解升级流程和版本控制规则，请参阅集群升级的生命周期和阶段。

本页面适用于管理底层技术基础设施生命周期的管理员、架构师和运维人员。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

规划升级

本部分包含升级集群之前应考虑内容的信息和链接。 如需详细了解升级（包括集群和节点池的版本控制规则），请参阅集群升级的生命周期和阶段。

最佳实践

如需了解如何为集群升级做好准备，请参阅 Google Distributed Cloud 集群升级最佳实践。

升级预检检查

预检检查在集群升级的过程中运行，以验证集群状态和节点运行状况。如果预检检查失败，则不会继续集群升级。 如需详细了解预检检查，请参阅了解预检检查。

您可以通过在运行升级之前运行预检检查来检查集群是否已准备好进行升级。如需了解详情，请参阅针对升级进行预检检查。

已知问题

如需了解与集群升级相关的潜在问题，请参阅 Google Distributed Cloud for Bare Metal 已知问题，并选择升级和更新问题类别。

配置升级选项

在开始集群升级之前，您可以配置以下升级选项来控制升级过程的工作原理：

• 选择性工作器节点池升级：独立于集群的其余部分升级特定工作器节点池。

• 并行升级：配置升级过程以同时升级节点组或节点池。

这些选项可以降低关键应用和服务中断的风险，并显著缩短整体升级时间。这些选项对于具有大量节点和运行重要工作负载的节点池的大型集群特别有用。如需详细了解这些选项的用途以及如何使用它们，请参阅以下部分。

选择性工作器节点池升级

默认情况下，集群升级操作会升级集群中的每个节点和节点池。集群升级可能会中断且非常耗时，因为这会导致每个节点排空，并且会重启并重新安排所有关联的 Pod。本部分介绍如何为集群升级添加或排除选定的工作器节点池，以最大限度地减少工作负载中断。此功能仅适用于用户集群、混合集群和独立集群，因为管理员集群不支持工作器节点池。

在以下情况下，您可以使用选择性节点池升级：

• 如需在不中断工作负载的情况下获取安全修复程序：您可以仅升级控制平面节点（和负载均衡器节点）以应用 Kubernetes 漏洞修复，而不中断工作器节点池。

• 如需在升级所有工作器节点之前确认升级的工作器节点子集正常运行，请执行以下操作：您可以先选择性地升级工作器节点池，以确保在升级另一个节点池之前，工作负载已在升级后的节点池上正常运行。

• 缩短维护窗口：升级大型集群可能非常耗时，并且很难准确预测升级何时完成。集群升级时间与要升级的节点数量成正比。通过排除节点池减少升级的节点数，从而缩短升级时间。您可以多次升级，但较小且可预测的维护窗口可能有助于安排调度。

两个次要版本节点池版本偏差

对于 1.28 版及更高版本的集群，工作器节点池版本最多可比集群（控制平面）版本低两个次要版本。由于 n-2 版本偏差支持，在将低于集群两个次要版本的工作器节点池升级到与集群相同的次要版本时，您还可以跳过一个次要发布版本。

对工作器节点池的此 n-2 版本偏差支持可让您更灵活地规划舰队升级。n-2

例如，如果您有 1.30 版集群，则可以使用 1.30、1.29 和 1.28 版本的工作器节点池。

在升级集群之前，所有工作器节点池的版本必须与当前集群版本和目标集群版本兼容。

例如，如果您有一个 1.29 版集群和 1.29 版、1.28 版和 1.16 版工作器节点池，则必须先将 1.16 版节点池升级到 1.28 版或 1.29 版，然后才能将集群升级到 1.30 版。

如需了解详情（包括给定集群版本支持的工作器节点池版本列表，适用于 1.29 版及更早版本），请参阅节点池版本控制规则

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  annotations:
    preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable
spec:
  type: hybrid
  profile: default
  anthosBareMetalVersion: 1.28.400-gke.77
  ...

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: baremetal-demo
  namespace: cluster-baremetal-demo
  annotations:
    preview.baremetal.cluster.gke.io/two-minor-version-node-pool: enable
spec:
...

如需详细了解选择性升级工作器节点池的版本控制规则，请参阅集群升级生命周期和阶段中的节点池版本控制规则。

升级集群控制平面和所选节点池

如需在初始集群升级时选择性地升级工作器节点池，请执行以下操作：

1. 对于要包含在集群升级中的工作器节点池，请对 NodePool 规范进行以下更改之一：

   • 将 NodePool 规范中的 anthosBareMetalVersion 设置为集群目标升级版本。
   • 在 NodePool 规范中省略 anthosBareMetalVersion 字段。或者将其设置为空字符串。默认情况下，工作器节点池包含在集群升级中。

2. 对于要从升级中排除的工作器节点池，请将 anthosBareMetalVersion 设置为集群的当前（升级前）版本：

3. 按照开始升级集群中的说明继续升级。

   集群升级操作会升级以下节点：

   • 集群控制平面节点。
   • 负载均衡器节点池（如果集群使用一个 [spec.loadBalancer.nodePoolSpec]）。默认情况下，负载均衡器节点可以运行常规工作负载。您无法选择性地升级负载均衡器节点池，它始终包含在初始集群升级中。
   • 您尚未从升级中排除的工作器节点池。

例如，假设您的集群是 1.29.0 版且具有两个工作器节点池：wpool01 和 wpool02。此外，假设您要将控制平面和 wpool01 升级到 1.30.100-gke.96，但希望 wpool02 保持为 1.29.0 版。

以下集群配置文件摘录展示了如何修改集群配置以支持这种部分升级：

...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user001
  namespace: cluster-user001
spec:
  type: user
  profile: default
  anthosBareMetalVersion: 1.30.100-gke.96
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.30.100-gke.96
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
  - address:  10.200.0.8

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool02
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.29.0
  nodes:
  - address:  10.200.1.1
  - address:  10.200.1.2
  - address:  10.200.1.3
  ...
  - address:  10.200.1.12

将节点池升级到当前集群版本

如果您已在集群升级中排除节点池，则可以运行集群升级，使它们升级到目标集群版本。已在集群升级中排除的工作器节点池的 NodePool 规范将 anthosBareMetalVersion 字段设置为先前（升级前）的集群版本。

如需将工作器节点池升级到当前升级的集群版本，请执行以下操作：

1. 为要升级到当前集群版本的工作器节点池修改集群配置文件中的 NodePool 规范。将 anthosBareMetalVersion 设置为当前（升级后）的集群版本。

   如果选择多个工作器节点池进行升级，则集群规范中的 spec.nodePoolUpgradeStrategy.concurrentNodePools 值将确定并行升级的节点池数量（如有）。如果您不想同时升级工作器节点池，请一次选择一个节点池进行升级。

2. 按照开始升级集群中的说明继续升级。

   集群升级操作仅升级您之前将 anthosBareMetalVersion 设置为当前升级的集群版本的已排除的工作器节点池。

例如，假设您已将集群升级到 1.30.100-gke.96 版，但节点池 wpool02 仍为升级前的旧版本 1.29.0。工作负载在升级的节点池 wpool01 上正常运行，因此现在您还需要将 wpool02 升级为当前的集群版本。如需升级 wpool02，您可以移除 anthosBareMetalVersion 字段或将其值设置为空字符串。

以下集群配置文件摘录展示了如何修改集群配置以支持这种部分升级：

...
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user001
  namespace: cluster-user001
spec:
  type: user
  profile: default
  anthosBareMetalVersion: 1.30.100-gke.96
---
apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool01
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: 1.30.100-gke.96
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  ...
  - address:  10.200.0.8

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: wpool02
  namespace: cluster-user001
spec:
  clusterName: user001
  anthosBareMetalVersion: ""
  nodes:
  - address:  10.200.1.1
  - address:  10.200.1.2
  - address:  10.200.1.3
  ...
  - address:  10.200.1.12

回滚节点池升级

有许多依赖项（例如与 kubelet 或插件的兼容性）可能会影响工作负载的性能。如果在升级工作器节点池后遇到问题，可以将节点池回滚到先前版本。

此功能在所有受支持的集群版本中处于不同的发布阶段：

preview.baremetal.cluster.gke.io/worker-node-pool-upgrade-rollback: enable

如需回滚节点池升级，请按以下步骤操作：

并行升级

在典型的默认集群升级中，每个集群节点按顺序依次升级。本部分介绍如何配置集群和工作器节点池，以便在升级集群时并行升级多个节点。并行升级节点可以显著加快集群升级速度，尤其是对于具有数百个节点的集群。

有两种并行升级策略可用于加快集群升级：

• 并发节点升级：您可以配置工作器节点池，以便多个节点并行升级。节点的并行升级在 NodePool 规范 (spec.upgradeStrategy.parallelUpgrade) 中进行配置，并且只有工作器节点池中的节点可以并行升级。控制平面或负载均衡器节点池中的节点一次只能升级一个。如需了解详情，请参阅节点升级策略。

• 并发节点池升级：您可以配置集群，以便并行升级多个节点池。只有工作器节点池可以并行升级。控制平面和负载均衡器节点池一次只能升级一个。

节点升级策略

您可以配置工作器节点池，以便多个节点同时升级 (concurrentNodes)。您还可以为在整个升级过程中运行工作负载的节点数设置最小阈值 (minimumAvailableNodes)。此配置是在 NodePool 规范中进行的。如需详细了解这些字段，请参阅集群配置字段参考文档。

节点升级策略仅适用于工作器节点池。您无法为控制平面或负载均衡器节点池指定节点升级策略。在集群升级期间，控制平面和负载均衡器节点池中的节点会逐个升级。控制平面节点池和负载均衡器节点池在集群规范（controlPlane.nodePoolSpec.nodes 和 loadBalancer.nodePoolSpec.nodes）中指定。

为节点配置并行升级时，请注意以下限制：

• concurrentNodes 的值不能超过节点池中节点数的 50%，也不能超过固定数量 15（以较小者为准）。例如，如果您的节点池有 20 个节点，则不能指定大于 10 的值。如果您的节点池有 100 个节点，则 15 是您可以指定的最大值。

• 将 concurrentNodes 与 minimumAvailableNodes 结合使用时，组合值不能超过节点池中的节点总数。例如，如果您的节点池有 20 个节点，并且 minimumAvailableNodes 设置为 18，则 concurrentNodes 不能超过 2。同样，如果 concurrentNodes 设置为 10，则 minimumAvailableNodes 不能超过 10。

以下示例展示了包含 10 个节点的工作器节点池 np1。在升级中，一次升级 5 个节点，并且至少有 4 个节点必须继续可用，才能继续进行升级：

apiVersion: baremetal.cluster.gke.io/v1
kind: NodePool
metadata:
  name: np1
  namespace: cluster-cluster1
spec:
  clusterName: cluster1
  nodes:
  - address:  10.200.0.1
  - address:  10.200.0.2
  - address:  10.200.0.3
  - address:  10.200.0.4
  - address:  10.200.0.5
  - address:  10.200.0.6
  - address:  10.200.0.7
  - address:  10.200.0.8
  - address:  10.200.0.9
  - address:  10.200.0.10 
  upgradeStrategy:
    parallelUpgrade:
      concurrentNodes: 5
      minimumAvailableNodes: 4 

节点池升级策略

您可以配置集群，以便多个工作器节点池并行升级。集群规范中的 nodePoolUpgradeStrategy.concurrentNodePools 布尔值字段指定是否同时升级集群的所有工作器节点池。默认情况下 (1)，节点池会按顺序升级。如果将 concurrentNodePools 设置为 0，则同时升级集群中的每个工作器节点池。

控制平面和负载均衡节点池不受此设置的影响。这些节点池始终按顺序逐个升级。控制平面节点池和负载均衡器节点池在集群规范（controlPlane.nodePoolSpec.nodes 和 loadBalancer.nodePoolSpec.nodes）中指定。

apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: cluster1
  namespace: cluster-cluster1
spec:
  ...
  nodePoolUpgradeStrategy:
    concurrentNodePools: 0
  ...

如何执行并行升级

本部分介绍如何配置集群和工作器节点池以进行并行升级。

如需对工作器节点池和工作器节点池中的节点执行并行升级，请执行以下操作：

1. 将 upgradeStrategy 部分添加到 NodePool 规范。

   在执行集群更新时，您可以单独应用此清单，也可以将其作为集群配置文件的一部分应用。

   示例如下：

   ---
   apiVersion: baremetal.cluster.gke.io/v1
   kind: NodePool
   metadata:
     name: np1
     namespace: cluster-ci-bf8b9aa43c16c47
   spec:
     clusterName: ci-bf8b9aa43c16c47
     nodes:
     - address:  10.200.0.1
     - address:  10.200.0.2
     - address:  10.200.0.3
     ...
     - address:  10.200.0.30
     upgradeStrategy:
       parallelUpgrade:
         concurrentNodes: 5
         minimumAvailableNodes: 10
   

   在此示例中，字段 concurrentNodes 的值为 5，这意味着 5 个节点会并行升级。minimumAvailableNodes 字段设置为 10，这意味着至少有 10 个节点在升级过程中必须可用于工作负载。

2. 将 nodePoolUpgradeStrategy 部分添加到集群配置文件中的集群规范。

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: cluster-user001
   ---
   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: user001
     namespace: cluster-user001
   spec:
     type: user
     profile: default
     anthosBareMetalVersion: 1.30.100-gke.96
     ...
     nodePoolUpgradeStrategy:
       concurrentNodePools: 0
     ...
   

   在此示例中，concurrentNodePools 字段设置为 0，这意味着所有工作器节点池在集群升级期间并发升级。节点池中的节点升级策略在 NodePool 规范中定义。

3. 按照上文升级管理员集群、独立集群、混合集群或用户集群部分中的说明升级集群。

并行升级默认值

默认情况下，并行升级处于停用状态，并且与并行升级相关的字段是可变的。您可以随时移除这些字段或将其设置为默认值，以便在后续升级之前停用该功能。

下表列出了并行升级字段及其默认值：

开始升级集群

本部分包含升级集群的说明。

暂停和恢复升级

升级暂停和恢复功能可让您在集群升级完成之前暂停升级。暂停集群升级后，在升级恢复之前不会触发新的工作器节点升级。

此功能在所有控制平面节点均为次要版本 1.28 或更高版本的集群中作为预览版提供。对于所有控制平面节点均为次要版本 1.29 或更高版本的集群，此功能是正式版。

您可能出于以下原因需要暂停升级：

• 您在升级过程中检测到集群工作负载出现问题，希望暂停升级来调查问题

• 您的维护窗口很短，因此您希望在窗口之间暂停升级

在集群升级暂停期间，支持进行以下操作：

• 添加或移除节点
• 添加或移除节点池
• 扩大服务网络范围
• 使用备份恢复集群

如果在升级暂停时添加了新节点，在升级恢复并完成之前，机器检查作业不会在该节点上运行。

在集群升级暂停期间，不支持进行以下集群操作：

• 轮替证书授权机构
• 备份集群

活动的集群升级暂停时，您无法启动新的集群升级。

启用升级暂停和恢复功能

暂停升级

您可以通过在集群规范中将 nodePoolUpgradeStrategy.pause 设置为 true 来暂停集群升级。

如需暂停活动的集群升级，请按照以下步骤操作：

1. 向集群配置文件添加 nodePoolUpgradeStrategy.pause 并将其设置为 true：

   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: baremetal-demo
     namespace: cluster-baremetal-demo
     ...
   spec:
     ...
     nodePoolUpgradeStrategy:
       pause: true
     ...
   

   如果您使用 bmctl 启动升级，则需要新的终端窗口来执行下一步。

2. 如需应用更改，请更新您的集群：

   bmctl update CLUSTER_NAME
   

   升级操作已暂停。不会触发新的节点升级。

3. 如果您使用 bmctl 启动升级，并且计划长时间暂停，请按 Control+C 退出 bmctl，否则，请保持 bmctl 运行。

   bmctl CLI 不会检测升级暂停状态的变化，因此不会自动退出。但是，当您退出 bmctl 后，它会停止将升级进度记录到管理员工作站上集群文件夹中的 cluster-upgrade-TIMESTAMP 日志文件以及 Cloud Logging。因此，对于短时间暂停，建议您使 bmctl 保持运行状态。如果您在升级暂停时让 bmctl 长时间运行，它最终会超时。

恢复暂停的升级

如需恢复暂停的集群升级，您可以在集群规范中将 nodePoolUpgradeStrategy.pause 设置为 false，或从规范中移除 nodePoolUpgradeStrategy.pause。

如需恢复已暂停的集群升级，请按以下步骤操作：

1. 向集群配置文件添加 nodePoolUpgradeStrategy.pause 并将其设置为 false：

   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: baremetal-demo
     namespace: cluster-baremetal-demo
     ...
   spec:
     ...
     nodePoolUpgradeStrategy:
       pause: false
     ...
   

   或者，您也可以移除 pause 字段，因为它默认为 false。

2. 如需应用更改，请更新您的集群：

   bmctl update CLUSTER_NAME
   

   升级操作会从上次中断的位置恢复。

3. 如需检查升级的状态，请先获取 status 中包含 anthosBareMetalVersion 的资源的列表：

   kubectl get RESOURCE --kubeconfig ADMIN_KUBECONFIG --all_namespaces
   

   替换以下内容：

   • RESOURCE：您要获取的资源的名称。Cluster、NodePool 和 BareMetalMachine 资源均包含 anthosBareMetalVersion 状态信息。

   • ADMIN_KUBECONFIG：管理员集群 kubeconfig 文件的路径。

   以下示例展示了 BareMetalMachine 自定义资源的响应格式。每个 BareMetalMachine 对应一个集群节点。

   NAMESPACE              NAME         CLUSTER        READY   INSTANCEID               MACHINE      ABM VERSION   DESIRED ABM VERSION
   cluster-nuc-admin001   192.0.2.52   nuc-admin001   true    baremetal://192.0.2.52   192.0.2.52   1.28.0        1.28.0
   cluster-nuc-user001    192.0.2.53   nuc-user001    true    baremetal://192.0.2.53   192.0.2.53   1.16.2        1.16.2
   cluster-nuc-user001    192.0.2.54   nuc-user001    true    baremetal://192.0.2.54   192.0.2.54   1.16.2        1.16.2
   

4. 如需查看 status.anthosBareMetalVersion（资源的当前版本），请检索各个资源的详细信息：

   kubectl describe RESOURCE RESOURCE_NAME \
       --kubeconfig ADMIN_KUBECONFIG \
       --namespace CLUSTER_NAMESPACE
   

   以下示例展示了 IP 地址为 192.0.2.53 的集群节点的 BareMetalMachine 详细信息：

   Name:         192.0.2.53
   Namespace:    cluster-nuc-user001
   ...
   API Version:  infrastructure.baremetal.cluster.gke.io/v1
   Kind:         BareMetalMachine
   Metadata:
     Creation Timestamp:  2023-09-22T17:52:09Z
     ...
   Spec:
     Address:                    192.0.2.53
     Anthos Bare Metal Version:  1.16.2
     ...
   Status:
     Anthos Bare Metal Version:  1.16.2
   

   在此示例中，节点为 Google Distributed Cloud 1.16.2 版。