#升级前准备

支持的升级路径：

在次版本发布策略层面，ACP 4.1、4.2 和 4.3 均位于 ACP 4.4 发布线的 n-3 直接升级窗口内。此策略并不意味着每个源补丁都可以升级到每个目标补丁。

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

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

#重要说明

• 确保 global cluster 的控制平面节点上的 /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 kernel 版本：

uname -r

kernel 必须是 5.8 或更高版本，并且还必须位于目标发行版的 ACP 支持的操作系统和 kernel 矩阵范围内。

验证节点是否使用 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 Package

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

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

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

将 <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 分开：

• Alauda Container Platform Web Console
• Alauda Container Platform Web Console Central
• Alauda Container Platform Marketplace Web Console
• Alauda Container Platform Helm Application Catalog
• Alauda Container Platform Observability Essentials
• Alauda Container Platform Essentials
• Alauda Container Platform Cluster Essentials
• Alauda Container Platform GatewayAPI Plugin
• Alauda Container Platform Monitoring for Prometheus
• Alauda Language Pack for Chinese
• Alauda Container Platform Networking for Calico

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

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

Cluster plugins 和 operators 由不同机制管理。在这一步中，两者都需要处理：

• Cluster plugins 是全局资源。推送到 global 层的 cluster plugin 会变成平台内每个集群上都可安装和升级的资源；每个 cluster plugin 只需推送一次。
• Operators 作用域限定为每个集群。将 operator 推送到 global 层是推荐的起点，但在升级该集群之前，同一个 operator 软件包必须已在每个业务集群上可用。

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

在任何能够访问 平台端点的机器上，运行 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.4 中的 11 个应用之一，不要使用 violet 重复发布该软件包。请改为通过 Core Package 的 plugins/ 目录使用 ACP Upgrade to v4.4 中的软件包。仅对其余 Extension 软件包使用 violet push。

请下载所有后续升级所需的软件包，确保在升级窗口开始前它们都已可本地获取。下一页 升级 global cluster 说明了所选 Registry 路径如何发布 Core 和那 11 个手动预置的软件包，以及 violet 如何发布其他 Extensions。制品发布不会升级任何已在运行的插件，因此请在维护窗口之前完成该步骤。