#在 VMware vSphere 上升级集群

本文介绍如何在平台侧发行版升级完成后，在 VMware vSphere 上升级 Kubernetes 集群。本文档所述工作流重点是通过 Cluster API 资源更新控制平面和工作节点。本页面中的提供商行为和规则已针对 VMware vSphere Provider v1.0.17 进行验证。准入 Webhook 强制执行的规则列于提供商要求中。

#升级顺序

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

1. （前提条件） 首先升级管理集群上的 ACP 平台。此操作会将 cluster-api-provider-vsphere 控制器和相关 CAPI 组件升级到能够理解新架构的版本。提供商会更新其 CRD，并自行将现有资源迁移到新的字段布局，无需手动修改 YAML。请参阅升级提供商。只有在管理侧控制器完成推出并变为 Ready 后，才可触发业务集群升级。
2. 完成升级集群中所述的发行版版本升级。
3. 验证现有的 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 版本与您的工作负载和附加组件兼容。
• machine config pool 具有足够的容量来执行滚动更新。
• KubeadmControlPlane 将 spec.rolloutStrategy.rollingUpdate.maxSurge: 0 和 spec.replicas 设置为 3 或更高，并且每个 MachineDeployment 都将 spec.strategy.rollingUpdate.maxSurge: 0 设置为 1 或更高的 maxUnavailable。这些值使替换操作能够复用相同的插槽和磁盘标识，准入 webhook 会强制执行这些值。请在开始之前，通过根据准入规则检查清单进行验证。
• 管理集群不是灾难恢复备用集群。针对备用集群时，provider 会跳过非 global 对象，并每 30 秒重新排队一次，因此滚动更新看起来像是尚未开始，而不是失败。请参阅备用管理集群。
• 您知道此集群的 KubeadmControlPlane 名称。请从 Cluster.spec.controlPlaneRef.name 中读取；在 VMware vSphere 上创建集群中的清单将其命名为 <cluster_name>-kcp。
• 如果集群使用 Self-built VIP（controlPlaneLoadBalancer.type: internal），则 VSphereCluster.status.conditions[SelfBuiltLoadBalancerReady] 为 True，并且新 VM 模板满足 Alive 内核前置条件（可以加载 ip_vs 模块系列，且允许使用 net.ipv4.vs.conntrack=1）。替换的控制平面节点将从该模板构建，provider 不会注入或验证这些设置。
• 查看 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 设置为该名称，同时应用于控制平面模板和 worker 模板。

从该行读取的单元格按以下方式映射到升级清单：

CoreDNS 和 etcd 镜像标签仅适用于控制平面，因为 clusterConfiguration 是一个 KubeadmControlPlane 字段。worker 节点从新 VM 模板继承容器镜像版本；MachineDeployment 不包含自身的 dns/etcd 标签。Kube-OVN 注解位于 Cluster 资源上，而不是 KubeadmControlPlane 上，因为 vSphere provider 独立于 Kubernetes 控制平面滚动更新监视该资源。

#操作步骤

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 already 3 or more: correct maxSurge on its own.
kubectl -n <namespace> patch kubeadmcontrolplane <cluster_name>-kcp --type='merge' \
  -p='{"spec":{"rolloutStrategy":{"type":"RollingUpdate","rollingUpdate":{"maxSurge":0}}}}'

# replicas is 1: set replicas and maxSurge in the same patch. Declare the two extra
# control-plane slots first.
kubectl -n <namespace> patch kubeadmcontrolplane <cluster_name>-kcp --type='merge' \
  -p='{"spec":{"replicas":3,"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 Image 更新

使用此操作步骤可在 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，每个 MachineDeployment 至少为 maxUnavailable 个 1。由池管理的持久磁盘会像版本升级时一样重新挂载，由池管理的临时磁盘则会被销毁并以空磁盘重新创建。

要恢复，请将控制资源指回之前的模板。这是从失败的第 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 未设置该锁定状态，因此在升级前被主动关闭电源的节点会在替换后恢复为开机状态。

#从失败的阶段 2 升级中恢复

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

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

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

在任何恢复过程中，请牢记以下基础设施事实：

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

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

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

#验证

升级后读取池状态：

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 上管理节点执行常规节点操作。