#升级集群

本节介绍如何升级由 Cluster API 管理的 Kubernetes 集群。

#升级概述

Immutable Infrastructure 上的集群升级分为两个阶段：

1. 阶段 1：通过 CVO 升级 ACP Core 和集群 Distribution Version。
2. 阶段 2：升级 Kubernetes，并使用匹配的 Alauda OS 镜像替换节点。

#Distribution Version 与 Kubernetes 版本

ACP 次要版本系列在其补丁生命周期内可能提供多个经过验证的 Kubernetes 目标版本。有关阶段 2 提供的确切补丁级 Kubernetes 和组件值，请参阅 OS Support Matrix。

#前提条件

• 完成 升级前准备，包括验证源 ACP 版本可以升级到目标 Distribution Version。
• 在开始阶段 2 之前，完成 ACP Core 和 Distribution Version 升级。
• 验证控制平面可访问且运行正常。
• 验证所有节点均处于 Ready 状态。
• 按照特定提供商的操作步骤创建并验证所需的备份。
• 确认有足够的 IP 或机器槽位容量用于滚动替换。

#阶段 1：升级 ACP Core 和 Distribution Version

将 ACP 产品文档作为本阶段的唯一操作步骤来源：

• 升级概述
• 升级前准备
• 升级 global 集群
• 升级业务集群

按照此顺序准备构件和插件包，升级 global 层，然后通过 CVO 将每个业务集群迁移到目标 Distribution Version。不要在阶段 2 中使用中间 Kubernetes 版本跳转来绕过不受支持的 ACP Core 升级路径。

#升级后验证

Distribution Version 升级完成后：

• 验证集群报告目标 Distribution Version，且 CVO 不再处于进行中或阻塞状态。
• 确认 OS Support Matrix 中存在目标行以及所有必需的中间行。
• 仅在管理侧 Cluster API providers 运行正常后，继续执行阶段 2。

#阶段 2：升级 Kubernetes 版本

升级 Distribution Version 后，通过特定提供商的 Cluster API 操作步骤升级 Kubernetes 和 Alauda OS 镜像。

对于 Huawei DCS、Huawei Cloud Stack、VMware vSphere 和裸金属集群，在更改 KubeadmControlPlane 之前，先为当前升级跳转升级 Kube-OVN chart。等待业务集群的 cni-kube-ovn AppRelease 报告目标已安装修订版本和 phase=Success，然后升级控制平面，最后升级工作节点。跨版本升级时，对每个中间 Kubernetes 次要版本重复此 Kube-OVN 优先顺序。

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

将本节作为业务集群和 global 集群的权威 Kube-OVN 操作步骤。对于每个 Kubernetes 和 OS 跳转，从匹配的 OS Support Matrix 行读取 kube-ovn (chart) 版本，完成以下特定提供商版本的操作步骤，并在更改 KubeadmControlPlane 之前验证生成的 AppRelease。

针对管理集群运行提供商版本检查以及 Cluster 或基础设施集群命令。针对正在升级的集群运行 cni-kube-ovn AppRelease 命令。升级 global 集群时，两个资源都位于 global 集群上，因此所有命令都使用 global kubeconfig。

#识别已安装的提供商版本

不要根据 ACP Distribution Version 推断提供商版本。在管理集群上检查提供商 AppRelease。资源名称可能有所不同，因此以下命令会按 chart 名称查找提供商，并打印请求的修订版本和已安装的修订版本：

kubectl -n cpaas-system get apprelease \
  -o custom-columns='APPRELEASE:.metadata.name,CHART:.spec.source.charts[*].name,REQUESTED:.spec.source.charts[*].targetRevision,INSTALLED:.status.charts[*].installedRevision,PHASE:.status.charts[*].phase'

根据具体情况，查找 chart 名称以 chart-cluster-api-provider-dcs、chart-cluster-api-provider-hcs、chart-cluster-api-provider-vsphere 或 chart-cluster-api-provider-baremetal 结尾的行。使用已安装的修订版本选择选项卡。如果请求的修订版本与已安装的修订版本不同，或者提供商 chart 不处于 Success 状态，请先完成或修复提供商升级，再开始集群升级。

Kube-OVN chart 源在 chart 版本 v4.4 处也会发生变化：

如果目标 OS Support Matrix 行使用 Kube-OVN chart v4.4 或更高版本，请先将基础设施提供商升级到表中所列的完整源协调版本，然后再继续。手动 Kube-OVN 源修补不能替代提供商升级，因为相同的提供商版本还会协调所需的 CoreDNS 和 kube-proxy 仓库变更。DCS Self-built VIP 是一个独立的创建时端点功能，需要 DCS Provider v1.0.22+ 和 ACP v4.4+；将现有外部端点更改为内部端点不属于本升级操作步骤。

#应用特定提供商版本的操作步骤

#Huawei DCS

验证 DCS 基础设施集群使用 Kube-OVN：

kubectl get dcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.spec.networkType}{"\n"}'
# Expected output: kube-ovn

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

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

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>"}]'

#Huawei Cloud Stack

验证 HCS 基础设施集群使用 Kube-OVN：

kubectl get hcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.spec.networkType}{"\n"}'
# Expected output: kube-ovn

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

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

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>"}]'

#VMware vSphere

验证 CAPI Cluster 启用了 Kube-OVN 协调：

kubectl get cluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.metadata.annotations.cpaas\.io/network-type}{"\n"}'
# Expected output: kube-ovn

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

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

#Bare Metal

此操作步骤适用于 v1.0.0 及更高版本的 Bare Metal provider。没有可供选择的更早受支持版本流程。

验证基础设施集群使用 Kube-OVN，然后更新 CAPI Cluster 上的目标 chart 版本：

kubectl get baremetalcluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.spec.networkType}{"\n"}'
# Expected output: kube-ovn

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

提供商根据目标版本选择 chart 名称，并协调完整的 AppRelease 源和规格。不要手动修补 AppRelease 源。

#验证 Kube-OVN AppRelease

针对正在升级的集群运行以下命令：

kubectl get apprelease cni-kube-ovn -n cpaas-system \
  -o jsonpath='Chart: {.spec.source.charts[0].name}{"\n"}Target: {.spec.source.charts[0].targetRevision}{"\n"}Installed: {.status.charts.*.installedRevision}{"\n"}Phase: {.status.charts.*.phase}{"\n"}'

kubectl get apprelease cni-kube-ovn -n cpaas-system \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status} ({.reason}){"\n"}{end}'

更改控制平面之前，验证以下所有内容：

• spec.source.charts[0].name 与上述 chart 名称边界匹配。
• targetRevision 和 installedRevision 均与 OS Support Matrix 行匹配。
• phase 为 Success。
• Sync 和 Health 条件均为 True。

正常的阶段顺序为 Upgrading → HealthChecking → Success。不要仅根据 installedRevision 继续操作：它可能在 HealthChecking 期间发生变化，此时 Kube-OVN pod 可能尚未验证为 Ready。如果 AppRelease 达到 DownloadFailed、DeployFailed 或 NotReady，请停止操作并检查其条件消息：

kubectl describe apprelease cni-kube-ovn -n cpaas-system

#Stage-1 恢复期间恢复 Kube-OVN

仅当目标 Kubernetes 次要版本上尚未创建控制平面 Machine 时，才使用此恢复流程。如果目标次要版本的控制平面机器已加入，请保留目标 Kube-OVN 基线，并使用前向恢复或受支持的备份或 DR 恢复操作步骤。

在管理集群中，将 CAPI Cluster 上的 chart 版本恢复为之前的版本：

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

• DCS v1.0.22+、HCS v1.0.4+、vSphere v1.0.16+ 和 Bare Metal v1.0.0+：恢复之前的 cpaas.io/kube-ovn-version 注释。提供商会恢复匹配的 chart 名称、修订版本和完整规格。不要手动修补源。

• DCS v1.0.21 及更早版本，或 HCS v1.0.3 及更早版本，且目标早于 chart v4.4：恢复注释后，在正在恢复的集群上将现有 targetRevision 修补回之前的 chart 修订版本：

  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>"}]'

• vSphere v1.0.15 及更早版本，且目标早于 chart v4.4：仅恢复之前的注释；提供商会协调完整的旧版规格。

恢复之前的目标后，在更改任何控制平面清单之前，重复执行验证 Kube-OVN AppRelease。

#Kubernetes 1.35 所需的 kubelet 修补

当升级跳转目标为 Kubernetes 1.35 或更高版本时，/etc/kubernetes/patches/kubeletconfiguration0+strategic.json 中的 kubelet 修补文件必须包含以下设置：

{
  "imagePullCredentialsVerificationPolicy": "NeverVerify"
}

在 Kubernetes 1.35 中，即使镜像已存在于节点上，也可能执行 kubelet 凭证验证。NeverVerify 告知 kubelet 不要验证这些预拉取镜像的拉取凭证。仅将此字段添加到将在 Kubernetes 1.35 或更高版本上运行的 kubelet 配置中；不要为 Kubernetes 1.34 或更早版本添加此字段。

仅在跳转到 Kubernetes 1.35 或更高版本时应用此更改：

• 对于控制平面节点，在将 spec.version 更改为 1.35 的同一次编辑中，更新 KubeadmControlPlane.spec.kubeadmConfigSpec.files 中的匹配文件。当目标版本仍为 1.34 时，不要单独推出此策略。
• 对于工作节点，创建包含更新文件的新不可变 KubeadmConfigTemplate，然后在更改目标版本和基础设施模板的同一次编辑中更新 MachineDeployment.spec.template.spec.bootstrap.configRef.name。
• 如果文件使用 contentFrom.secret，请验证所引用的 Secret key 包含此参数。较早的特定版本 Secret 不会自动适用于 1.35 跳转。

对于 Kubernetes 1.34 或更早版本，请省略 imagePullCredentialsVerificationPolicy。仅在目标为 Kubernetes 1.35 或更高版本的升级跳转中添加它。

请参阅特定平台指南：

• Huawei DCS
• Huawei Cloud Stack
• VMware vSphere
• Bare Metal

#准备跨版本升级

当目标 ACP Distribution Version 比集群当前版本高出一个以上 Kubernetes 次版本时，必须先进行额外准备，然后才能开始阶段 2。单次次版本升级无需执行本节。

在不可变基础设施上，每个 Kubernetes 次版本都固化在对应的 OS 镜像中，并且每个 Kubernetes 次版本都映射到 OS Support Matrix 中的特定 ACP 版本行。因此，Kubernetes 版本必须通过所需的中间 OS 镜像逐个次版本升级。请将这些 Kubernetes 和 OS 升级跳转与 ACP Core 升级路径分开处理：Distribution Version 必须遵循 CVO 提供的每个源版本到目标版本的升级跳转，而阶段 2 可能需要额外的中间版本行，仅用于升级 Kubernetes 和 OS 镜像。

开始阶段 2 之前，请确定所有中间 Kubernetes 次版本及其对应的 OS Support Matrix 行。另行确认阶段 1 已按照 升级前准备 完成所有必需的 Distribution Version 升级跳转。

#步骤 1 — 确认 Core 升级跳转并预先同步中间版本镜像

如果 CVO 将中间 Distribution Version 纳入受支持的 Core 升级路径，则应在阶段 1 中为该升级跳转完成 ACP 构件准备以及 Core/CVO 升级。对于 ACP 4.0.x 到 4.4 这样的升级路径，这是必需的，且 --only-sync-image 不能替代此操作。在每个 Core 升级跳转中验证 availableUpdates 和 VersionUpgradePath。

完成所有必需的 Core 升级跳转后，阶段 2 中 Kubernetes 和 OS 的逐步升级可能仍需要某些中间 OS Support Matrix 行。对于这些仅用于 Kubernetes/OS 升级的版本行，请下载相应的 Core 软件包，并仅将其中的镜像同步到镜像仓库。不要仅仅因为某个版本行被用作 Kubernetes 或 OS 的升级中间步骤，就额外请求 Core 升级。

bash upgrade.sh --only-sync-image

有关命令选项，请参阅 同步升级构件。

这样一来，中间版本的 CoreDNS、etcd 和 Kube-OVN chart 镜像就会存放在镜像仓库中。当 KubeadmControlPlane 被修补为匹配的 OS Support Matrix 行时，分阶段进行的 Kubernetes 升级便可拉取这些镜像。在隔离网络环境中，如果缺少中间版本镜像，新的控制平面组件将无法启动。

对于必需的 Core 升级跳转，请按照 ACP 阶段 1 操作步骤准备并升级 Aligned 插件。对于仅用于 Kubernetes/OS 升级的中间版本行，无需额外的 Aligned 插件 violet push；该中间 Kubernetes 升级跳转所用的 Kube-OVN chart 已包含在上述 Core 镜像同步中。

#步骤 2 — 为置备机制暂存中间版本 OS 镜像

对于每个中间 Kubernetes/OS 版本行，请确保节点置备机制可以使用该 ACP 版本发布的 Alauda OS 镜像，以便在 Kubernetes 升级步骤中依次使用每个镜像替换节点：

• IaaS 提供商（Huawei DCS、VMware vSphere、Huawei Cloud Stack）：上传 OS 镜像并将其注册为 VM 模板（或 VM 镜像，具体取决于平台）。记录注册时使用的名称 — machine template 会引用该名称。
• 裸金属：确保节点重新置备流程可以使用 OS 镜像。

随后，控制平面和工作节点将按照已暂存的 Kubernetes 次版本，逐个升级到中间 OS 镜像，直至集群达到目标 ACP 版本行。

#步骤 3 — 对每个中间 Kubernetes/OS 版本行执行特定平台的操作步骤

依次对每个中间 Kubernetes/OS 版本行重复执行特定平台的阶段 2 操作步骤，并使用 OS Support Matrix 中该行对应的 Kube-OVN、KubeadmControlPlane 和 MachineDeployment 值。对于每个升级跳转，请先升级 Kube-OVN 并等待 phase=Success，然后升级控制平面，最后升级工作节点。升级到 Kubernetes 1.35 时，还需将必需的 kubelet 补丁应用到控制平面和工作节点的引导配置中。完成整个升级跳转后，再开始下一个升级跳转。所有中间升级跳转均成功后，对目标版本行再执行一次相同的操作步骤。

#特定于平台的说明

选择您的平台以查看详细的升级说明：

#相关主题

• 创建集群
• 管理节点
• 基础设施资源