#升级前准备

支持的升级路径：

在次要版本策略层面，ACP 4.2、4.3 和 4.4 均处于 ACP 4.5 发布系列的 n-3 直接升级窗口内。此策略并不意味着每个源修订版本都可以升级到每个目标修订版本。

仅升级到平台针对当前源修订版本提供的 4.5.x 目标版本。注册目标 ProductManifest 后，请确认目标版本显示在 availableUpdates 中（可在 Web Console 或 ac adm upgrade 中查看），并确认 VersionUpgradePath 预检查通过。如果未提供任何 4.5.x 目标版本，请使用包含当前源修订版本的更高 4.5.x 目标版本，或先按照平台提供的中间目标版本进行升级。请勿使用显式升级请求或禁用 VersionUpgradePath 来绕过不受支持的源版本到目标版本组合。

ACP 4.1.x 及更早版本不在 ACP 4.5 的直接升级窗口内。请按照平台提供的中间升级链进行升级，并在每个跳转点验证 availableUpdates 和 VersionUpgradePath。

#重要说明

• 确保 global 集群控制平面节点上的目录 /cpaas/minio 至少有 120 GB 的可用磁盘空间。
• 在升级 global 层之前，确认所有业务集群均处于 Kubernetes 支持矩阵 中记录的目标 Distribution Version 的兼容版本范围内。
• 如果任何业务集群超出目标兼容范围，请先升级该业务集群，直到其进入该范围，然后再升级 global 层。
• 业务集群只能升级到 global 层已达到的 Distribution Version。

#升级前验证模块稳定性

集群升级预检要求目标集群上已安装的每个 Core 和 Aligned 插件模块均处于稳定状态。如果任一此类模块正在安装、升级或处于失败状态，ModuleInfoStable 和 ClusterModuleStable 预检会阻止升级，直到问题得到解决。常见原因是独立插件升级在请求集群升级时仍在运行。

在请求升级之前，列出目标集群上已安装的模块，并确认每个模块均处于 Running 阶段：

kubectl get moduleinfo -l cpaas.io/cluster-name=<cluster> \
  -o custom-columns='MODULE:.metadata.labels.cpaas\.io/module-name,CURRENT:.status.version,TARGET:.spec.version,PHASE:.status.phase'

同时确认集群模块本身不处于部署或升级失败状态：

kubectl get clustermodule <cluster> -o jsonpath='{.status.base.deployStatus}{"\n"}'

每个模块的 PHASE 必须为 Running，并且 deployStatus 不得为 Upgrading、DeployFailed 或 UpgradeFailed。如果模块仍在升级，请等待其达到 Running；如果模块处于 Failed 或 Blocked 状态，请先解决问题，再请求集群升级。

#Kubernetes 1.35 或更高版本的节点就绪性

如果目标版本为 ACP 4.4 或更高版本、会将集群升级到 Kubernetes 1.35 或更高版本，并且报告了要求管理员确认节点就绪性的确认门槛，请在确认该门槛之前，验证将运行目标集群的每个生产节点。

通过 SSH 或环境中可用的其他管理员节点访问方式登录每个节点，并直接在节点操作系统上运行以下检查。所使用的账户和凭据取决于集群节点的置备方式。

验证 Linux 内核版本：

uname -r

内核必须为 5.8 或更高版本，并且还必须符合目标版本的 ACP 支持的操作系统和内核矩阵。

验证节点使用 cgroup v2：

stat -fc %T /sys/fs/cgroup/

预期输出为：

cgroup2fs

对于 Alauda OS 集群，Kubernetes 通过替换节点进行升级。在升级到 Kubernetes 1.35 或更高版本时，还需将所需的 kubelet 补丁应用到控制平面和工作节点引导配置。

#下载离线环境的软件包

生产维护窗口通常会在同一窗口中升级 Core、Aligned 插件（与同一 ACP 版本一起发布的集群插件和 operator）以及正在使用的 Agnostic 插件（独立发布的集群插件和 operator）。Core 和 Extension 软件包需要分别下载。在维护窗口前准备好这三组软件包，以便尽早完成制品同步。

#步骤 1：下载 Core 软件包

从 Customer Portal 下载与目标架构匹配的 4.5 Core Package。Core Package 仅包含 Core 制品；不包含任何 Aligned 或 Agnostic Extension 软件包。

#步骤 2：下载 ACP Upgrade to v4.5

使用 Violet v4.2.13 或更高版本直接下载场景软件包。运行 violet version 验证版本，并使用 violet ac login 登录 Customer Portal。有关安装和登录说明，请参阅下载软件包。

将 <target-platform-version> 设置为 Core Package 的确切 ACP Distribution Version，例如 v4.5.0。将 <arch> 设置为 amd64、arm64 或 hybrid，以匹配 Core Package。先列出场景，然后下载 ACP Upgrade to v4.5：

violet ac scenarios --arch=<arch> --platformVersion=<target-platform-version>
violet ac download-app --arch=<arch> --platformVersion=<target-platform-version> --scenario="ACP Upgrade to v4.5"

确认 ACP Upgrade to v4.5 出现在场景列表中，然后再下载。

也可以不使用 Violet，而是在 Customer Portal 中转到 Marketplace > Batch Download > Install。在页面中，从 Your ACP Version 选择目标 Core Package 版本，选择匹配的 Architecture，从 Scenarios 中选择 ACP Upgrade to v4.5，然后下载软件包。

此软件包集提供以下 Aligned 应用的目标版本软件包。这些软件包与 Core Package 分开。

下载的文件名称为 <package-name>.<arch>.<version>.tgz，其中不包含显示名称。下面的每一项都提供了软件包名称，便于确认已收到全部 11 个软件包：

发布升级制品前，手动将全部 11 个软件包复制到解压后的 Core Package 的 plugins/ 目录中。同步升级制品介绍了内置 Registry 和外部 Registry 的发布分支。

#步骤 3：盘点范围内每个集群上的其他 Extensions

集群插件和 operator 由不同的机制管理。本步骤需要同时处理两者：

• 集群插件是全局资源。推送到全局层级的集群插件会在平台中的每个集群上变为可安装和可升级；每个集群插件只需推送一次。
• Operator的作用域限定为每个集群。建议先将 operator 推送到全局层级，但在升级某个业务集群之前，必须确保该 operator 软件包已在该集群上可用。

使用步骤 2 中相同的 violet 安装来盘点已安装的 Extensions，并发布不属于 ACP Upgrade to v4.5 的软件包。有关更多信息，请参阅下载软件包和上架软件包。

在任何可访问 平台端点的计算机上，运行 violet list，列出当前环境中已安装的插件（包括 Aligned 和 Agnostic），并将结果导出到 ./apps.yaml：

violet list \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --output-file "./apps.yaml"

优先使用 --platform-token，而不是 --platform-password，以避免在 shell 历史记录和进程列表中暴露密码（ps aux）。

此基于令牌的盘点流程要求使用 Violet v4.2.13 或更高版本。较早版本可能会失败并显示 failed to get user info from platform server；请先升级 Violet，然后再继续。

#步骤 4：下载其他 Extension 软件包

将导出的 apps.yaml 文件导入 Customer Portal，使软件包列表与集群当前运行的内容保持一致。下载集群所使用的其他 Aligned 和 Agnostic Extensions 的匹配目标版本软件包。

如果结果中包含 ACP Upgrade to v4.5 中的 11 个应用之一，请勿使用 violet 发布该应用的重复软件包。应通过 Core Package 的 plugins/ 目录使用 ACP Upgrade to v4.5 中的软件包。仅对其余 Extension 软件包使用 violet push。

下载升级所需的每个软件包，确保在升级窗口开始前所有软件包都已在本地可用。下一页升级 global 集群介绍了所选 Registry 路径如何发布 Core 和手动暂存的 11 个软件包，以及 violet 如何发布其他 Extensions。制品发布不会升级任何已在运行的插件，因此请在维护窗口前完成发布。