Alauda Container Platform
  • 简体中文

    • 升级故障排查

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

    目录

    检查升级状态处理 Preflight 阻塞解决其他常见的 Preflight 阻塞处理管理员确认门控恢复缺失的 Aligned 包Aligned 集群插件Aligned Operator诊断未前进的模块升级前收集证据

    检查升级状态

    将 <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

    豁免注解键为 config.cpaas.io/exempt-for-ver，其值为目标版本。豁免是按主版本和次版本匹配的，因此为某个 patch 版本记录的豁免，也会覆盖同一 minor release 的其他 patch 版本。

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

    解决其他常见的 Preflight 阻塞

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

    检查验证内容解决方法
    KubernetesVersionSupported集群的 Kubernetes 版本在目标 release 支持范围内。遵循 Kubernetes 支持矩阵；不要禁用该检查。
    VersionUpgradePath当前 patch 可以通过受支持的边到达所请求的目标版本。使用 availableUpdates 中的目标版本，或按建议先升级到中间目标版本。
    ClusterRunning集群健康且已完成协调。检查 kubectl get clusterview <cluster>，并解决不健康的节点或组件。
    DockerRuntimeUnsupported没有节点使用不受支持的 Docker runtime。将受影响的节点迁移到 containerd。
    ClusterModuleStable, ModuleInfoStableCore 和已安装的 Aligned 模块处于稳定状态。按 在升级前验证模块稳定性 中的步骤执行。

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

    处理管理员确认门控

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

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

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

    针对该要求引入的第一个门控，即 ACP 4.4 和 Kubernetes 1.35 目标对应的门控，是 ack-4.4-kubernetes-1.35-kernel-update。请将其视为示例——后续的目标 release 可能提供不同的键，因此务必从 admin-gates 中读取键，而不要复用此键。

    从 admin-gates 复制适用的键，在 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。这并不意味着当前已安装的应用已经缺失，也不足以证明 registry 中缺少该镜像。

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

    证据恢复方式
    所命名的 ModulePluginConfig 不存在检查目标 ProductManifest 条件和 controller 协调状态。对象缺失本身并不能证明包镜像不存在。
    ResolveDigestFailed 报告 manifest unknown 或 not found，或者 registry 确认 .spec.image 不存在使用下面适用的方法重新发布确切的目标包。
    条件报告 unauthorized、denied 或其他认证错误修正 registry 凭据或仓库权限，然后让现有请求重试。
    条件报告 x509 或证书信任错误修正 registry 证书链或节点信任配置。
    条件报告 DNS、路由、超时或连接错误从执行解析的组件恢复到 registry 的可达性。
    LoadModulePluginFailed检查包内容和 module-plugin.yaml；仅在确认包无效后发布修正后的包。
    • 对于 ACP Upgrade to v4.4 中的应用，将其包复制到目标 Core Package 的 plugins/ 目录。对于使用平台内置 Registry 的情况，重新运行 upgrade.sh --only-sync-image。对于外部 registry，重新运行 准备目标版本负载 中的两个模式。
    • 对于其他 Aligned 集群插件，使用 violet push 将目标包发布到 global tier。

    Aligned Operator

    Aligned operator 不使用 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 内容。