#升级前准备

受支持的升级路径：

在 minor-release policy 层面，ACP 4.1、4.2 和 4.3 都处于 ACP 4.4 release line 的 n-3 直接升级窗口内。此策略并不意味着每一个源 patch 都适用于每一个目标 patch。

仅升级到平台针对当前源 patch 提供的目标 4.4.x 版本。在注册目标 ProductManifest 之后，确认目标版本出现在 Web Console 或 ac adm upgrade 的 availableUpdates 中，并确认 VersionUpgradePath 预检通过。如果未提供任何 4.4.x 目标版本，请使用包含当前源 patch 的更高 4.4.x 目标版本，或者先跟随平台提供的中间目标版本。不要使用显式升级请求，也不要禁用 VersionUpgradePath 来绕过不受支持的源到目标组合。

ACP 4.0.x 超出了 ACP 4.4 的直接升级窗口。请遵循平台提供的中间升级链，并在每一跳都验证 availableUpdates 和 VersionUpgradePath。

#重要说明

• 确保 global cluster 的 control plane 节点上的 /cpaas/minio 目录至少有 120 GB 可用磁盘空间。
• 在升级 global tier 之前，验证所有 workload cluster 都仍然位于目标 Distribution Version 文档中 Kubernetes Support Matrix 所述的 Compatible Versions 范围内。
• 如果任何 workload cluster 超出目标兼容范围，请先升级该 workload cluster，直到其进入该范围，然后再升级 global tier。
• workload cluster 只能升级到 global tier 已经到达的 Distribution Version。

#升级前验证模块稳定性

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

在请求升级之前，请列出目标集群上已安装的 modules，并确认每个 module 都处于 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'

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

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

每个 module 的 PHASE 都必须是 Running，且 deployStatus 不能是 Upgrading、DeployFailed 或 UpgradeFailed。如果某个 module 仍在升级，请等待其达到 Running；如果某个 module 处于 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

#为离线环境下载软件包

一次生产维护窗口通常会在同一窗口内升级 Core、Aligned plugins（与相同 ACP 版本一起发布的 cluster plugins 和 operators）以及正在使用的 Agnostic plugins（独立发布的 cluster plugins 和 operators）。Core 和 Extension 软件包是分开下载的。请在维护窗口前准备好这三类软件包，以便制品同步可以提前完成。

#步骤 1：下载 Core 软件包

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

#步骤 2：下载 ACP 升级到 v4.4

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

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

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

下载之前，请确认 ACP Upgrade to v4.4 出现在场景列表中。

除了 Violet 外，您还可以在 Customer Portal 中进入 Marketplace > Batch Download > Install。在该页面中，从 Your ACP Version 选择目标 Core Package 版本，选择匹配的 Architecture，再从 Scenarios 中选择 ACP Upgrade to v4.4，然后下载这些软件包。

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

下载的文件命名为 <package-name>.<arch>.<version>.tgz，不会重复显示名称。下面每一项都给出了 package name，以便您确认已获得全部十一项：

在发布升级制品之前，请手动将全部十一项软件包复制到解压后的 Core Package 的 plugins/ 目录中。Sync upgrade artifacts 描述了内置 Registry 和外部 Registry 的发布分支。

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

cluster plugins 和 operators 的管理机制不同。在这一步中两者都需要：

• cluster plugins 是全局资源。推送到 global tier 的 cluster plugin 会在平台内每个集群上变为可安装和可升级；每个 cluster plugin 只需推送一次。
• operators 作用域限定为每个集群。建议先将 operator 推送到 global tier，但在某个 workload cluster 升级之前，该集群上也必须提供同一 operator package。

使用步骤 2 中相同的 violet 安装，清点已安装的 Extensions，并发布不属于 ACP Upgrade to v4.4 的软件包。更多信息请参见 Download Packages 和 Upload Packages。

在任何可以访问 平台端点的机器上，运行 violet list 列出当前环境中已安装的 plugins（包括 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 history 和进程列表（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.4 中的某个十一项应用之一，不要使用 violet 重复发布该软件包。应改为通过 Core Package 的 plugins/ 目录使用来自 ACP Upgrade to v4.4 的软件包。仅对其余 Extension 软件包使用 violet push。

请下载您需要的每个软件包，确保在升级窗口开始前它们都已可在本地使用。下一页 Upgrade the global cluster 说明了所选 Registry 路径如何发布 Core 和这十一项手动暂存的软件包，以及 violet 如何发布其他 Extensions。制品发布不会升级任何已运行的 plugin，因此请在维护窗口之前完成此步骤。