#为业务集群升级 Alauda OS 上的 Kubernetes

本节介绍如何升级由 Cluster API 管理的 Alauda OS 业务集群上的 Kubernetes。

#升级概述

Alauda OS 上的集群升级分为两个阶段：

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

有关 Distribution Version 与 Kubernetes 和 OS 基线之间的关系，请参阅 Distribution Version 与 Kubernetes Version。阶段 2 中提供的、针对特定补丁版本的 Kubernetes 和组件确切值，请参阅 OS Support Matrix。

#前提条件

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

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

使用以下页面作为本阶段的唯一操作步骤来源：

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

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

#升级后验证

Distribution Version 升级完成后：

• 验证集群报告的 Distribution Version 为目标版本，且 CVO 不再处于进行中或阻塞状态。
• 确认 OS Support Matrix 中存在目标行和所有必需的中间行。
• 只有在管理端的 Cluster API 提供商均运行正常后，才能继续进行阶段 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 minor 版本重复此 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

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

验证基础设施集群使用 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

#在阶段 1 恢复期间恢复 Kube-OVN

仅当目标 Kubernetes minor 版本上尚未创建任何控制平面 Machine 时，才能使用此恢复流程。如果目标 minor 版本的控制平面 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 annotation。提供商会恢复匹配的 chart 名称、修订版本和完整规范。请勿手动修补源代码。

• DCS v1.0.21 及更早版本或 HCS v1.0.3 及更早版本，且目标早于 chart v4.4：恢复 annotation 后，在正在恢复的集群上将现有 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：仅恢复先前的 annotation；提供商会协调完整的旧版规范。

恢复先前目标后，在更改任何控制平面清单之前，重复执行验证 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 之前完成额外准备。单个小版本的升级可跳过本节。

在 Alauda OS 上，每个 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 跳转后，某些中间 OS Support Matrix 行可能仍仅用于阶段 2 中 Kubernetes 和 OS 的顺序推出。对于这些仅涉及 Kubernetes/OS 的版本行，请下载相应的 Core 软件包，并仅将其中的镜像同步到 registry。请勿仅因某个版本行被用作 Kubernetes 或 OS 的过渡版本而请求额外的 Core 升级。

bash upgrade.sh --only-sync-image

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

此操作会将中间版本的 CoreDNS、etcd 和 Kube-OVN chart 镜像置于 registry 中，以便在将 KubeadmControlPlane 修补为匹配的 OS Support Matrix 行时，分阶段的 Kubernetes 推出可以拉取这些镜像。在 air-gapped 环境中，缺少中间镜像会导致新的控制平面组件无法启动。

对于必需的 Core 跳转，请按照阶段 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 会引用该名称。
• Bare Metal：使 OS 镜像可供集群使用的节点重新置备流程使用。

随后，控制平面和工作节点会依次使用中间 OS 镜像进行推出，并与暂存的 Kubernetes 小版本匹配，直到集群达到目标 ACP 版本行。

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

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

#特定于平台的说明

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

#相关主题

• 在 Alauda OS 上创建集群
• 管理 Alauda OS 集群上的节点
• 基础设施资源