#升级前准备

支持的升级路径：

• 从 4.0 → 4.3
• 从 4.1 → 4.3
• 从 4.2 → 4.3

开始之前，请确保当前平台版本在支持的升级范围内。

#重要说明

• 确保 global 集群控制平面节点上的目录 /cpaas/minio 至少有 120 GB 可用磁盘空间。
• 将 global 层升级到 ACP 4.3 之前，所有业务集群必须处于 Kubernetes Support Matrix 中记录的 ACP 4.3 兼容版本范围内。
• 如果任何业务集群不在此兼容范围内，请先升级该业务集群，使其进入 ACP 4.3 兼容范围，然后再升级 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 状态，请先解决问题，再请求集群升级。

#下载离线环境所需的软件包

生产环境的维护窗口通常会同时升级 Core、Aligned 插件（与同一 ACP 版本一同发布的集群插件和 operator），以及正在使用的 Agnostic 插件（独立发布的集群插件和 operator）。升级开始前，请为每个已安装的 Aligned 插件准备好目标版本的软件包。还请准备好计划在同一维护窗口升级的 Agnostic 插件，尽管这些插件不会阻止 CVO 升级。延后升级 Agnostic 插件往往会导致之后需要安排第二个维护窗口。

#步骤 1：下载 Core 软件包

从 Customer Portal 下载 Core Package。Core 软件包仅包含 upgrade.sh 为由 CVO 驱动的 Core 升级所准备的 Core 工件。

Core 软件包不包含 Aligned 插件软件包，即使 CVO 知道哪些 Aligned 插件版本与目标 ACP 版本相对应。必须从 Customer Portal 单独下载 Aligned 插件软件包，并使用 violet 推送；下一步将介绍此工作流程以及 Agnostic 插件的相关流程。

#步骤 2：盘点范围内每个集群上的插件

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

• 集群插件是全局资源。推送到 global 层的集群插件可在平台中的每个集群上安装和升级；每个集群插件只需推送一次。
• operator按集群范围管理。建议先将 operator 推送到 global 层，但在每个业务集群升级前，同一 operator 软件包必须在该集群上可用。

前往 Customer Portal 中的 CLI Tools 部分，下载 violet 工具。上传 Aligned 和 Agnostic 插件软件包需要使用 violet。有关 violet 的详细信息，请参阅上架软件包。

在任何可访问 平台端点的计算机上，运行 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）。

#步骤 3：同步 Customer Portal 软件包列表

将导出的 apps.yaml 文件导入 Customer Portal，使软件包列表与集群当前运行的软件保持一致。随后，门户会提供匹配的目标版本软件包供下载，包括 Core、Aligned 插件以及集群正在使用的 Agnostic 插件。

请下载所需的所有软件包，确保在维护窗口开始前它们都已在本地准备就绪。下一页升级 global 集群介绍如何使用 upgrade.sh 和 violet 将这些软件包推送到平台。推送操作会将镜像上传到 registry，并在平台目录中注册目标版本，使其可供安装或升级；此操作不会升级任何已在运行的插件，因此可以在维护窗口开始前的任何时间完成。

violet push <path/to/directory/only_put_topolvm_plugin_here> \
  --platform-address "https://example.com" \
  --platform-token "<platform_token>" \
  --clusters "cluster-a,cluster-b"