#升级故障排查

当 preflight 报告阻塞性检查，CVO 报告 Ready=False、Reconciling=True 或 Stalled=True，或者 Core 或 Aligned 模块未达到其目标版本时，请使用本页。

#检查升级状态

将 <cluster> 替换为 global 或业务集群名称：

kubectl -n cpaas-system get cvsh <cluster> \
  -o jsonpath='{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl -n cpaas-system get cvsh <cluster> \
  -o jsonpath='{.status.preflight.observedAt}{"\n"}{range .status.preflight.checks[*]}{.name}{"\t"}{.policy}{"\t"}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl -n cpaas-system get cvsh <cluster> \
  -o jsonpath='{range .status.history[*]}{.version}{"\t"}{.state}{"\t"}{.startedTime}{"\t"}{.completionTime}{"\n"}{end}'

在更改升级请求之前，先解决第一个失败的 preflight 检查，或相关的 Ready、Reconciling、Stalled 条件。

#处理预检阻塞

如果 ResourcePatchUpgradeable 因 reason=UnexemptResourcePatches 失败，请检查命名的 ResourcePatch，并且仅在审查该 patch 之后，添加所需的目标版本豁免：

kubectl -n cpaas-system get cvsh <cluster> \
  -o jsonpath='{range .status.preflight.checks[?(@.name=="ResourcePatchUpgradeable")]}{.state}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

kubectl get resourcepatches <rp-name> -o yaml
kubectl annotate resourcepatches <rp-name> \
  config.cpaas.io/exempt-for-ver=<target-version> \
  --overwrite

常见的 preflight 阻塞：

不要禁用 VersionUpgradePath、KubernetesVersionSupported 或 AdminAckRequired 来强制执行不受支持的升级。如果技术支持指示你临时禁用其他检查，则仅在 cpaas-system/cvo-config 中禁用所指定的检查。

#处理管理员确认门控

如果 AdminAckRequired 失败，请检查目标发行版提供的键：

kubectl -n cpaas-system get configmap admin-gates -o yaml

完成适用门控所描述的操作。对于 Kubernetes 1.35 或更高版本的节点就绪门控，请在每个生产节点上完成 Kubernetes 1.35 或更高版本节点就绪。

从 admin-gates 中复制适用的键，记录确认，然后重新运行 preflight：

ACK_KEY='<key-from-admin-gates>'
kubectl -n cpaas-system patch configmap admin-acks --type merge \
  -p "{\"data\":{\"${ACK_KEY}\":\"true\"}}"

bash upgrade.sh --preflight

#恢复缺失的 Aligned 包

不可用的 Aligned 包不会更改应用当前已安装的状态。根据包类型和协调阶段，CVO 可能会通过 Ready=False 或 Reconciling=True 而不是 Stalled=True 来报告问题。

#Aligned 集群插件

如果某个 ClusterVersionShadow 条件包含 required ready ModulePluginConfig for installed platform-aligned component，请识别目标 ProductManifest 以及命名的 ModulePluginConfig：

kubectl get productmanifest v<target-version> -o yaml

kubectl get modulepluginconfig <modulepluginconfig-name> \
  -o jsonpath='{.spec.image}{"\n"}{range .status.conditions[*]}{.type}{"\t"}{.status}{"\t"}{.reason}{"\t"}{.message}{"\n"}{end}'

对于 ModulePlugin channel，目标 ProductManifest 中的 artifactStatus: Absent 表示匹配的目标 ModulePluginConfig 尚未完全就绪。这并不表示当前已安装的应用已变为缺失，也不能仅凭这一点证明 registry 中缺少该 image。

使用 ModulePluginConfig 条件以及 .spec.image 中的确切 image 来选择恢复方式：

• 对于 ACP Upgrade to v4.4 中的应用，将其 package 复制到目标 Core Package 的 plugins/ 目录中。对于内置 Registry，重新运行 upgrade.sh --only-sync-image。对于外部 registry，重新运行 准备目标版本有效负载 中的两种模式。
• 对于其他 Aligned 集群插件，使用 violet push 将目标包发布到 global 层。

#Aligned operators

Aligned operators 不使用 ModulePluginConfig。如果已安装的 operator 未继续升级，请检查受影响集群上的 Subscription、目标 InstallPlan、catalog 和 ModuleInfo：

kubectl get subscription -A
kubectl get installplan -A
kubectl get moduleinfo -l cpaas.io/cluster-name=<cluster>

如果目标 operator 包缺失，请将其发布到安装了该 operator 的每个集群。如果只有一个业务集群缺失，则使用 --clusters "<workload-cluster-name>" 将其推送到该集群。如果包已存在，请解决 CVO 实际报告的 Subscription、InstallPlan、catalog 或 ModuleInfo 条件。

在修正问题后，继续观察现有请求。CVO 会自动重试；不要清除或重新提交 desiredUpdate。

#诊断未推进的模块

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,NEW:.status.availableVersions[0].version,PHASE:.status.phase'

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

检查命名资源及相关 Events。对于 image-pull 失败，请验证 registry 可达性、CA 信任、pull 凭据，以及受影响节点上引用的 manifest。

#在升级升级前收集证据

请捕获 cvsh 条件、preflight 检查、阶段和历史记录、受影响的 ModuleInfo 或 ModulePluginConfig、相关 Events，以及精确的源版本和目标版本。不要包含平台 token、registry 密码或 Secret 内容。