#升级 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 值匹配的分支发布已暂存的负载。

对于平台内置 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/ 目录中，按照 准备目标版本负载 同时运行 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 窗口已经过去，而你发现某个业务集群缺少 operator 包，你仍然可以在业务升级之前将其推送到该业务集群——参见 升级业务集群。

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

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

如果已知工件校验是多余的，可以添加 --skip-check-artifacts 来绕过它。

在运行预检之前，请确认 Registry 配置仍然正确：

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

将所选发布命令成功完成的结果，以及 Registry 管理界面或 API 作为阶段 1 的证据。确认预期的目标仓库和 tag 已存在，并将已发布的 Extension 集与导出的已安装清单 apps.yaml 进行比较。不要将 ProductBase.status.artifacts 作为零输出的目标版本门控：它代表当前目录，且对于可选或未安装的包，合法地可能包含 Absent 条目。

#运行预检

时间： 维护窗口前 1–2 周，这样在窗口打开之前就有时间解决任何阻塞项。

以预检模式运行 upgrade.sh：

bash upgrade.sh --preflight

预检是只读的——它会验证升级就绪状态，但不会更改集群状态。

预检返回两部分：

默认检查集包括：

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

如果任何检查未通过，请在维护窗口之前停止，并按照 升级故障排查 处理。不要通过禁用版本、Kubernetes 支持或管理员确认检查来强制执行不受支持的升级。

#部署 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 后，通过以下任一入口请求升级。这三个入口是等价的；请选择最符合你的操作模型的方式。

# 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 集群插件，或者进入 Agnostic operator 的工作流。
3. 选择目标插件或 operator 并触发升级。Marketplace 升级流程会读取此前通过 violet 推送的包。

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