#在 VMware vSphere 上升级集群

#创建目标 machine templates

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

1. 导出现有的控制平面模板

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

2. 修改控制平面模板

   编辑 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
   • 保持 spec.template.spec.providerID 为空。vSphere provider 会在 VM 创建后将 providerID 设置为该 VM 的 BIOS UUID；如果在模板中预先填充该字段，会破坏控制器的身份绑定。

3. 导出并修改工作节点模板

   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、内存或磁盘设置
   • 删除上面列出的相同服务器生成字段

4. 应用这两个新模板

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

#升级控制平面

开始之前，请按照 来自 OS Support Matrix 的必需值 的说明，从目标 ACP 行中收集所有必需值。

1. 使用目标 Kubernetes 值 patch KubeadmControlPlane

   在一次编辑中更新 KubeadmControlPlane 资源，以保持 spec.version、CoreDNS 镜像标签、etcd 镜像标签以及基础设施模板引用与同一个 VM 模板一致：

   • spec.version ← OS Support Matrix 行中的 Kubernetes Version

   • spec.kubeadmConfigSpec.clusterConfiguration.dns.imageTag ← 同一行中的 coredns 列

   • spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.imageTag ← 同一行中的 etcd 列

   • spec.machineTemplate.infrastructureRef.name ← 上面创建的新 VSphereMachineTemplate 名称

     kubectl edit kubeadmcontrolplane <cluster_name> -n <namespace>

   仅更新 spec.version 并不够。CoreDNS 和 etcd 的镜像标签必须与 Kubernetes 版本一起移动，因为它们是基于同一发行版构建的；如果保留旧值，可能会导致 CoreDNS 和 etcd Pod 与新的 Kubernetes 次版本不匹配。

2. 更新 Cluster 资源上的 Kube-OVN 版本注解

   如果 OS Support Matrix 中目标 ACP 行显示的 kube-ovn (chart) 值与当前集群不同，请 patch Cluster 资源上的注解，以便 vSphere provider 协调新的 Kube-OVN AppRelease。

   INFO

   前提条件 — Kube-OVN 协调门控注解（仅适用于 vSphere）

   在 vSphere 上，provider 只有在 Cluster 资源带有注解 cpaas.io/network-type: kube-ovn 时，才会协调 Kube-OVN AppRelease。该注解通常在集群创建时设置。如果缺少该注解，下面的步骤虽然会成功写入版本注解，但不会协调 Kube-OVN AppRelease。继续之前请先验证：

   kubectl get cluster <cluster_name> -n <namespace> \
     -o jsonpath='{.metadata.annotations.cpaas\.io/network-type}{"\n"}'
   # Expected output: kube-ovn

   这个前置条件是 vSphere 特有的。DCS 和 Huawei Cloud Stack provider 则改用 DCSCluster / HCSCluster 的 spec.networkType 字段，因此不需要该注解。

   kubectl annotate cluster <cluster_name> -n <namespace> \
     cpaas.io/kube-ovn-version=<kube-ovn-version-from-matrix> --overwrite

   Kube-OVN 是一个 Core 生命周期组件，但在不可变 OS 上，vSphere provider 会根据这个注解驱动其交付；当 spec.version 变化时，该注解不会自动更新。

   vSphere provider 会在业务集群的 cpaas-system 命名空间中协调一个名为 cni-kube-ovn 的 Kube-OVN AppRelease。请在业务集群上执行以下命令（而不是 bootstrap KIND 或 global 集群）来跟踪协调过程：

   # Overall AppRelease state — Sync and Health columns must reach a Success-equivalent reason
   kubectl get apprelease cni-kube-ovn -n cpaas-system
   
   # Installed revision and chart phase
   kubectl get apprelease cni-kube-ovn -n cpaas-system \
     -o jsonpath='Installed: {.status.charts.*.installedRevision}{"\n"}Phase: {.status.charts.*.phase}{"\n"}'

   正常顺序是 Upgrading → HealthChecking → Success。在小型集群上，完整转换通常会在大约一分钟内完成。各阶段含义如下：

   阶段	含义	installedRevision
   Upgrading	Helm release 升级进行中。Sync 条件为 Unknown(Syncing)。	仍然是上一版本
   HealthChecking	Helm release 已应用；控制器正在验证 Kube-OVN Pod。Sync 条件为 True(Synced)。	已经是目标版本
   Success	所有三个条件（Validate、Sync、Health）均为 True。	目标版本

   WARNING

   不要仅凭 installedRevision 就宣布升级完成。该字段会在 HealthChecking 阶段切换到目标值，此时 Pod 还没有完成 Ready 验证。只有当 phase 为 Success 且 installedRevision 与目标值一致时，才认为 chart 已升级完成。

   AppRelease API 还定义了 Downloading、Installing、Syncing、DownloadFailed、DeployFailed 和 NotReady。前三者是临时状态，升级应会自行收敛。后三者表示发生故障，需要人工排查；请先执行 kubectl describe apprelease cni-kube-ovn -n cpaas-system 以查看每个条件的 message 字段。

3. 监控控制平面滚动更新

   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 模板）

应用这些更改：

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