#在 Huawei DCS 上升级 Kubernetes

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

#升级顺序

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

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

Cluster API 使用内置安全机制编排滚动更新，以减少服务中断。

#前提条件

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

• Distribution Version 升级已完成
• 控制平面可达
• 所有节点健康并处于 Ready 状态
• IP Pool 有足够容量支持滚动更新
• VM 模板支持目标 Kubernetes 版本。有关版本映射，请参见 OS Support Matrix
• 对于跨越超过一个 Kubernetes minor 版本的跨版本升级，请提前准备好中间版本的 Core 镜像和 VM 模板。参见 Cross-Version Upgrade Preparation
• 目标 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 上不存在，升级将失败。

#升级控制平面基础设施

升级控制平面 machine template 可让你滚动发布更新后的 VM 规格、系统补丁和基础设施设置。

#操作步骤

1. 创建更新后的 machine template

   复制 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 中删除服务器生成的 metadata（resourceVersion、uid、generation、creationTimestamp、managedFields、kubectl.kubernetes.io/last-applied-configuration annotation）以及整个 status 字段。
   • 保持 spec.template.spec.providerID 为空。DCS provider 会在 VM 创建后将 providerID 设置为 dcs://<machine-name>；如果在模板中预先填充该值，会破坏 controller 的 identity binding。

   将池管理持久盘（包括 /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 会通过新的 DCSMachineTemplate 逐台替换；该模板指向目标 Alauda OS VM 模板，并且会 patch KubeadmControlPlane 资源，使其携带匹配的 Kubernetes 版本、CoreDNS 镜像标签和 etcd 镜像标签。

在开始之前，请先按照 来自 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 名称

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

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

3. 在业务集群上升级 Kube-OVN chart

   Kube-OVN 是一个 Core 生命周期组件，但在不可变 OS 上，DCS provider 不会将其 chart 版本固定到集群的 Kubernetes 版本。chart 版本由业务集群 cpaas-system 命名空间中的一个名为 cni-kube-ovn 的独立 AppRelease 承载，你需要通过两个步骤将其推进：先更新 Cluster 资源上的注解用于记录和未来重新创建，再直接 patch 现有 AppRelease 以提升 chart revision。

   WARNING

   为什么在 DCS 上需要两个步骤

   DCS provider 在集群首次创建时会创建 cni-kube-ovn AppRelease，从那以后它只会协调 spec.values 块（集群名称、CIDR、registry、控制平面节点列表）。它不会写入已存在 AppRelease 的 spec.source.charts[0].targetRevision。因此，仅修改 Cluster 资源上的 cpaas.io/kube-ovn-version 并不会改变业务集群上的 chart 版本。仍然需要更新该注解，以便记录的目标值与 OS Support Matrix 行保持一致，但 chart 升级本身必须通过直接 patch AppRelease 来驱动。

   3.1. 更新 Cluster 资源上的 cpaas.io/kube-ovn-version 注解

   kubectl annotate cluster <cluster-name> -n cpaas-system \
     cpaas.io/kube-ovn-version=<kube-ovn-version-from-matrix> --overwrite

   当 spec.version 变化时，该注解不会自动更新；请使其与目标行的 kube-ovn (chart) 列保持一致。

   3.2. 在业务集群上 patch AppRelease 的 chart revision

   请对业务集群的 API server 执行 patch，而不是 bootstrap KIND 或 global 集群：

   kubectl patch apprelease cni-kube-ovn -n cpaas-system --type='json' \
     -p='[{"op":"replace","path":"/spec/source/charts/0/targetRevision","value":"<kube-ovn-version-from-matrix>"}]'

   使用与注解中相同的值。releaseName（cpaas-kube-ovn）和 name（acp/chart-cpaas-kube-ovn）由 provider 管理；不要修改它们。

   3.3. 等待协调完成

   观察 chart phase 和 installed revision：

   # Overall AppRelease state — Sync and Health columns must reach a Success-equivalent reason
   kubectl get apprelease cni-kube-ovn -n cpaas-system
   
   # Installed revision and chart phase
   kubectl get apprelease cni-kube-ovn -n cpaas-system \
     -o jsonpath='Installed: {.status.charts.*.installedRevision}{"\n"}Phase: {.status.charts.*.phase}{"\n"}'

   正常顺序是 Upgrading → HealthChecking → Success。在小规模集群上，完整转换通常会在约一分钟内完成。各 phase 的含义如下：

   Phase	含义	installedRevision
   Upgrading	Helm release 正在升级。Sync 条件为 Unknown(Syncing)。	仍然是上一版本
   HealthChecking	Helm release 已应用；controller 正在验证 Kube-OVN Pod。Sync 条件为 True(Synced)。	已经是目标版本
   Success	三个条件（Validate、Sync、Health）均为 True。	目标版本

   WARNING

   不要仅凭 installedRevision 就宣布升级完成。该字段会在 HealthChecking 期间切换到目标值，此时 Pod 还没有被验证为 Ready。只有当 phase 为 Success 且 installedRevision 与目标值匹配时，才认为 chart 已升级完成。

   AppRelease API 还定义了 Downloading、Installing、Syncing、DownloadFailed、DeployFailed 和 NotReady。前三者是临时状态，升级应自行收敛。后三者表示失败，需要人工排查；首先运行 kubectl describe apprelease cni-kube-ovn -n cpaas-system 查看各条件的 message 字段。

4. 监控滚动更新

   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 的必需值 的说明，读取 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 名称
   • 如果此版本需要变更 bootstrap 配置，可选地更新 spec.template.spec.bootstrap.configRef.name

3. 监控滚动更新

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

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

#回滚失败的升级

如果滚动更新失败——新的 VM 无法启动、节点未能变为 Ready，或者新的 Kubernetes minor 版本暴露出兼容性问题——请将模板引用和 Kubernetes 版本字段恢复为先前的值。Cluster API 会将该回退视为新的 spec 漂移，并将 v2 机器逐台回滚到之前的模板。

在回滚之前，需要先牢记三点：

• 旧 VM 已经消失。 它们在升级期间已被销毁。回滚会使用旧模板构建一组新的替换机器；它不会恢复原始 VM。
• 旧的 DCSMachineTemplate 资源必须仍然存在。 在新滚动健康之前，不要删除旧模板。如果你已经删除了它，请先从版本控制或备份中重新创建，再进行回滚。
• 池管理磁盘的身份会被保留，但数据状态不会。 在 DCSIpHostnamePool.spec.pool[].persistentDisk 中声明的磁盘会以相同 IP 槽位重新挂载到回滚后的机器上，但升级窗口期间写入这些磁盘的任何数据（例如新 Kubernetes minor 格式的 etcd 条目）都会保留。如果新格式对旧 Kubernetes minor 版本不可读，那么回滚仍可能失败，并需要手动恢复 etcd。

操作步骤：

• 控制平面：patch KubeadmControlPlane，恢复之前的 spec.machineTemplate.infrastructureRef.name、spec.version、spec.kubeadmConfigSpec.clusterConfiguration.dns.imageTag 和 spec.kubeadmConfigSpec.clusterConfiguration.etcd.local.imageTag。

• Workers：patch 每个 MachineDeployment，恢复之前的 spec.template.spec.infrastructureRef.name 和 spec.template.spec.version。

• Kube-OVN：如果升级了 Kube-OVN chart，则按应用升级时相同的方式回退——先恢复注解，再将 AppRelease 的 chart revision patch 回去。使用与步骤 3 中相同的 installedRevision + phase=Success 检查进行验证。

  kubectl annotate cluster <cluster-name> -n cpaas-system \
    cpaas.io/kube-ovn-version=<previous-kube-ovn-version> --overwrite
  
  kubectl patch apprelease cni-kube-ovn -n cpaas-system --type='json' \
    -p='[{"op":"replace","path":"/spec/source/charts/0/targetRevision","value":"<previous-kube-ovn-version>"}]'

如果新的控制平面从未达到 etcd quorum，那么 KubeadmControlPlane controller 可能会拒绝回滚任何机器，因为其预检检查会在不健康的 etcd 上阻塞。在重试回滚之前，先恢复 etcd quorum（需要 operator 干预）。

---

#使用 Web UI

在第 1 阶段完成后，使用此工作流从 Web UI 升级 Kubernetes。

版本要求：此工作流要求 Fleet Essentials 和 Alauda Container Platform DCS Infrastructure Provider 1.0.13 或更高版本。如果 provider 版本早于 1.0.13，请使用 YAML manifest。如果升级依赖池管理持久盘，请使用 DCS provider v1.0.16 或更高版本。在 v1.0.16 中，DCSIpHostnamePool 上的 persistentDisk 声明仍然只能通过 YAML 配置，Web UI 中不提供该项。

#前提条件

• Distribution Version 升级已完成。参见 Upgrading Distribution Version
• Control Plane Node Pool 处于 Running 状态
• IP Pool 有足够容量支持滚动更新
• 如果升级依赖池管理持久盘，请确保所需的 DCSIpHostnamePool.spec.pool[].persistentDisk 条目已经通过 YAML 创建或更新

#升级工作流

在 Distribution Version 升级完成后，Kubernetes 升级按以下顺序进行：

1. 升级 Control Plane Node Pool。
2. 等待 Control Plane Node Pool 升级完成。
3. 按任意顺序升级 Worker Node Pools。

#检查可用升级

导航：Clusters → Clusters → 选择集群 → Node Pools 选项卡

有可用升级的 Node Pool 会显示 Upgrade available 指示器。点击 Node Pool 卡片可查看 Current 与 Target 版本。

#升级 Control Plane Node Pool

步骤：

1. 在 Node Pools 选项卡中，找到 Control Plane Node Pool
2. 点击 Upgrade
3. 查看升级信息：
   • Current Version：当前 Kubernetes 版本
   • Target Version：自动选择的最新 minor 版本
4. 点击 Confirm 开始升级

监控：

• 观察 Node Pool 状态
• 节点会逐台滚动更新（maxSurge=0）。当集群依赖持久盘时，也必须采用这种逐台替换方式。
• 升级时间取决于节点数量和资源情况

#升级 Worker Node Pools

何时可以升级 Worker Pool：

• Control Plane Kubernetes Version 与 global 集群版本一致
• Control Plane 处于 Running 状态

升级步骤：

1. 对每个 Worker Node Pool：
   • 点击 Upgrade 按钮
   • 查看并确认
2. Control Plane 完成后，各个 Pool 可以并行升级

升级约束：

#故障排查

---

#其他资源

• 将现有 Huawei DCS 集群迁移到池管理持久盘
• Cluster API Upgrade Documentation
• Kubernetes Version Skew Policy