#在华为云Stack上升级 Kubernetes

本指南介绍如何在华为云Stack上升级 Kubernetes 集群，在尽量缩短停机时间的同时，保持系统稳定性和数据完整性。

#概览

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

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

#升级顺序

按以下顺序升级 HCS 集群：

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

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

#前提条件

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

• 已完成发行版升级。
• 控制平面可访问。
• 所有节点均运行正常，且处于 Ready 状态。
• 已创建当前的 etcd 备份，并使用受支持的 ACP 备份操作步骤完成验证。
• HCS 环境中已存在使用为目标 ACP 版本发布的 Alauda OS 映像创建的 VM 映像。应用新的 HCSMachineTemplate 时，如果该映像不存在，升级将失败。
• 对于跨越多个 Kubernetes 次要版本的跨版本升级，请预先暂存中间版本的 Core 映像和 VM 映像。请参阅跨版本升级准备。
• 目标 Kubernetes 版本与您的工作负载和附加组件兼容。
• 查看 Kubernetes 升级路径和版本偏差策略。
• 必须在 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明所有需要在替换后保留的节点本地状态，而不是在 HCSMachineTemplate.spec.template.spec.dataVolumes[] 中声明。

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

#控制平面升级

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

对于由使用 Pool 管理的持久磁盘的 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 操作步骤，并在继续之前，使用 phase=Success 验证 cni-kube-ovn AppRelease 已处于目标修订版本。

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 设置为上传到 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 次要版本不匹配。

   如果引用的控制平面 Pool 使用持久磁盘，请保留 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 资源进行管理。

#升级工作节点 Kubernetes 版本

Kubernetes 版本升级要求同时协调更新 MachineDeployment 和底层 VM 模板。

注意：确保 VM 模板的 Kubernetes 版本与 MachineDeployment 中指定的版本匹配。版本不匹配将导致节点加入集群失败。

操作步骤：

1. 更新 Machine 模板

   使用支持目标 Kubernetes 版本的更新后的 imageName，创建新的 HCSMachineTemplate。有关导出、重命名和应用命令，请参阅更改机器基础设施。

2. 为 Kubernetes 1.35 或更高版本创建新的引导模板

   当目标为 Kubernetes 1.35 或更高版本时，在新名称下克隆当前的 KubeadmConfigTemplate，并将所需的 kubelet 补丁设置添加到 /etc/kubernetes/patches/kubeletconfiguration0+strategic.json。有关导出、编辑和应用步骤，请参阅更新引导模板。对于更早版本，除非该版本发布包含其他引导变更，否则跳过此步骤。

3. 更新 MachineDeployment

   修改以下字段：

   • spec.template.spec.version - 目标 Kubernetes 版本

   • spec.template.spec.infrastructureRef.name - 新机器模板名称

   • spec.template.spec.bootstrap.configRef.name - 新引导模板名称；Kubernetes 1.35 或更高版本必需

     kubectl patch machinedeployment <cluster-name>-md-0 -n cpaas-system \
       --type='merge' -p='{"spec":{"template":{"spec":{"version":"<kubernetes-version>","infrastructureRef":{"name":"<new-template>"},"bootstrap":{"configRef":{"name":"<new-bootstrap-template>"}}}}}}'

   该命令包含 Kubernetes 1.35 或更高版本所需的引导引用。如果目标版本更早且没有引导变更，请省略 bootstrap 对象。

4. 监控升级

   验证新节点是否以正确的 Kubernetes 版本加入集群：

   kubectl get nodes

#从失败的第 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 资源必须仍然存在。 在新发布恢复健康之前，不要删除之前的模板。如果已删除，请在尝试同一次要版本模板恢复之前，从版本控制或备份中重新创建它。
• 只有由 Pool 管理的持久磁盘才能保留节点本地状态。 在升级窗口期间写入 HCSMachineTemplate.spec.template.spec.dataVolumes[] 的数据会在替换该 VM 时丢失。写入 HCSMachineConfigPool.spec.configs[].persistentDisks[] 中声明的磁盘的数据将被保留，并重新连接到替换 VM。应用程序数据仍应使用外部持久存储（例如 HCS EVS CSI），除非您的运维设计明确依赖节点本地状态。

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

当 etcd 不健康时，KubeadmControlPlane 控制器可能会阻止替换。请先恢复仲裁，然后再重试任何安全的替换操作。

#其他资源

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