#升级前准备

支持的升级路径：

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

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

#重要说明

• 确保 global cluster 控制平面节点上的目录 /cpaas/minio 至少有 120 GB 的可用磁盘空间。
• 在将 global tier 升级到 ACP 4.3 之前，所有 workload cluster 必须保持在 Kubernetes Support Matrix 中记录的 ACP 4.3 兼容版本范围内。
• 如果某个 workload cluster 超出该兼容范围，请先升级该 workload cluster，直到其进入 ACP 4.3 兼容范围后，再升级 global tier。
• workload cluster 只能升级到 global tier 已经达到的 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 发布版本。Aligned 插件包必须单独从 Customer Portal 下载，并使用 violet 推送；下一步会介绍该流程以及 Agnostic 插件的处理方式。

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

Cluster plugin 和 operator 的管理机制不同。在这一步中，两者都需要：

• Cluster plugin 是全局资源。推送到 global tier 的 cluster plugin 会变成平台中每个集群都可安装和升级；每个 cluster plugin 只需推送一次。
• Operator 作用域限定为单个集群。将 operator 推送到 global tier 是推荐的起点，但在某个 workload cluster 升级之前，该集群上也必须可用同一个 operator 包。

进入 Customer Portal 中的 CLI Tools 部分并下载 violet 工具。上传 Aligned 和 Agnostic 插件包需要使用 violet。有关 violet 的更多信息，请参见 Upload Packages。

在任何一台可以访问 平台端点的机器上，运行 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 cluster 介绍了 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"