#升级 global 集群的分发版本

#同步升级工件

时间：维护窗口前的任意时间。此步骤会将工件上传到 Registry，不会更改集群状态。

首先，记录已配置的 Registry 地址，并确定平台使用的是内置 Registry 还是外部 Registry：

kubectl get productbase base \
  -o jsonpath='{.spec.registry.address}{"\t"}{.spec.registry.external}{"\n"}'

对于平台内置 Registry，第二个值为 false；对于外部 Registry，第二个值为 true。将目标 Aligned 软件包复制到 plugins/ 后，再选择发布命令。

Core Package 不包含 ACP Upgrade to v4.5 中的 Aligned 软件包。将升级前准备中列出的十一个单独下载的软件包复制到解压后的 Core Package 的 plugins/ 目录中。对每个软件包分别运行以下命令：

cp <path-to-upgrade-extension-package> ./plugins/

同步前，请确认该目录包含全部十一个软件包：

ls -1 ./plugins/

根据 ProductBase.spec.registry.external 的值，按照相应分支发布暂存的 payload。

对于平台内置 Registry（false），请在解压后的 Core Package 目录中以仅同步模式运行 upgrade.sh：

bash upgrade.sh --only-sync-image

--only-sync-image 会上传 Core 镜像以及您手动放入 plugins/ 的软件包，但不会部署集群版本 operator，也不会更改正在运行的应用。CVO 将在维护窗口内的后续步骤中部署 — 请参阅部署集群版本 operator。

对于外部 Registry（true），不要将 --only-sync-image 作为已发布的证明。upgrade.sh 会自动跳过镜像同步。请从目标 Core Package 的 installer/ 目录开始，按照准备目标版本 payload，同时运行 res/upload.sh all 和 res/upload.sh necessary。两种模式可以按任意顺序运行，但都必须成功。

所选发布路径会使基于 CVO 的工作流所需的工件可用，包括：

对于 ACP Upgrade to v4.5 中的十一个 Aligned 原生应用，始终将软件包暂存到 plugins/。内置 Registry 路径会通过 upgrade.sh --only-sync-image 发布这些软件包；外部 Registry 路径则通过 res/upload.sh all 发布。CVO 仅会升级已安装的原生应用；为未安装的原生应用发布软件包并不会安装该应用。

对于从 violet list 清单下载的其他软件包，请使用 violet push：

# Publish another cluster plugin to the global tier
violet push <path-to-other-cluster-plugin-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>"

# Publish another operator to global and each workload cluster that runs it
violet push <path-to-other-operator-package> \
  --platform-address "https://<your-platform-domain>" \
  --platform-token "<platform_token>" \
  --clusters "global,<workload-cluster-1>,<workload-cluster-2>"

建议在 global 窗口期间，将每个 operator 软件包推送到每个 集群。如果 global 窗口已结束，而您发现某个业务集群缺少 operator 软件包，仍可在升级该业务集群之前将软件包推送到该集群 — 请参阅升级业务集群。

Registry 的行为取决于环境配置方式：

当目标 Registry 不是平台默认 Registry 时，请添加 Registry 参数：

工件验证会将 plugins/ 中存在的每个软件包与目标 Core Package 预期的版本进行比较，若版本不匹配则失败。它不会验证软件包集合是否完整：从未暂存的软件包不会被检查，运行会继续。请先根据下载 ACP Upgrade to v4.5确认十一个软件包，再依赖验证成功的结果。

运行升级前检查之前，请确认 Registry 配置仍然正确：

kubectl get productbase base \
  -o jsonpath='{.spec.registry.address}{"\t"}{.spec.registry.external}{"\n"}'

将所选发布命令成功完成，以及 Registry 管理界面或 API 中的相关信息，作为阶段 1 的证据。请确认预期的目标仓库和标签均已存在，并将已发布的 Extension 集合与导出到 apps.yaml 的已安装清单进行比较。不要将 ProductBase.status.artifacts 作为目标版本的零输出门槛：它表示当前目录，其中可以合理包含可选或未安装软件包的 Absent 条目。

#运行升级前检查

时间：维护窗口前 1–2 周，以便在窗口开启前有时间解决所有阻塞项。

以升级前检查模式运行 upgrade.sh：

bash upgrade.sh --preflight

升级前检查为只读操作 — 它会验证升级准备情况，不会更改集群状态。

resolve desired release: get ProductManifest for version "<target-version>": no matches for kind "ProductManifest" in version "config.alauda.io/v1"

升级前检查会返回两部分内容：

默认检查集包括：

• ResourcePatchUpgradeable
• ClusterVersionUpgradeable
• AdminAckRequired
• VersionUpgradePath
• KubernetesVersionSupported
• DockerRuntimeUnsupported
• ClusterRunning
• ClusterModuleStable
• ControlPlaneStaticPodsPresent
• CustomEtcdBackupCronJobsAbsent
• CRIUpgradePodsAbsent
• ModuleInfoStable
• PlatformLicense

#处理升级前检查阻塞项

时间：维护窗口前；升级前检查一旦报告阻塞项，就应立即处理。

在经过定制的环境中，首次运行升级前检查就全部通过并不常见。请将解决阻塞项视为准备阶段的一部分，而非例外情况 — 这正是要提前一到两周运行升级前检查的原因。

如果任何检查未通过，请勿开启维护窗口。请根据升级故障排除解决每个阻塞项，其中涵盖：

• ResourcePatchUpgradeable — 在经过定制的环境中最常见的阻塞项，以及所需的目标版本豁免。
• 其他常见阻塞项 — KubernetesVersionSupported、VersionUpgradePath、ClusterRunning、DockerRuntimeUnsupported 和模块稳定性。
• 管理员确认门槛 — AdminAckRequired 失败时的处理方式。

不要强行绕过失败的检查进行升级。VersionUpgradePath、KubernetesVersionSupported 和 AdminAckRequired 是受支持升级路径本身的门槛。如果无法解决阻塞项，请在继续之前联系技术支持。

#部署集群版本 operator

时间：维护窗口开始时。

以跳过同步模式运行 upgrade.sh。由于已在同步升级工件中上传工件，因此跳过同步：

bash upgrade.sh --skip-sync-image

此操作会部署或更新集群版本 operator（CVO），并完成剩余准备工作。下一步请求升级后，CVO 将驱动 Core 和 Aligned 插件升级。

命令完成后，请检查目标 ProductManifest，再请求升级：

kubectl get productmanifest v<target-version> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl get productmanifest v<target-version> -o json | jq -r '
  .status.artifacts[] as $artifact
  | $artifact.channels[]
  | select(.artifactStatus != "Ready")
  | [$artifact.name, .channel, .tag, .artifactStatus]
  | @tsv'

每个工件的输出用于诊断，不要求为空。目标清单可能包含可选、Agnostic 或未安装的条目，这些条目未处于 Ready 状态也可能是正常情况。请将输出与已安装的 Core 和 Aligned 清单进行比较。对于已安装的 Aligned ModulePlugin，如果对应的目标 ModulePluginConfig 所属的 channel 未处于 Ready 状态，请检查该资源：

kubectl get modulepluginconfig <modulepluginconfig-name> -o yaml

请使用目标 ProductManifest 中的组件名称和 channel 标签，或 ClusterVersionShadow 错误中报告的名称，来识别 ModulePluginConfig。此名称中的组件版本不一定是 ACP Distribution Version。不要仅凭 artifactStatus: Absent 就认定 Registry manifest 缺失；请使用 ModulePluginConfig 条件及其 .spec.image，以区分 manifest 缺失与身份验证、CA、网络或软件包内容问题。

#请求升级

部署集群版本 operator 后，可通过以下任一入口请求升级。这些入口的功能相同；请选择符合您运维模式的入口。

平台在 Web Console 中提供两个集群管理界面。Web Console 是平台内置的界面，也是默认入口。Web Console (Fleet Essentials) 是较新的集群管理界面，通过独立的集群插件提供，必须先安装才能使用。

# Request upgrade to the highest version currently published in availableUpdates
ac adm upgrade --cluster=global --to-latest

# Request upgrade to a specific target version
ac adm upgrade --cluster=global --to=<target-version>

# Show summary, preflight, and stage progress for the global cluster upgrade
ac adm upgrade status --cluster=global

kubectl patch cvsh global -n cpaas-system --type merge -p '{
  "spec": {
    "desiredUpdate": {
      "version": "<target-version>"
    }
  }
}'

kubectl edit cvsh global -n cpaas-system

spec:
  desiredUpdate:
    version: <target-version>

#观察执行情况

使用以下命令检查总体状态：

kubectl get cvsh -n cpaas-system

重要状态字段：

请先关注以下条件：

如果 Stalled=True，请参阅升级故障排除。要观察单个插件或 operator 模块，请读取其 ModuleInfo：

# Current version, target, next available version, and phase per installed module on this cluster
kubectl get moduleinfo -l cpaas.io/cluster-name=global \
  -o custom-columns='MODULE:.metadata.labels.cpaas\.io/module-name,CURRENT:.status.version,TARGET:.spec.version,NEW:.status.availableVersions[0].version,PHASE:.status.phase'

# Conditions and any block reasons for one module
kubectl get moduleinfo <name> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

当模块的 status.phase 为 Running 且 status.version 等于目标版本时，表示该模块已达到目标版本。

#从 Marketplace 升级 Agnostic 插件

CVO 驱动 Core 和 Aligned 插件。Agnostic 插件不在 CVO 的范围内，集群达到目标 Distribution Version 后，必须单独升级这些插件。每个 Agnostic 插件是否需要升级取决于其自身的 Kubernetes 兼容性 — 请参阅插件的 release notes，了解其与目标 Kubernetes 版本的兼容性。

对于 global 集群上正在使用的每个 Agnostic 插件：

1. 在 Web Console 中切换到 Administrator 视图。
2. 对于 Agnostic 集群插件，导航到 Marketplace > Cluster Plugins；对于 Agnostic operator，导航到 operator 操作流程。
3. 选择目标插件或 operator 并触发升级。Marketplace 升级流程会读取之前使用 violet 推送的软件包。

如果在升级前跳过了推送 Agnostic 插件，而 Marketplace 未提供目标版本，请先完成 violet push 步骤，然后重试 Marketplace 升级。