#升级 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.4 的 Aligned 包。请将 Pre-Upgrade Preparation 中列出的 11 个分别下载的包复制到解压后的 Core Package 的 plugins/ 目录中。对每个包运行一次以下命令：

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

在同步之前，确认该目录包含全部 11 个包：

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/ 中的包，而不会部署 cluster version operator 或更改正在运行的应用。CVO 会在稍后维护窗口内部署——请参见 部署 cluster version 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.4 的 11 个 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 窗口已经过去，而你发现某个 workload 集群缺少 operator 包，仍然可以在 workload 升级之前将其推送到该 workload 集群——请参见 升级 workload 集群。

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

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

制品验证会将 plugins/ 中存在的每个包与目标 Core Package 期望的版本进行比较，并在版本不匹配时失败。它不会验证集合是否完整：未暂存的包不会被检查，运行会继续。请在依赖验证成功之前，先根据 Download ACP Upgrade to v4.4 确认这 11 个包。

在运行预检之前，请确认 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 会对受支持的升级路径本身进行门禁。如果某个阻塞项无法解决，请在继续之前联系技术支持。

#部署 cluster version operator

何时： 在维护窗口开始时。

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

bash upgrade.sh --skip-sync-image

这会部署或更新 cluster version 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'

按制品逐项输出的信息用于诊断，不要求为空。目标 manifest 可以包含未安装、Agnostic 或可选条目，这些条目未处于 Ready 状态是合理的。请将输出与已安装的 Core 和 Aligned 清单进行比较。对于已安装的 Aligned ModulePlugin，当其 channel 不处于 Ready 状态时，请检查匹配的目标 ModulePluginConfig：

kubectl get modulepluginconfig <modulepluginconfig-name> -o yaml

使用目标 ProductManifest 中的组件名称和 channel tag，或者使用 ClusterVersionShadow 错误中报告的名称，来定位 ModulePluginConfig。此名称中的组件版本不一定就是 ACP Distribution Version。不要仅将 artifactStatus: Absent 视为 Registry manifest 缺失的证据；应结合 ModulePluginConfig 条件及其 .spec.image，区分 manifest 缺失、认证问题、CA 问题、网络问题或包内容问题。

#请求升级

在 cluster version 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. 导航到 Marketplace > Cluster Plugins 以升级 Agnostic 集群插件，或导航到 operator 工作流以升级 Agnostic operator。
3. 选择目标插件或 operator 并触发升级。Marketplace 升级流程会读取之前通过 violet 推送的包。

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