#在 Huawei Cloud Stack 上升级集群

本指南说明如何在尽量减少停机时间的情况下升级 Huawei Cloud Stack 上的 Kubernetes 集群，同时保持稳定性和数据完整性。

#概述

HCS 上的集群升级包含多个组件，并采用结构化方法来确保系统可靠性：

• 控制平面升级：更新 Kubernetes 控制平面组件及底层基础设施
• 工作节点升级：使用新的机器镜像和 Kubernetes 版本升级工作节点
• 基础设施更新：修改虚拟机规格、存储和网络配置

#升级顺序

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

1. （前置条件） 先在管理集群上升级 ACP 平台。这会将 cluster-api-provider-hcs 控制器以及相关的 CAPI 组件升级到能够识别新 schema 的版本。只有在管理侧控制器完成滚动发布并变为 Ready 之后，才触发 workload 集群升级。
2. 升级 workload 集群上的 Distribution Version。请参见 升级集群。
3. 升级控制平面 Kubernetes 版本。
4. 将工作节点升级到目标 Kubernetes 版本。

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

#前提条件

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

• Distribution Version 升级已完成。
• 控制平面可达。
• 所有节点均处于健康状态并为 Ready。
• 目标 VM 镜像已存在于 HCS 环境中，且名称与 OS Support Matrix 对应行中的 Alauda OS Image Version 值相同。如果在应用新的 HCSMachineTemplate 时该镜像不存在，升级会失败。
• 对于跨越多个 Kubernetes minor 版本的跨版本升级，已预先准备好中间版本的 Core 镜像和 VM 镜像。请参见 跨版本升级准备。
• 目标 Kubernetes 版本与您的工作负载和附加组件兼容。
• 请检查 Kubernetes 升级路径和版本偏差策略。
• 任何必须在替换后仍需保留的节点本地状态，都应声明在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中，而不是声明在 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中。

首次部署请参见 创建集群 指南。

#控制平面升级

控制平面升级会更新 Kubernetes API server、etcd、scheduler 和 controller manager，以及底层的 VM 基础设施。

对于由使用 pool-managed persistent disks 的 HCSMachineConfigPool 支撑的 HCS 控制平面，在升级期间请将 KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge: 0 保持不变。persistent disks 绑定到固定的 (hostname, slot) 身份，因此滚动发布必须先移除旧机器，然后替换机器才能复用相同的磁盘。

#基础设施镜像更新

升级控制平面节点所使用的底层机器镜像可以提供安全补丁、性能改进以及更新后的系统组件。

#操作步骤

1. 创建更新后的 Machine Template

   复制 KubeadmControlPlane 引用的现有 HCSMachineTemplate，并修改所需规格：

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

2. 修改模板规格

   修改新模板：

   • 将 metadata.name 设置为 <new-template-name>
   • 从复制的 manifest 中移除服务器生成的 metadata 和 status 字段
   • 保持运行时身份字段为空，包括 spec.template.spec.providerID 和 spec.template.spec.serverId。HCS provider 在创建实例时会分配这些值。
   • 将需要保留的路径（例如 /var/cpaas）排除在 spec.template.spec.dataVolumes[] 之外。请在引用的 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明这些路径。
   • 按需更新：
     • spec.template.spec.imageName
     • spec.template.spec.flavorName
     • spec.template.spec.rootVolume.size
     • spec.template.spec.dataVolumes（仅用于临时磁盘）

3. 部署更新后的模板

   应用新的 machine template：

   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 版本升级

升级 Kubernetes 版本需要同时更新控制平面软件和配套的虚拟机镜像。

#来自 OS Support Matrix 的必需值

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

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

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

#操作步骤

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

   复制现有控制平面模板，并以新的 metadata.name 和目标 imageName 应用它：

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

   在 new-cp-template.yaml 中：

   • 将 metadata.name 设置为 <new-template-name>。

   • 将 spec.template.spec.imageName 设置为 OS Support Matrix 中目标行的 Alauda OS Image Version 值。

   • 删除服务器生成的 metadata（resourceVersion、uid、generation、creationTimestamp、managedFields、kubectl.kubernetes.io/last-applied-configuration 注解）以及整个 status 字段。

   • 保持运行时身份字段为空，包括 spec.template.spec.providerID 和 spec.template.spec.serverId。HCS provider 在 VM 创建后会将 providerID 设置为 hcs://<cluster-name>/<machine-name>，并将 serverId 设置为 HCS ECS 实例 ID；在模板中预先填充这些字段会破坏控制器的身份绑定。

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

2. 使用目标 Kubernetes 值补丁 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 步创建的新 HCSMachineTemplate 名称

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

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

   当引用的控制平面池使用 persistent disks 时，请保持 spec.rolloutStrategy.rollingUpdate.maxSurge: 0。替换机器在旧机器移除后必须复用相同的固定 hostname 和磁盘 slot。

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

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

   WARNING

   为什么在 HCS 上需要两步

   HCS provider 在集群首次构建时创建 cni-kube-ovn AppRelease，此后只会调谐 spec.values 块（集群名称、CIDR、registry、控制平面节点列表）。它不会写入已存在 AppRelease 的 spec.source.charts[0].targetRevision。因此，仅在 Cluster 资源上更改 cpaas.io/kube-ovn-version 并不会推动 workload 集群上的 chart 版本变更。注解仍然必须更新，以便记录的目标值与 OS Support Matrix 行一致，但 chart 升级本身需要通过直接补丁 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. 在 workload 集群上补丁 AppRelease 的 chart revision

   请针对 workload 集群的 API server 执行补丁操作（不要针对 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 阶段和已安装 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。在较小的集群上，完整转换通常会在大约一分钟内完成。各阶段含义如下：

   阶段	含义	installedRevision
   Upgrading	Helm release 升级进行中。Sync 条件为 Unknown(Syncing)。	仍是上一版本
   HealthChecking	Helm release 已应用；控制器正在验证 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. 验证升级进度

   监控滚动升级过程：

   # Check control plane status
   kubectl get kubeadmcontrolplane <kcp-name> -n cpaas-system
   
   # Monitor individual machines
   kubectl get machines -n cpaas-system -l cluster.x-k8s.io/control-plane
   
   # Verify cluster health
   kubectl get nodes

#工作节点升级

工作节点升级通过 MachineDeployment 资源进行管理。

#回滚失败的升级

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

在执行回滚前，需要先理解以下三点：

• 旧 VM 已经不存在。 它们在升级期间已被销毁。回滚会使用旧模板构建一组新的替换机器；它不会恢复原来的 VM。
• 旧的 HCSMachineTemplate 资源必须仍然存在。 在新的滚动发布健康之前，不要删除前一个模板。如果您已经删除了它，请在回滚前从版本控制或备份中重新创建它。
• 只有 pool-managed persistent disks 才能保留节点本地状态。 升级窗口内写入 HCSMachineTemplate.spec.template.spec.dataVolumes[] 的数据会在该 VM 被替换时丢失。写入 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明的磁盘的数据会被保留并重新挂载到替换后的 VM。除非您的运维设计明确依赖节点本地状态，否则应用数据仍应使用外部持久化存储，例如 HCS EVS CSI。

操作步骤：

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

• 工作节点：补丁每个 MachineDeployment，恢复之前的 spec.template.spec.infrastructureRef.name 和 spec.template.spec.version。

• Kube-OVN：如果已升级 Kube-OVN chart，请按升级时相同的方式回滚——先恢复注解，再将 AppRelease 的 chart revision 补丁回去。使用第 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 控制器可能会因为预检检查在不健康的 etcd 上阻塞，而拒绝回滚任何机器。请先恢复 etcd quorum（需要 operator 人工介入），然后再重试回滚。

#其他资源

• Cluster API 升级文档
• Kubernetes 版本偏差策略