#升级故障排查

当 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 条件。

#处理 Preflight 阻塞

ResourcePatch 记录了应用于平台资源的自定义项。升级不会覆盖此类自定义项，除非目标版本已对其豁免，因此在已自定义的环境中，ResourcePatchUpgradeable 是最常见的阻塞项。

如果 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

豁免注解的 key 是 config.cpaas.io/exempt-for-ver，其 value 为目标版本。豁免是按 major 和 minor 版本匹配的，因此，为某个 patch 版本记录的豁免也适用于同一 minor release 的其他 patch 版本。

对 patch 进行豁免意味着升级会保留该自定义项不变。它不会验证该自定义项在目标版本中是否仍然有效——请向提供该自定义项的技术支持联系人确认。

#解决其他常见的 Preflight 阻塞

使用 检查升级状态 中的命令列出所有不是 Passed 的检查，然后逐一解决：

不要强行绕过失败的检查继续升级。VersionUpgradePath、KubernetesVersionSupported 和 AdminAckRequired 是支持的升级路径本身的门禁；绕过它们的升级会进入平台未验证的状态。如果无法通过本页解决阻塞，请在继续之前联系技术支持。

#处理管理员确认门禁

如果 AdminAckRequired 失败，请检查目标 release 提供的 keys：

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

完成适用于相应门禁所描述的操作。对于 Kubernetes 1.35 或更高版本的 node-readiness 门禁，请在每个生产节点上完成 Kubernetes 1.35 或更高版本节点就绪状态。

针对该要求引入的第一个门禁，也就是 ACP 4.4 和 Kubernetes 1.35 目标所使用的门禁，是 ack-4.4-kubernetes-1.35-kernel-update。请将其视为示例——后续目标 release 可能提供不同的 key，因此始终应从 admin-gates 中读取 key，而不要重复使用这里的示例。

从 admin-gates 复制适用的 key，在 admin-acks 中记录确认，然后重新运行 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

确认该检查现在通过：

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

#恢复缺失的 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 尚未完全 Ready。它并不表示当前已安装的应用已变为 absent，也不能单凭这一点证明镜像在 registry 中缺失。

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

• 对于 ACP Upgrade to v4.5 中的应用，将其包复制到目标 Core Package 的 plugins/ 目录中。使用平台内置 Registry 时，重新运行 upgrade.sh --only-sync-image。使用外部 registry 时，重新运行 Prepare the Target-Version Payload 中的两种模式。
• 对于其他 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。对于镜像拉取失败，请验证 registry 可达性、CA 信任、拉取凭据，以及受影响节点上引用的 manifest。

#在升级升级前收集证据

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