#在 Huawei Cloud Stack 上升级集群

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

#概述

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

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

#升级顺序

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

1. （前置条件） 先在管理集群上升级 ACP 平台。这会将 cluster-api-provider-hcs controller 及相关 CAPI 组件升级到能够理解新 schema 的版本。仅当管理侧 controller 已完成滚动发布并变为 Ready 后，才触发业务集群升级。
2. 升级业务集群上的 Distribution Version。请参见 升级集群。
3. 将 Kube-OVN 升级到目标 ACP 发布版本所需的 chart 版本，并等待 AppRelease 变为 Success。
4. 升级控制平面 Kubernetes 版本。
5. 将工作节点升级到目标 Kubernetes 版本。

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

#前提条件

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

• Distribution Version 升级已完成。
• 控制平面可达。
• 所有节点健康且处于 Ready 状态。
• 已使用受支持的 ACP 备份流程创建并验证了当前 etcd 备份。
• 目标 VM 镜像已存在于 HCS 环境中，且其名称与 OS Support Matrix 对应行中的 Alauda OS 镜像版本 值相同。如果在应用新的 HCSMachineTemplate 时镜像不存在，升级将失败。
• 对于跨越多个 Kubernetes minor 版本的跨版本升级，已预先准备好中间版本的 Core 镜像和 VM 镜像。请参见 跨版本升级准备。
• 目标 Kubernetes 版本与你的工作负载和 add-ons 兼容。
• 检查 Kubernetes 升级路径和版本偏差策略。
• 任何必须在替换后继续保留的节点本地状态，都应声明在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中，而不是 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中。

初始部署请参见 创建集群 指南。

#控制平面升级

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

对于由使用池管理持久盘的 HCSMachineConfigPool 支持的 HCS 控制平面，在升级期间请保持 KubeadmControlPlane.spec.rolloutStrategy.rollingUpdate.maxSurge: 0。持久盘绑定到固定的 (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 中删除由服务器生成的元数据和 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 的 image tag 仅适用于控制平面，因为 clusterConfiguration 是 KubeadmControlPlane 的字段。工作节点从新的 VM 模板继承容器镜像版本；MachineDeployment 不携带自己的 dns / etcd tag。Kube-OVN annotation 位于 Cluster 资源上，而不是 KubeadmControlPlane 上，因为 HCS provider 会独立于 Kubernetes 控制平面滚动来监视它。

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

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

对于目标为 Kube-OVN v4.4+ 的场景，不要使用传统的直接 targetRevision patch。请先将 HCS provider 升级到 v1.0.4 或更高版本，以便它能够协调完整源和相关组件仓库的变更。

#升级控制平面 Kubernetes 版本

完成共享的 在控制平面之前升级 Kube-OVN 操作步骤，并在继续之前确认 cni-kube-ovn AppRelease 已达到目标 revision 且 phase=Success。

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

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

   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 镜像版本 值。

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

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

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

2. 使用目标 Kubernetes 值 patch KubeadmControlPlane

   一次性编辑 KubeadmControlPlane 资源，以保持 spec.version、CoreDNS image tag、etcd image tag 以及基础设施模板引用与同一个 Alauda OS 发布保持一致：

   • spec.version ← OS Support Matrix 对应行中的 Kubernetes 版本

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

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

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

   • 当目标为 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 的 image tag 必须与 Kubernetes 版本一起变更，因为它们基于同一个 Alauda OS 发布构建；如果保留为之前的值，可能会导致 CoreDNS 和 etcd pod 与新的 Kubernetes minor 版本不匹配。

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

3. 验证升级进度

   监控滚动升级过程：

   # 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 资源进行管理。

#从失败的 Phase 2 升级中恢复

不要将 Kubernetes minor 降级视为普通回滚。请根据滚动发布阶段选择恢复路径：

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

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

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

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

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

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

#其他资源

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