#在 Huawei DCS 上升级集群

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

#升级顺序

按照以下顺序升级 DCS 集群：

1. （前提条件） 先在管理集群上升级 ACP 平台。这会将 cluster-api-provider-dcs 控制器以及相关的 CAPI 组件（core、KubeadmControlPlane provider、bootstrap provider）升级到能够识别新 schema 的版本。只有在管理端控制器完成滚动发布并变为 Ready 之后，才触发业务集群升级。
2. 升级业务集群上的 Distribution Version（Aligned Extensions）。请参见 升级 Distribution Version。
3. 将 Kube-OVN 升级到目标 ACP 版本所需的 chart 版本，并等待 AppRelease 达到 Success。
4. 升级控制平面 Kubernetes 版本。
5. 将 worker 节点升级到目标 Kubernetes 版本。

Cluster API 会通过内置的安全机制编排滚动更新，以减少服务中断。

#前提条件

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

• Distribution Version 升级已完成
• 控制平面可达
• 所有节点均健康且处于 Ready 状态
• 已使用受支持的 ACP 备份流程创建并验证了当前的 etcd 备份
• IP Pool 具有足够容量以支持滚动更新
• VM 模板支持目标 Kubernetes 版本。版本映射请参见 OS Support Matrix
• 对于跨越多个 Kubernetes minor 的跨版本升级，已预先准备好中间版本的 Core 镜像和 VM 模板。请参见 跨版本升级准备
• 目标 Kubernetes 版本与您的工作负载和 add-on 兼容
• 如果您使用池管理型持久磁盘，则 DCS VM 模板必须是 4.2.1 或更高版本，因为安全关机和磁盘分离依赖 guest tools
• 如果您依赖池管理型持久磁盘，请保持 KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge = 0，并保持每个 MachineDeployment.spec.strategy.rollingUpdate.maxSurge = 0
• 如果集群使用额外 NIC，请保持所需的 DCSIpHostnamePool.spec.pool[].additionNic[] 条目不变，并确认可能接收替换 VM 的主机能够访问 DCS DVS 和 Port Groups

#使用 YAML

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

#来自 OS Support Matrix 的所需值

ACP 版本、其 Alauda OS 镜像、Kubernetes 版本，以及匹配的 CoreDNS、etcd 和 Kube-OVN 版本之间的权威映射保存在 OS Support Matrix 中。在开始之前，请先找到与目标 ACP 版本对应的行；该行提供下面 YAML 步骤所需的所有值。

您从该行读取的单元格与升级 manifest 的映射关系如下：

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

请与集群的平台所有者确认，目标 Alauda OS 镜像已经以上述矩阵行中 Alauda OS Image Version 的值作为名称上传到 DCS 平台。如果在应用 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 以及相关组件仓库变更。

#升级控制平面基础设施

升级控制平面机器模板可以让您发布更新后的 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 为空。DCS provider 在 VM 创建后会将 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 版本

在不可变 OS 上升级控制平面 Kubernetes 版本是一个删除后重建的工作流。控制平面 VM 会通过指向目标 Alauda OS VM 模板的新 DCSMachineTemplate 逐台替换，同时 KubeadmControlPlane 资源会被 patch，以携带匹配的 Kubernetes 版本、CoreDNS 镜像标签和 etcd 镜像标签。

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

#操作步骤

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

   将现有控制平面模板复制出来，并将 metadata.name 更新为新名称，同时将 spec.template.spec.vmTemplateName 更新为从 OS Support Matrix 的目标行读取到的 Alauda OS Image Version 值。请将池管理型持久磁盘保留在 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 或更高时，请在同一次编辑中按 Kubernetes 1.35 所需的 kubelet patch 的说明，更新 spec.kubeadmConfigSpec.files 中的 /etc/kubernetes/patches/kubeletconfiguration0+strategic.json

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

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

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 才会一次替换一台。

#升级 Worker 节点

Worker 节点的 Kubernetes 升级通过 MachineDeployment 资源进行管理。Worker 升级所携带的字段比控制平面更少：CoreDNS 和 etcd 镜像标签属于 KubeadmControlPlane.spec.kubeadmConfigSpec.clusterConfiguration，而 MachineDeployment 没有该字段。worker 节点从新的 VM 模板继承 Kubernetes 组件版本；MachineDeployment 只需要目标 Kubernetes 版本和新的模板引用。

在开始之前，请按照 来自 OS Support Matrix 的所需值 的说明，从目标 ACP 行中读取 Alauda OS Image Version 和 Kubernetes Version 两个单元格。

#操作步骤

1. 为 worker 节点创建新的 DCSMachineTemplate

   • 创建一个新的 DCSMachineTemplate，并将 vmTemplateName 设置为 OS Support Matrix 目标行中的 Alauda OS Image Version 值
   • 将 /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. 监视滚动更新

   • 验证滚动更新成功完成
   • 验证新 worker 节点已使用目标 Kubernetes 版本加入集群

   当集群依赖池管理型持久磁盘时，MachineDeployment.spec.strategy.rollingUpdate.maxSurge 必须保持为 0，这样 worker 节点才会一次替换一台。

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

不要把 Kubernetes minor 降级当作普通回滚。请根据滚动发布所处阶段选择恢复路径：

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

如果已经创建了目标 minor 的控制平面 Machine，但它从未加入集群，请先恢复健康的 etcd quorum，再判断失败的替换是否可以安全删除。不要假设仅修改版本字段就足够。

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

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

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

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

---

#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。完整的第 2 阶段发布请使用本页面上的 YAML 操作步骤。

通过 Fleet Essentials 进行集群创建和常规 node-pool 管理不受此升级限制影响。

#其他资源

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