#在 Huawei DCS 上升级集群

本指南介绍如何完成 Huawei DCS 集群升级工作流的第 2 阶段。在升级 Kubernetes 之前，请先完成《升级集群》中所述的 Distribution Version 升级。

#升级顺序

按以下顺序升级 DCS 集群：

1. 前提条件：首先升级管理集群上的 ACP 平台。这会将 cluster-api-provider-dcs 控制器以及相关的 CAPI 组件（核心组件、KubeadmControlPlane provider、bootstrap provider）升级到能够识别新 schema 的版本。只有在管理端控制器完成部署并进入 Ready 状态后，才可触发业务集群升级。
2. 在业务集群上升级 Distribution Version（Aligned Extensions）。请参阅《升级 Distribution Version》。
3. 将 Kube-OVN 升级到目标 ACP 版本所需的 chart 版本，并等待 AppRelease 达到 Success。
4. 升级控制平面 Kubernetes 版本。
5. 将工作节点升级到目标 Kubernetes 版本。

Cluster API 使用内置的安全机制编排滚动更新，以减少对服务的影响。

#前提条件

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

• Distribution Version 升级已完成
• 控制平面可访问
• 所有节点均正常且处于 Ready 状态
• 已使用受支持的 ACP 备份操作步骤创建并验证最新的 etcd 备份
• IP Pool 具有足够的滚动更新容量
• VM 模板支持目标 Kubernetes 版本。有关版本映射，请参阅 OS Support Matrix
• 对于跨越多个 Kubernetes 次要版本的跨版本升级，已预先准备好中间版本的 Core 镜像和 VM 模板。请参阅《跨版本升级准备》
• 目标 Kubernetes 版本与您的工作负载和附加组件兼容
• 如果使用池管理持久磁盘，DCS VM 模板必须为 4.2.1 或更高版本，因为安全关机和磁盘卸载依赖 guest tools
• 如果依赖池管理持久磁盘，请保留 KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge = 0 和每个 MachineDeployment.spec.strategy.rollingUpdate.maxSurge = 0
• 如果集群使用其他 NIC，请保留所需的 DCSIpHostnamePool.spec.pool[].additionNic[] 条目，并确认 DCS DVS 和 Port Groups 可从可能接收替换 VM 的主机访问

#使用 YAML

基于 YAML 的升级不依赖 Fleet Essentials。

#OS Support Matrix 中的必需值

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

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

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

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

请与集群平台所有者确认，目标 ACP 版本发布的 Alauda OS 镜像已上传到 DCS 平台，并记录使用该镜像在 DCS 上创建的 VM 模板名称。如果应用 DCSMachineTemplate 时该 VM 模板不存在于 DCS 上，升级将失败。

#在控制平面之前升级 Kube-OVN

按照在控制平面之前升级 Kube-OVN中的说明操作，并选择与已安装的 DCS provider 版本匹配的 Huawei DCS 操作步骤。该共享操作步骤负责 provider 版本边界、v4.4 处的 Kube-OVN chart 名称迁移、旧版行为以及所需的 AppRelease 健康检查。

对于 Kube-OVN 的 v4.4+ 目标版本，不要使用旧版直接 targetRevision patch。请先将 DCS provider 升级到 v1.0.22 或更高版本，以便它协调完整的 source 以及相关的 CoreDNS 和 kube-proxy 仓库变更。此 provider 升级不会将现有的外部控制平面端点迁移到 Self-built VIP；在常规 Kubernetes 升级期间，端点模式保持不变。

#升级控制平面基础设施

升级控制平面机器模板可以推出更新后的 VM 规格、系统补丁和基础设施设置。

#操作步骤

1. 创建更新后的机器模板

   复制 KubeadmControlPlane 引用的现有 DCSMachineTemplate，并将其另存为新文件：

   kubectl get dcsmachinetemplate <current-template-name> -n cpaas-system -o yaml > new-cp-template.yaml

2. 修改模板规格

   根据需要更新新模板：

   • 将 metadata.name 设置为 <new-template-name>
   • 更新 spec.template.spec.vmTemplateName
   • 更新 spec.template.spec.vmConfig.dcsMachineCpuSpec.quantity
   • 更新 spec.template.spec.vmConfig.dcsMachineMemorySpec.quantity
   • 仅更新系统磁盘和模板本地磁盘的 spec.template.spec.vmConfig.dcsMachineDiskSpec
   • 从复制的 manifest 中删除服务器生成的元数据（resourceVersion、uid、generation、creationTimestamp、managedFields、kubectl.kubernetes.io/last-applied-configuration 注解）以及完整的 status 字段。
   • 保持 spec.template.spec.providerID 未设置。VM 创建后，DCS provider 会将 providerID 设置为 dcs://<machine-name>；在模板中预先填充该值会破坏控制器的身份绑定。

   将包括 /var/cpaas 在内的池管理持久磁盘保留在 DCSIpHostnamePool.spec.pool[].persistentDisk 中。将其他 NIC 保留在 DCSIpHostnamePool.spec.pool[].additionNic[] 中。

3. 应用更新后的模板

   kubectl apply -f new-cp-template.yaml -n cpaas-system

4. 更新控制平面引用

   修改 KubeadmControlPlane 资源，使其引用新模板：

   kubectl patch kubeadmcontrolplane <kcp-name> -n cpaas-system --type='merge' -p='{"spec":{"machineTemplate":{"infrastructureRef":{"name":"<new-template-name>"}}}}'

5. 监控滚动更新

   kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system -w
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/control-plane

#升级控制平面 Kubernetes 版本

在 Alauda OS 上升级控制平面 Kubernetes 版本采用删除并重新创建的工作流。控制平面 VM 会根据新的 DCSMachineTemplate 逐个替换，该资源指向目标 Alauda OS VM 模板；同时会 patch KubeadmControlPlane 资源，使其携带匹配的 Kubernetes 版本、CoreDNS 镜像标签和 etcd 镜像标签。

开始前，完成共享的在控制平面之前升级 Kube-OVN操作步骤，并确认 cni-kube-ovn AppRelease 已通过 phase=Success 位于目标 revision。然后按照OS Support Matrix 中的必需值中的说明，从目标 ACP 行收集所有必需的控制平面值。

#操作步骤

1. 为目标 Kubernetes 版本创建新的 DCSMachineTemplate

   复制现有控制平面模板，并将 metadata.name 更新为新名称，将 spec.template.spec.vmTemplateName 更新为使用目标 ACP 版本发布的 Alauda OS 镜像在 DCS 上创建的 VM 模板。将池管理持久磁盘保留在 DCSIpHostnamePool.spec.pool[].persistentDisk 中，将其他 NIC 保留在 DCSIpHostnamePool.spec.pool[].additionNic[] 中，而不是将它们重新作为模板字段引入。

   kubectl get dcsmachinetemplate <current-cp-template-name> -n cpaas-system -o yaml > new-cp-template.yaml
   # edit metadata.name and spec.template.spec.vmTemplateName
   kubectl apply -f new-cp-template.yaml -n cpaas-system

2. 使用目标 Kubernetes 值 patch KubeadmControlPlane

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

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

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

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

   • spec.machineTemplate.infrastructureRef.name ← 第 1 步创建的新 DCSMachineTemplate 名称

   • 当目标版本为 Kubernetes 1.35 或更高版本时，在同一次编辑中更新 spec.kubeadmConfigSpec.files 中的 /etc/kubernetes/patches/kubeletconfiguration0+strategic.json，如适用于 Kubernetes 1.35 的必需 kubelet patch中所述

     kubectl edit kubeadmcontrolplane <kcp-name> -n cpaas-system

仅更新 spec.version 并不足够。CoreDNS 和 etcd 镜像标签必须随 Kubernetes 版本一起变更，因为它们基于同一 Alauda OS 版本构建；保留旧值可能导致 CoreDNS 和 etcd Pod 与新的 Kubernetes 次要版本不匹配。

3. 监控滚动更新

   kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system -w
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/control-plane
   kubectl get nodes

   当集群依赖池管理持久磁盘时，KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge 必须保持为 0，以便控制平面 VM 逐个替换。

#升级工作节点

工作节点 Kubernetes 升级通过 MachineDeployment 资源管理。工作节点升级所携带的字段少于控制平面：CoreDNS 和 etcd 镜像标签属于 KubeadmControlPlane.spec.kubeadmConfigSpec.clusterConfiguration，而 MachineDeployment 不包含这些标签。工作节点从新的 VM 模板继承 Kubernetes 组件版本；MachineDeployment 只需包含目标 Kubernetes 版本和新模板引用。

开始前，请读取 OS Support Matrix中目标 ACP 行的 Kubernetes Version 单元格，并按照OS Support Matrix 中的必需值中的说明确认 DCS 上的目标 VM 模板名称。

#操作步骤

1. 为工作节点创建新的 DCSMachineTemplate

   • 创建新的 DCSMachineTemplate，并将 vmTemplateName 设置为使用目标 ACP 版本发布的 Alauda OS 镜像在 DCS 上创建的 VM 模板
   • 将 /var/cpaas 和其他升级时需保留的磁盘保留在 DCSIpHostnamePool.spec.pool[].persistentDisk 中，而不是将它们重新作为模板磁盘引入
   • 将其他 NIC 保留在 DCSIpHostnamePool.spec.pool[].additionNic[] 中

2. 更新 MachineDeployment

   • 将 spec.template.spec.version 设置为同一 OS Support Matrix 行中的 Kubernetes Version 值
   • 将 spec.template.spec.infrastructureRef.name 设置为第 1 步创建的新 DCSMachineTemplate 名称
   • 当目标版本为 Kubernetes 1.35 或更高版本时，创建包含所需 kubelet patch 的新 KubeadmConfigTemplate，并在同一次编辑中将 spec.template.spec.bootstrap.configRef.name 设置为该模板；对于更早的版本，仅在需要其他 bootstrap 更改时更新 bootstrap 引用

3. 监控滚动更新

   • 验证滚动更新成功完成
   • 验证新的工作节点以目标 Kubernetes 版本加入集群

   当集群依赖池管理持久磁盘时，MachineDeployment.spec.strategy.rollingUpdate.maxSurge 必须保持为 0，以便工作节点逐个替换。

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

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

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

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

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

• 旧 VM 已不存在。 它们在升级期间已被销毁。模板恢复会构建一组全新的替换机器，不会恢复原始 VM。
• 旧的 DCSMachineTemplate 资源必须仍然存在。 在新的滚动更新健康之前，不要删除之前的模板。如果已经删除，请在尝试同一 Kubernetes 次要版本的模板恢复前，根据版本控制或备份重新创建该模板。
• 池管理磁盘的身份会保留，但数据状态不会保留。 DCSIpHostnamePool.spec.pool[].persistentDisk 中声明的磁盘会在相同 IP 槽位重新挂载到替换机器，但升级窗口期间写入这些磁盘的数据仍会保留在磁盘上。

对于阶段 1，请使用阶段 1 恢复期间恢复 Kube-OVN中的 DCS 规则。恢复操作取决于已安装的 provider 版本：当前 provider 会从注解恢复完整 source，而旧版 provider 需要应用之前 chart 的 revision patch。在更改控制平面 manifest 前，请等待恢复后的 AppRelease 通过共享验证。

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

---

#Fleet Essentials 边界

Fleet Essentials 1.0.4 及更高版本可以通过 CVO 请求 ACP 4.3 及更高版本的 Distribution Version 升级。这是本指南的阶段 1。Fleet Essentials 不会在阶段 2 中执行 DCS Kubernetes 和 Alauda OS 替换，也不会管理 DCSIpHostnamePool.spec.pool[].persistentDisk。请使用本页的 YAML 操作步骤完成阶段 2 的整个滚动更新。

通过 Fleet Essentials 创建集群和执行常规节点池管理不受此升级限制的影响。

#其他资源

• 将现有 Huawei DCS 集群迁移到池管理的持久化磁盘
• Cluster API 升级文档
• Kubernetes 版本偏差策略