Immutable Infrastructure
  • 简体中文

    • 升级集群

    本节提供由 Cluster API 管理的 Kubernetes 集群升级说明。

    目录

    升级概览Distribution Version 与 Kubernetes 版本前提条件阶段 1：升级 ACP Core 和 Distribution Version升级后验证阶段 2：升级 Kubernetes 版本在控制平面之前升级 Kube-OVN确定已安装的 provider 版本应用特定于 provider 版本的操作步骤验证 Kube-OVN AppRelease在 Stage-1 恢复期间恢复 Kube-OVNKubernetes 1.35 所需的 kubelet 补丁跨版本升级准备步骤 1 — 确认 Core 跳跃并预同步中间镜像步骤 2 — 为预配机制准备中间 OS 镜像步骤 3 — 对每个中间 Kubernetes/OS 行应用平台特定操作步骤平台特定说明相关主题

    升级概览

    Immutable Infrastructure 上的集群升级采用两阶段方法：

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

    ACP 产品文档负责阶段 1 的前提条件、受支持的 ACP 升级路径、制品准备和 CVO 操作。本网站负责阶段 2 中 Immutable Infrastructure 的 Kubernetes 和 OS 替换操作。

    Distribution Version 与 Kubernetes 版本

    组件说明由谁管理
    Distribution Version安装在集群上的 ACP Core 版本。ACP 产品文档中记录的 CVO 工作流。
    Kubernetes and OS baseline已验证的 Kubernetes 次版本、组件集以及适用于已安装 ACP 版本的 Alauda OS 镜像。Cluster API 和特定于供应商的阶段 2 操作。

    ACP 的某个次版本发布线在其补丁生命周期内可能提供多个已验证的 Kubernetes 目标。请使用 OS Support Matrix 查看阶段 2 所提供的精确补丁级 Kubernetes、组件和 Alauda OS 镜像值。

    前提条件

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

    阶段 1：升级 ACP Core 和 Distribution Version

    请将 ACP 产品文档作为此阶段的唯一操作步骤负责人：

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

    INFO

    Fleet Essentials 1.0.4 及更高版本可使用 ACP 4.3 及更高版本的 CVO 工作流请求 Distribution Version 升级。该能力仅覆盖阶段 1。Fleet Essentials 不会替换不可变节点，也不会在阶段 2 中执行 Kubernetes 和 Alauda OS 的滚动更新；请使用本网站上的供应商特定 YAML 操作步骤。

    升级后验证

    Distribution Version 升级完成后：

    • 验证集群报告的目标 Distribution Version，且 CVO 不再处于进行中或被阻塞状态。
    • 确认 OS Support Matrix 中存在目标行以及所有必需的中间行。
    • 仅在管理侧 Cluster API provider 运行正常后，继续执行阶段 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 报告目标已安装 revision 且 phase=Success，然后升级控制平面，最后升级 worker 节点。在跨版本升级中，对每个中间 Kubernetes 次版本都重复这种先 Kube-OVN 后控制平面的顺序。

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

    本节作为业务集群和 global 集群的权威 Kube-OVN 操作步骤。对于每个 Kubernetes 和 OS 跳跃，请从匹配的 OS Support Matrix 行中读取 kube-ovn (chart) 版本，完成下面按供应商版本划分的操作步骤，并在更改 KubeadmControlPlane 之前验证得到的 AppRelease。

    请在管理集群上运行 provider 版本检查以及 Cluster 或 infrastructure-cluster 命令。请在正在升级的集群上运行 cni-kube-ovn AppRelease 命令。升级 global 集群时，这两个资源都位于 global 集群上，因此所有命令都使用 global kubeconfig。

    确定已安装的 provider 版本

    不要根据 ACP Distribution Version 推断 provider 版本。请检查管理集群上的 provider AppRelease。资源名称可能不同，因此下面的命令会根据 chart 名称查找 provider，并打印请求的 revision 和已安装的 revision：

    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 结尾的行，以适用者为准。使用已安装的 revision选择对应标签页。如果请求的 revision 和已安装的 revision 不同，或者 provider chart 不是 Success，请在开始集群升级之前先完成或修复 provider 升级。

    Provider完整源码协调本指南保留的旧行为
    Huawei DCSv1.0.22 及更高版本v1.0.21 及更早版本
    Huawei Cloud Stackv1.0.4 及更高版本v1.0.3 及更早版本
    VMware vSpherev1.0.16 及更高版本v1.0.15 及更早版本
    Bare Metalv0.0.1 及更高版本无；v0.0.1 是此操作步骤支持的首个版本。

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

    目标 Kube-OVN chart 版本预期的 spec.source.charts[0].name
    早于 v4.4acp/chart-cpaas-kube-ovn
    v4.4 及更高版本acp/chart-kube-ovn

    如果目标 OS Support Matrix 行使用的 Kube-OVN chart 为 v4.4 或更高版本，请先将 infrastructure provider 升级到上表中的完整源码协调版本，然后再继续。手动修补 Kube-OVN source 不能替代该 provider 升级，因为相同的 provider 版本还会协调所需的 CoreDNS 和 kube-proxy 仓库变更。

    应用特定于 provider 版本的操作步骤

    Huawei DCS

    验证 DCS infrastructure cluster 是否使用 Kube-OVN：

    kubectl get dcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.spec.networkType}{"\n"}'
# Expected output: kube-ovn
    DCS v1.0.22+
    DCS v1.0.21 及更早版本

    在 CAPI Cluster 上更新目标 chart 版本。provider 会根据目标版本选择 chart 名称，并协调完整的 AppRelease source 和 specification。

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

    不要手动修补 AppRelease source。继续执行 验证 Kube-OVN AppRelease。

    Huawei Cloud Stack

    验证 HCS infrastructure cluster 是否使用 Kube-OVN：

    kubectl get hcscluster <cluster-name> -n cpaas-system \
  -o jsonpath='{.spec.networkType}{"\n"}'
# Expected output: kube-ovn
    HCS v1.0.4+
    HCS v1.0.3 及更早版本

    在 CAPI Cluster 上更新目标 chart 版本。provider 会根据目标版本选择 chart 名称，并协调完整的 AppRelease source 和 specification。

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

    不要手动修补 AppRelease source。继续执行 验证 Kube-OVN AppRelease。

    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
    vSphere v1.0.16+
    vSphere v1.0.15 及更早版本

    在 CAPI Cluster 上更新目标 chart 版本。provider 会根据目标版本选择 chart 名称，并协调完整的 AppRelease source 和 specification。

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

    不要手动修补 AppRelease source。继续执行 验证 Kube-OVN AppRelease。

    Bare Metal

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

    验证 infrastructure cluster 是否使用 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

    provider 会根据目标版本选择 chart 名称，并协调完整的 AppRelease source 和 specification。不要手动修补 AppRelease source。

    验证 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-name 边界一致。
    • targetRevision 和 installedRevision 都与 OS Support Matrix 行一致。
    • phase 为 Success。
    • Sync 和 Health 条件均为 True。

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

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

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

    仅当目标 Kubernetes 次版本尚未创建任何控制平面 Machine 时，才使用此恢复方式。如果目标次版本的控制平面 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 v0.0.1+：恢复之前的 cpaas.io/kube-ovn-version annotation。provider 会恢复匹配的 chart 名称、revision 和完整 specification。不要手动修补 source。

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

      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；provider 会协调完整的旧版 specification。

    恢复到之前的目标后，在更改任何控制平面 manifest 之前，重复执行 验证 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 时单独推出该策略。
    • 对于 worker 节点，请创建一个包含更新后文件的新不可变 KubeadmConfigTemplate，然后在与目标版本和 infrastructure template 相同的编辑中更新 MachineDeployment.spec.template.spec.bootstrap.configRef.name。
    • 如果文件使用 contentFrom.secret，请验证所引用的 Secret key 是否包含此参数。较旧的按版本划分的 Secret 不会自动适用于 1.35 的跳跃。

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

    请参阅平台特定指南：

    跨版本升级准备

    当目标 ACP Distribution Version 比集群当前版本高出不止一个 Kubernetes 次版本时，在开始阶段 2 之前需要额外准备。单次次版本升级可跳过本节。

    在 Immutable Infrastructure 上，每个 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 包，并且只将其镜像同步到仓库中。不要仅因为某一行被用作 Kubernetes 或 OS 的过渡步骤，就额外请求一次 Core 升级。

    bash upgrade.sh --only-sync-image

    有关命令选项，请参阅 同步升级制品。

    这会将中间版本的 CoreDNS、etcd 和 Kube-OVN chart 镜像放入仓库，以便分阶段的 Kubernetes 发布在 KubeadmControlPlane 被修补到匹配的 OS Support Matrix 行时能够拉取它们。在 air-gapped 环境中，缺少中间镜像会导致新的控制平面组件无法启动。

    对于必需的 Core 跳跃，请按照 ACP 阶段 1 操作步骤的要求准备并升级 Aligned plugins。对于仅用于 Kubernetes/OS 的中间行，Aligned plugins 不需要额外的 violet push；该中间 Kubernetes 跳跃所使用的 Kube-OVN chart 已由上面的 Core 镜像同步涵盖。

    步骤 2 — 为预配机制准备中间 OS 镜像

    对于每个中间 Kubernetes/OS 行，请将匹配的 OS 镜像（即 OS Support Matrix 行中的 Alauda OS Image Version 值）提供给节点预配机制，以便 Kubernetes 步骤可以依次用每个镜像替换节点：

    • IaaS provider（Huawei DCS、VMware vSphere、Huawei Cloud Stack）：上传 OS 镜像，并按照 OS Support Matrix 行中列出的精确名称将其注册为 VM template（或根据平台注册为 VM image）。
    • Bare metal：将 OS 镜像提供给集群所使用的节点重新预配流程。

    随后，控制平面和 worker 发布将按中间 OS 镜像逐个推进，并与已分阶段准备的 Kubernetes 次版本相匹配，直到集群到达目标 ACP 版本行。

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

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

    平台特定说明

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

    Provider说明状态
    Huawei DCSHuawei Datacenter Virtualization Solution✅ 可用
    Huawei Cloud StackHuawei Cloud Stack✅ 可用
    VMware vSphereVMware vSphere 虚拟化平台✅ 可用
    Bare Metal无虚拟化的裸金属服务器YAML；要求已安装版本中包含 provider v0.0.1+

    相关主题