#在 Huawei Cloud Stack 上升级集群

本指南介绍如何在 Huawei Cloud Stack 上升级 Kubernetes 集群，同时最大限度地减少停机时间，并保持稳定性和数据完整性。

#概述

HCS 集群升级涉及多个组件，并遵循结构化方法以确保系统可靠性：

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

#升级顺序

按以下顺序升级 HCS 集群：

1. （前提条件） 首先升级管理集群上的 ACP 平台。这会将 cluster-api-provider-hcs 控制器和相关 CAPI 组件升级到能够识别新架构的版本。只有在管理侧控制器完成滚动更新并进入 Ready 状态后，才能触发业务集群升级。
2. 升级业务集群上的 Distribution Version。请参阅升级集群。
3. 将 Kube-OVN 升级到目标 ACP 版本所需的 chart 版本，并等待 AppRelease 达到 Success。
4. 升级控制平面的 Kubernetes 版本。
5. 将工作节点升级到目标 Kubernetes 版本。

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

#前提条件

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

• Distribution Version 升级已完成。
• 控制平面可访问。
• 所有节点均运行正常，并处于 Ready 状态。
• 已使用受支持的 ACP 备份操作步骤创建并验证最新的 etcd 备份。
• 已将从目标 ACP 版本发布的 Alauda OS 映像创建的 VM 映像放置在 HCS 环境中。如果应用新的 HCSMachineTemplate 时该映像不存在，升级将失败。
• 对于跨越多个 Kubernetes 次要版本的跨版本升级，已预先准备中间版本的 Core 映像和 VM 映像。请参阅跨版本升级准备。
• 目标 Kubernetes 版本与您的工作负载和附加组件兼容。
• 查看 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. 创建更新后的机器模板

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

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

2. 修改模板规格

   修改新模板：

   • 将 metadata.name 设置为 <new-template-name>
   • 从复制的清单中删除服务器生成的元数据和状态字段。
   • 将运行时身份字段留空，包括 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. 部署更新后的模板

   应用新的机器模板：

   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 版本、Kubernetes 版本以及匹配的 CoreDNS、etcd 和 Kube-OVN 版本之间的权威对应关系位于 OS Support Matrix 中。开始操作前，请找到与目标 ACP 版本对应的行；该行提供了以下操作步骤所需的组件值。

ECS 镜像名称不在矩阵中。它是从为目标 ACP 版本发布的 Alauda OS 镜像上传到 HCS 时所使用的名称 — 请参阅下载 Alauda OS — 并且必须将控制平面和工作节点模板中的 HCSMachineTemplate.spec.template.spec.imageName 设置为该名称。

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

CoreDNS 和 etcd 镜像标签仅适用于控制平面，因为 clusterConfiguration 是一个 KubeadmControlPlane 字段。工作节点从新 VM 模板继承容器镜像版本；MachineDeployment 不包含自身的 dns/etcd 标签。Kube-OVN 注解位于 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 补丁。请先将 HCS provider 升级到 v1.0.4 或更高版本，以便其协调完整源以及相关组件仓库的更改。

#升级控制平面 Kubernetes 版本

完成共享的在控制平面之前升级 Kube-OVN 操作步骤，并在继续之前确认 cni-kube-ovn AppRelease 已通过 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 设置为上传到 HCS 的目标 Alauda OS 镜像名称。

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

   • 将运行时身份字段留空，包括 spec.template.spec.providerID 和 spec.template.spec.serverId。VM 创建后，HCS provider 会将 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 名称

   • 当目标为 Kubernetes 1.35 或更高版本时，按照适用于 Kubernetes 1.35 的必需 kubelet 补丁 中的说明，在同一次编辑中更新 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 次要版本不匹配。

   如果所引用的控制平面池使用持久磁盘，请保留 spec.rolloutStrategy.rollingUpdate.maxSurge: 0。删除旧机器后，替换机器必须重新使用相同的固定主机名和磁盘插槽。

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

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

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

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

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

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

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

对于第 1 阶段，请使用在第 1 阶段恢复期间恢复 Kube-OVN 中的 HCS 规则。恢复操作取决于已安装的 provider 版本：当前 provider 会从注解中恢复完整源内容，而旧版 provider 则需要应用早期 chart 修订版本补丁。等待恢复的 AppRelease 通过共享验证后，再更改控制平面清单。

KubeadmControlPlane 控制器可能会在 etcd 不正常时阻止替换。在重试任何安全替换操作之前，请先恢复仲裁。

#其他资源

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