#升级前准备

支持的升级路径：

• 从 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 plugins（与同一 ACP 版本一起发布的集群插件和 operators）以及正在使用的 Agnostic plugins（独立发布的集群插件和 operators）。在升级开始之前，请准备集群当前使用的所有软件包，即使从技术上讲某个 Agnostic plugin 升级是可选的。若在维护窗口内暂缓某个 Agnostic plugin，往往会在之后被迫再开一个维护窗口。

#步骤 1：下载 Core 包

从 customer portal 下载 Core Package。Core 包仅包含 upgrade.sh 会为由 CVO 驱动的 Core 升级准备的 Core 工件。

尽管 CVO 知道哪些 Aligned plugin 版本对应目标 ACP 发行版，但 Core 包并不包含 Aligned plugin 包。Aligned plugin 包必须单独从 customer portal 下载，并使用 violet 上架；下一步将介绍这套流程以及 Agnostic plugins。

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

集群插件和 operator 由不同机制管理。在这一步中，两者都需要处理：

• 集群插件是全局资源。推送到 global 层的集群插件会成为平台内每个集群都可安装和升级的对象；每个集群插件只需上架一次。
• Operators 按集群作用域管理。将 operator 推送到 global 层是推荐的起点，但在某个业务集群升级之前，该集群上必须也可用相同的 operator 包。

前往 customer portal 中的 CLI Tools 部分，下载 violet 工具。上传 Aligned 和 Agnostic plugin 包需要使用 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，使软件包列表与集群当前运行的内容保持一致。随后，portal 会提供匹配目标版本的软件包——Core、Aligned plugins，以及你的集群正在使用的 Agnostic plugins——供下载。

请下载你将需要的所有软件包，确保在升级窗口开始之前它们都已在本地可用。下一页 升级 global 集群 说明了 upgrade.sh 和 violet 如何将这些软件包推送到平台中。该推送会把镜像上传到 registry，并在平台 catalog 中注册目标版本，使其可用于安装或升级；它不会升级任何已在运行的插件，因此可以在维护窗口之前的任意时间完成。

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