在 VMware vSphere 上升级集群

本文档说明在平台侧 distribution 升级完成后，如何升级 VMware vSphere 上的 Kubernetes 集群。本文档所述工作流重点介绍如何通过 Cluster API 资源更新控制平面和工作节点。

升级顺序

按以下顺序升级 VMware vSphere 集群：

完成 Upgrading Clusters 中描述的 distribution 版本升级。
验证控制平面健康且当前集群稳定。
升级控制平面 Kubernetes 版本。
将工作节点升级到目标 Kubernetes 版本。

前提条件

开始之前，请确保满足以下条件：

distribution 版本升级已完成。
控制平面健康且可访问。
所有节点都处于 Ready 状态。
目标 VM 模板与目标 Kubernetes 版本兼容。
machine config pools 有足够容量执行滚动更新。

WARNING

模板是不可变的

VSphereMachineTemplate 资源不能原地修改。任何会更改 VM 规格或 VM 模板名称的升级，都需要创建一个新的、具有新名称的 VSphereMachineTemplate，并更新 KubeadmControlPlane 或 MachineDeployment 中的引用。

步骤

创建目标 machine 模板

在开始滚动升级之前，请为控制平面和工作节点创建新的 VSphereMachineTemplate 资源。

导出现有的控制平面模板

kubectl get vspheremachinetemplate <cluster_name>-control-plane -n <namespace> -o yaml > new-cp-template.yaml

修改控制平面模板

编辑 new-cp-template.yaml：
- 将 metadata.name 设置为新的唯一名称（例如，<cluster_name>-control-plane-v2）
- 将 spec.template.spec.template 更新为目标 VM 模板名称
- 如有需要，更新 CPU、内存或磁盘设置
- 删除服务器生成的字段：metadata.resourceVersion、metadata.uid、metadata.generation、metadata.creationTimestamp、metadata.managedFields、metadata.annotations["kubectl.kubernetes.io/last-applied-configuration"] 和 status
导出并修改工作节点模板
kubectl get vspheremachinetemplate <cluster_name>-worker -n <namespace> -o yaml > new-worker-template.yaml
编辑 new-worker-template.yaml：
- 将 metadata.name 设置为新的唯一名称（例如，<cluster_name>-worker-v2）
- 将 spec.template.spec.template 更新为目标 VM 模板名称
- 如有需要，更新 CPU、内存或磁盘设置
- 删除上述相同的服务器生成字段

应用这两个新模板

kubectl apply -f new-cp-template.yaml
kubectl apply -f new-worker-template.yaml

升级控制平面

更新 KubeadmControlPlane 资源，使其引用新的控制平面模板和目标 Kubernetes 版本。

常见变更包括：

spec.version — 目标 Kubernetes 版本
spec.machineTemplate.infrastructureRef.name — 新的 VSphereMachineTemplate 名称
当目标发行版需要时，相关镜像标签，例如 dns.imageTag 和 etcd.local.imageTag

应用变更：

kubectl patch kubeadmcontrolplane <cluster_name> -n <namespace> \
  --type='merge' -p='{
    "spec": {
      "version": "<target_kubernetes_version>",
      "machineTemplate": {
        "infrastructureRef": {
          "name": "<new-cp-template-name>"
        }
      }
    }
  }'

TIP

如果目标 Kubernetes 发行版还需要更新镜像标签（例如 dns.imageTag 或 etcd.local.imageTag），请将其包含在 patch payload 中，或者使用 kubectl apply -f 应用完整 manifest。

监控控制平面滚动过程：

kubectl -n <namespace> get kubeadmcontrolplane <cluster_name> -w
kubectl -n <namespace> get machine -l cluster.x-k8s.io/control-plane

升级工作节点

控制平面升级完成后，更新 MachineDeployment，使其引用新的工作节点模板和目标 Kubernetes 版本。

常见变更包括：

spec.template.spec.version — 目标 Kubernetes 版本
spec.template.spec.infrastructureRef.name — 新的 VSphereMachineTemplate 名称
spec.template.spec.bootstrap.configRef.name — 新的 KubeadmConfigTemplate 名称，如果 bootstrap 设置需要更改（参见 Updating Bootstrap Templates）

应用变更：

kubectl patch machinedeployment <cluster_name>-md-0 -n <namespace> \
  --type='merge' -p='{
    "spec": {
      "template": {
        "spec": {
          "version": "<target_kubernetes_version>",
          "infrastructureRef": {
            "name": "<new-worker-template-name>"
          }
        }
      }
    }
  }'

监控工作节点滚动过程：

kubectl -n <namespace> get machinedeployment <cluster_name>-md-0 -w
kubectl -n <namespace> get machine
kubectl --kubeconfig=/tmp/<cluster_name>.kubeconfig get nodes -o wide

回滚失败的升级

如果滚动更新失败（例如，新 VM 无法启动，或者节点无法变为 Ready），请将模板引用恢复为之前的模板名称。旧模板仍然存在，Cluster API 会回滚到先前的配置。

对于控制平面：patch KubeadmControlPlane，恢复之前的 spec.machineTemplate.infrastructureRef.name 和 spec.version。
对于工作节点：patch MachineDeployment，恢复之前的 spec.template.spec.infrastructureRef.name 和 spec.template.spec.version。

验证

升级后，请确认以下结果：

KubeadmControlPlane 达到目标版本和期望的 replica 数量。
MachineDeployment 达到目标版本和期望的 replica 数量。
控制平面和工作节点恢复为 Ready 状态。
vSphere CPI daemonset 在业务集群中保持可用。

后续步骤

Kubernetes 升级完成后，请继续执行 Managing Nodes on VMware vSphere 中的常规节点操作。

#在 VMware vSphere 上升级集群

#目录

#升级顺序

#前提条件

#步骤

#创建目标 machine 模板

#升级控制平面

#升级工作节点

#回滚失败的升级

#验证

#后续步骤