#在 VMware vSphere 上升级 Kubernetes

本文介绍如何在平台侧发行版升级完成后，升级 VMware vSphere 上的 Kubernetes 集群。本文档所述的工作流重点是通过 Cluster API 资源更新控制平面和工作节点。发布规则请参阅提供商要求。

#升级顺序

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

1. （前提条件） 首先升级管理集群上的 ACP 平台。这样可将 cluster-api-provider-vsphere 控制器及相关 CAPI 组件升级到能够识别新架构的版本。提供商会更新其 CRD，并自行将现有资源迁移到新的字段布局，无需手动修改 YAML。请参阅升级提供商。只有在管理侧控制器完成发布并变为 Ready 后，才触发业务集群升级。
2. 完成升级发行版版本中所述的发行版版本升级。
3. 确认现有的 KubeadmControlPlane 和 MachineDeployment 清单符合发布规则。不符合规则的 KubeadmControlPlane 可能会阻止升级时的首次编辑，不符合规则的 MachineDeployment 则会导致发布停滞。请参阅检查清单是否符合准入规则。
4. 确认控制平面运行正常，且当前集群稳定。
5. 将 Kube-OVN 升级到目标 ACP 版本所需的 chart 版本，并等待 AppRelease 达到 Success。
6. 升级控制平面的 Kubernetes 版本。
7. 将工作节点升级到目标 Kubernetes 版本。

#前提条件

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

• 已完成发行版版本升级。
• 控制平面运行正常且可访问。
• 所有节点均处于 Ready 状态。
• 已按照受支持的 ACP 备份操作步骤创建并验证最新的 etcd 备份。
• vSphere 环境中已存在由面向目标 ACP 版本发布的 Alauda OS 镜像构建的 VM 模板。如果应用新的 VSphereMachineTemplate 时模板不存在，升级将失败。
• 对于跨越多个 Kubernetes 次要版本的跨版本升级，请预先暂存中间版本的 Core 镜像和 VM 模板。请参阅跨版本升级准备。
• 目标 Kubernetes 版本与工作负载及附加组件兼容。
• 机器配置池有足够的容量执行滚动更新。
• KubeadmControlPlane 将 spec.rolloutStrategy.rollingUpdate.maxSurge: 0 和 spec.replicas 设置为 3 或更高值，并且每个 MachineDeployment 都设置了 spec.strategy.rollingUpdate.maxSurge: 0。这些值可让替换操作复用相同的槽位和磁盘标识。在开始之前，请使用检查清单是否符合准入规则进行验证。
• 管理集群不是灾难恢复备用集群。针对备用集群时，提供商会跳过非 global 对象，并每 30 秒重新排队一次，因此发布看起来会像是尚未启动，而不是失败。请参阅备用管理集群。
• 你知道此集群的 KubeadmControlPlane 名称。请从 Cluster.spec.controlPlaneRef.name 中读取；在 VMware vSphere 上创建集群中的清单将其命名为 <cluster_name>-kcp。
• 如果集群使用自建 VIP（controlPlaneLoadBalancer.type: internal），则 VSphereCluster.status.conditions[SelfBuiltLoadBalancerReady] 为 True，并且新 VM 模板满足 Alive 内核前提条件（ip_vs 模块系列可加载，且允许使用 net.ipv4.vs.conntrack=1）。替换后的控制平面节点基于该模板构建，提供商不会注入或验证这些设置。
• 查看 Kubernetes 升级路径和版本偏差策略。

#OS Support Matrix 中的必需值

ACP 版本、Kubernetes 版本以及对应的 CoreDNS、etcd 和 Kube-OVN 版本之间的权威映射位于 OS Support Matrix。开始之前，请找到与目标 ACP 版本对应的行；该行提供了以下操作步骤所需的组件值。

VM 模板名称不在矩阵中。它是使用针对目标 ACP 版本发布的 Alauda OS 镜像在 vSphere 中创建模板时所用的名称 — 请参阅下载 Alauda OS — VSphereMachineTemplate.spec.template.spec.template 必须在控制平面和工作节点模板中都设为该名称。

该行中各列的值在升级清单中的对应关系如下：

CoreDNS 和 etcd 镜像标签仅用于控制平面，因为 clusterConfiguration 是 KubeadmControlPlane 字段。工作节点从新的 VM 模板继承容器镜像版本；MachineDeployment 不包含自己的 dns/etcd 标签。Kube-OVN 注解位于 Cluster 资源上，而不是 KubeadmControlPlane 上。

#操作步骤

kubectl -n <namespace> get kubeadmcontrolplane <cluster_name>-kcp \
  -o jsonpath='replicas={.spec.replicas} maxSurge={.spec.rolloutStrategy.rollingUpdate.maxSurge}{"\n"}'

kubectl -n <namespace> get machinedeployment -o custom-columns='NAME:.metadata.name,TYPE:.spec.strategy.type,SURGE:.spec.strategy.rollingUpdate.maxSurge,UNAVAIL:.spec.strategy.rollingUpdate.maxUnavailable'

# replicas is 3 or more: correct maxSurge.
kubectl -n <namespace> patch kubeadmcontrolplane <cluster_name>-kcp --type='merge' \
  -p='{"spec":{"rolloutStrategy":{"type":"RollingUpdate","rollingUpdate":{"maxSurge":0}}}}'

kubectl -n <namespace> patch machinedeployment <cluster_name>-md-0 --type='merge' \
  -p='{"spec":{"strategy":{"type":"RollingUpdate","rollingUpdate":{"maxSurge":0,"maxUnavailable":1}}}}'

kubectl -n <namespace> get vspheremachineconfigpool
kubectl -n <namespace> get vspheremachineconfigpool <cluster_name>-cp-pool \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'

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>"
          },
          "bootstrap": {
            "configRef": {
              "name": "<new-bootstrap-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

#在不更改 Kubernetes 版本的情况下更新 OS 映像

使用此操作步骤，在 Kubernetes 版本保持不变的情况下，将节点迁移到新的 Alauda OS 映像，例如获取 OS 安全修复，或将Pod 日志目录迁移应用到现有节点。

1. 按照创建目标机器模板中的导出、清理和重命名操作步骤，创建新的 VSphereMachineTemplate 资源。仅将 spec.template.spec.template 更改为新的 VM 模板名称。
2. 应用两个新模板。
3. 修补 KubeadmControlPlane.spec.machineTemplate.infrastructureRef.name，等待控制平面滚动升级完成，然后修补 MachineDeployment.spec.template.spec.infrastructureRef.name。

不要修改 spec.version、clusterConfiguration.dns.imageTag、clusterConfiguration.etcd.local.imageTag 或 cpaas.io/kube-ovn-version 注释。OS 映像滚动升级并非 Kubernetes 版本升级，因此无需遵循先升级 Kube-OVN 的顺序。

同样的滚动升级规则仍然适用：两个控制器上的 maxSurge: 0。由池管理的持久磁盘会像版本升级时一样重新挂载；由池管理的临时磁盘则会被销毁并重新创建为空磁盘。

如需恢复，将控制资源指回之前的模板。这是从失败的第 2 阶段升级中恢复的第 2 阶段。

#不代表失败的滚动升级暂停

某些滚动升级暂停是 Provider 为保护数据而设置的。不要手动清除这些暂停。

附件安全暂停。 删除 VSphereVM 时，Provider 会扫描数据中心，查找仍挂载着该槽位持久磁盘后端存储的 VM。只要仍有任何磁盘处于挂载状态，Provider 就会保留 finalizer 并重新排队。相同的检查也会保护池回收。如果滚动升级似乎在删除第一个旧机器时停滞，通常是触发了此暂停，而非出现故障。不要移除 finalizer。

读取当前状态：

kubectl -n <namespace> get vspheremachineconfigpool <pool_name> \
  -o jsonpath='{range .status.persistentDiskStatuses[*]}{.hostname}{" "}{.name}{" "}{.phase}{" owner="}{.ownerMachineName}{" err="}{.lastError}{"\n"}{end}'
kubectl -n <namespace> get vspherevm -o custom-columns='NAME:.metadata.name,DELETED:.metadata.deletionTimestamp,FINALIZERS:.metadata.finalizers'

正常的交接过程是先执行 Attached，待旧 VM 消失后执行 Available，然后在替换机器上再次执行 Attached。删除和重新创建过程中会保留 ownerMachineName 和 ownerMachineUID，因此替换机器会重新挂载相同的磁盘。

Reclaimed 是墓碑记录。 不要删除 phase: Reclaimed 条目来解除滚动升级停滞。有关删除该条目会导致重新播种循环的原因，请参阅集群创建页面中的故障排除。

SlotAvailable=False 属于预期情况。 使用 maxSurge: 0 且池已完全分配时，只有在删除旧机器后才会有空闲槽位。SlotAvailable 会从池的 Ready 摘要中排除，正是为了避免将这种情况显示为失败。

在 vCenter 中关机的节点会保持关机状态。 VSphereVM 一旦锁定 InitialPowerOnCompleted=True，控制器就不再强制启动已关机的 VM。滚动升级期间创建的替换 VM，其锁定位未设置，因此升级前主动关机的节点会在替换后以开机状态恢复。

#从失败的 Phase 2 升级中恢复

不要将 Kubernetes 次版本降级视为普通回滚。请根据滚动升级阶段选择恢复路径：

1. 尚未创建目标版本的控制平面 Machine：恢复之前的 Kube-OVN 注解，以及之前的 KubeadmControlPlane 和 MachineDeployment 清单值。这样可以在引入新的控制平面数据格式之前取消目标版本的滚动升级。
2. 仅更改了机器模板或 OS 镜像，Kubernetes 次版本未变：将控制资源指回之前的模板。Cluster API 会执行另一轮替换滚动升级。保持 Kubernetes 次版本不变。
3. 目标 Kubernetes 次版本的控制平面 Machine 已加入集群：不要将 Kubernetes、CoreDNS 或 etcd 回退到之前的次版本。停止进一步滚动升级，在目标次版本上向前修复，或使用受支持的 ACP 恢复操作步骤，从经过验证的升级前备份恢复集群。

如果已创建目标次版本的控制平面 Machine，但它从未加入集群，请先恢复健康的 etcd 仲裁，并确定是否可以安全移除失败的替换节点。不要假设仅更改版本字段就足够了。

恢复期间，请牢记以下基础设施事实：

• 旧 VM 已不存在。 它们已在升级过程中销毁。模板恢复会创建一组全新的替换机器，不会恢复原始 VM。
• 旧的 VSphereMachineTemplate 资源必须仍然存在。 在新一轮滚动升级恢复正常之前，不要删除之前的模板。如果已将其删除，请在尝试恢复相同次版本的模板之前，从版本控制或备份中重新创建。
• 池管理的磁盘身份会保留，但数据状态不会。 在 VSphereMachineConfigPool.spec.configs[].persistentDisks[] 中声明的磁盘会在相同槽位重新挂载到替换机器上，但升级期间写入的数据仍保留在这些磁盘上。
• 临时磁盘已丢失。 每个被替换 VM 上的 VSphereMachineConfigPool.spec.configs[].ephemeralDisks[] 数据都会随 VM 一起销毁，无法从池中恢复。只有池管理的持久磁盘会重新挂载。
• 不要撤销滚动升级规则的修正。 如果阶段 1 要求恢复之前的清单值，请将 maxSurge 保持为 0。

对于阶段 1，请使用在阶段 1 恢复期间恢复 Kube-OVN中的 vSphere 规则。Provider 会根据注解恢复 chart。请等待恢复后的 AppRelease 通过共享验证，然后再更改控制平面清单。

如果 etcd 不健康，KubeadmControlPlane 控制器可能会阻止替换操作。重试任何安全的替换操作之前，请先恢复仲裁。

#验证

升级后重新读取池状态：

kubectl -n <namespace> get vspheremachineconfigpool
kubectl -n <namespace> get vspheremachineconfigpool <pool_name> \
  -o jsonpath='{range .status.persistentDiskStatuses[*]}{.hostname}{" "}{.name}{" "}{.phase}{"\n"}{end}'

确认以下结果：

• KubeadmControlPlane 达到目标版本和所需的从节点数。
• MachineDeployment 达到目标版本和所需的从节点数。
• 控制平面和工作节点恢复到 Ready 状态。
• vSphere CPI daemonset 在业务集群中仍然可用。
• 每个 VSphereMachineConfigPool 均报告 Ready=True 和 PersistentDisksReady=True；其 ALLOCATED 数量等于从该池调度运行的 Machine 数量，并且其 TOTAL 数量保持不变。
• 已分配槽位上的每个持久磁盘均报告 phase: Attached。

#故障排查

#后续步骤

Kubernetes 升级完成后，请继续参阅 在 VMware vSphere 上管理节点，执行常规节点操作。