#在 Huawei DCS 上升级 Kubernetes

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

#升级顺序

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

1. （先决条件） 首先升级管理集群上的 ACP 平台。这会将 cluster-api-provider-dcs 控制器及相关 CAPI 组件（core、KubeadmControlPlane provider、bootstrap provider）升级到能够理解新架构的版本。仅当管理端控制器完成发布并变为 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 支持矩阵
• 对于跨越多个 Kubernetes 次要版本的跨版本升级，已预先准备好中间版本的 Core 映像和 VM 模板。请参阅跨版本升级准备
• 目标 Kubernetes 版本与您的业务负载和附加组件兼容
• 如果使用存储池管理的持久磁盘，则 DCS VM 模板必须为 4.2.1 或更高版本，因为安全关机和磁盘分离依赖客户机工具
• 如果依赖存储池管理的持久磁盘，请保留 KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge = 0 和每个 MachineDeployment.spec.strategy.rollingUpdate.maxSurge = 0
• 如果集群使用额外 NIC，请保留所需的 DCSIpHostnamePool.spec.pool[].additionNic[] 条目，并确认 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 设置为该名称，同时应用于控制平面和工作节点模板。

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

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

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

#在控制平面之前升级 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
   • 从复制的清单中移除服务器生成的元数据（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 版本

在 Alauda OS 上升级控制平面 Kubernetes 版本采用删除并重新创建的工作流。控制平面 VM 会从指向目标 Alauda OS VM 模板的新 DCSMachineTemplate 开始逐个替换，并对 KubeadmControlPlane 资源进行 patch，使其携带匹配的 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 更新为在 DCS 上根据目标 ACP 版本发布的 Alauda OS 镜像创建的 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 或更高版本时，按照适用于 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 次要版本不匹配。

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 设置为在 DCS 上根据目标 ACP 版本发布的 Alauda OS 镜像创建的 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（请参阅更新 Bootstrap 模板），并在同一次编辑中将 spec.template.spec.bootstrap.configRef.name 设置为该模板；对于更早的版本，仅当需要进行其他 bootstrap 更改时才更新 bootstrap 引用

3. 监控滚动更新

   • 确认滚动更新成功完成
   • 确认新工作节点已使用目标 Kubernetes 版本加入集群

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

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

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

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

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

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

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

对于阶段 1，请使用阶段 1 恢复期间恢复 Kube-OVN中的 DCS 规则。恢复操作取决于已安装的 provider 版本：当前 provider 会从注解中恢复完整 source，而旧版 provider 需要使用之前 chart 的 revision patch。请等待恢复后的 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 rollout。

通过 Fleet Essentials 创建集群和日常管理节点池不受此升级限制。

#Additional Resources

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