解决方案 先升级对应的ASM网格版本，再进行集群升级，ASM网格版本与集群版本适配规则如下表。 表1 ASM网格版本与集群版本适配规则 ASM网格版本 集群版本 1.3 v1.13、v1.15、v1.17、v1.19 1.6 v1.15、v1.17 1.8 v1.15、v1.17、v1.19、v1.21 1.13 v1.21、v1.23 1.15 v1.21、v1.23、v1.25、v1.27 1.18 v1.25、v1.27、v1.28 若不需要使用ASM网格，可删除ASM网格后再进行升级，升级后集群不能绑定与表中不匹配的ASM网格版本。例如，使用v1.21版本集群与1.8版本ASM网格，若要升级至v1.25版本集群时，请先升级ASM网格至1.15版本后再进行v1.25版本集群升级。

版本兼容性差异 版本升级路径 版本差异 建议自检措施 v1.23/v1.25 升级至v1.27 容器运行时Docker不再被推荐使用，建议您使用Containerd进行替换，详情请参见容器引擎。 已纳入升级前检查。 v1.23升级至v1.25 在Kubernetes v1.25版本中， PodSecurityPolicy已被移除，并提供Pod安全性准入控制器（Pod Security Admission配置）作为PodSecurityPolicy的替代。 如果您需要将PodSecurityPolicy的相关能力迁移到Pod Security Admission中，需要参照以下步骤进行： 确认集群为CCE v1.23的最新版本。 迁移PodSecurityPolicy的相关能力迁移到Pod Security Admission，请参见Pod Security Admission配置。 确认迁移后功能正常，再升级为CCE v1.25版本。 如果您不再使用PodSecurityPolicy能力，则可以在删除集群中的PodSecurityPolicy后，直接升级为CCE v1.25版本。 v1.21/v1.19 升级至v1.23 社区较老版本的Nginx Ingress Controller来说（社区版本v0.49及以下，对应CCE插件版本v1.x.x），在创建Ingress时没有指定Ingress类别为nginx，即annotations中未添加kubernetes.io/ingress.class: nginx的情况，也可以被Nginx Ingress Controller纳管。但对于较新版本的Nginx Ingress Controller来说（社区版本v1.0.0及以上，对应CCE插件版本2.x.x），如果在创建Ingress时没有显示指定Ingress类别为nginx，该资源将被Nginx Ingress Controller忽略，Ingress规则失效，导致服务中断。 已纳入升级前检查，也可参照nginx-ingress插件升级检查进行自检。 v1.19升级至v1.21 Kubernetes v1.21集群版本修复 了exec probe timeouts不生效的BUG，在此修复之前，exec 探测器不考虑 timeoutSeconds 字段。相反，探测将无限期运行，甚至超过其配置的截止日期，直到返回结果。 若用户未配置，默认值为1秒。升级后此字段生效，如果探测时间超过1秒，可能会导致应用健康检查失败并频繁重启。 升级前检查您使用了exec probe的应用的probe timeouts是否合理。 CCE的v1.19及以上版本的kube-apiserver要求客户侧webhook server的证书必须配置Subject Alternative Names (SAN)字段。否则升级后kube-apiserver调用webhook server失败，容器无法正常启动。 根因：Go语言v1.15版本废弃了X.509 CommonName，CCE的v1.19版本的kube-apiserver编译的版本为v1.15，若客户的webhook证书没有Subject Alternative Names (SAN)，kube-apiserver不再默认将X509证书的CommonName字段作为hostname处理，最终导致认证失败。 升级前检查您自建webhook server的证书是否配置了SAN字段。 若无自建webhook server则不涉及。 若未配置，建议您配置使用SAN字段指定证书支持的IP及域名。 v1.15升级至v1.19 CCE v1.19版本的控制面与v1.15版本的Kubelet存在兼容性问题。若Master节点升级成功后，节点升级失败或待升级节点发生重启，则节点有极大概率为NotReady状态。 主要原因为升级失败的节点有大概率重启kubelet而触发节点注册流程，v1.15 kubelet默认注册标签（failure-domain.beta.kubernetes.io/is-baremetal和kubernetes.io/availablezone）被v1.19版本kube-apiserver视为非法标签。 v1.19版本中对应的合法标签为node.kubernetes.io/baremetal和failure-domain.beta.kubernetes.io/zone。 正常升级流程不会触发此场景。 在Master升级完成后尽量避免使用暂停升级功能，快速升级完Node节点。 若Node节点升级失败且无法修复，请尽快驱逐此节点上的应用，请联系技术支持人员，跳过此节点升级，在整体升级完毕后，重置该节点。 CCE的v1.15版本集群及v1.19版本集群将docker的存储驱动文件系统由 xfs切换成ext4，可能会导致升级后的java应用Pod内的import包顺序异常，既而导致Pod异常。 升级前查看节点上docker配置文件/etc/docker/daemon.json。检查dm.fs配置项是否为xfs。 若为ext4或存储驱动为overlay则不涉及。 若为xfs则建议您在新版本集群预先部署应用，以测试应用与新版本集群是否兼容。 { "storage-driver": "devicemapper", "storage-opts": [ "dm.thinpooldev=/dev/mapper/vgpaas-thinpool", "dm.use_deferred_removal=true", "dm.fs=xfs", "dm.use_deferred_deletion=true" ] } CCE的v1.19及以上版本的kube-apiserver要求客户侧webhook server的证书必须配置Subject Alternative Names (SAN)字段。否则升级后kube-apiserver调用webhook server失败，容器无法正常启动。 根因：Go语言v1.15版本废弃了X.509 CommonName，CCE的v1.19版本的kube-apiserver编译的版本为v1.15。CommonName字段作为hostname处理，最终导致认证失败。 升级前检查您自建webhook server的证书是否配置了SAN字段。 若无自建webhook server则不涉及。 若未配置，建议您配置使用SAN字段指定证书支持的IP及域名。 须知： 为减弱此版本差异对集群升级的影响，v1.15升级至v1.19时，CCE会进行特殊处理，仍然会兼容支持证书不带SAN。但后续升级不再特殊处理，请尽快整改证书，以避免影响后续升级。 v1.17.17版本及以后的集群CCE自动给用户创建了PSP规则，限制了不安全配置的Pod的创建，如securityContext配置了sysctl的net.core.somaxconn的Pod。 升级后请参考资料按需开放非安全系统配置，具体请参见PodSecurityPolicy配置。 1.15版本集群原地升级，如果业务中存在initContainer或使用Istio的场景，则需要注意以下约束： 1.16及以上的kubelet统计QosClass和之前版本存在差异，1.15及以下版本仅统计spec.containers下的容器，1.16及以上的kubelet版本会同时统计spec.containers和spec.initContainers下的容器，升级前后会造成Pod的QosClass变化，从而造成Pod中容器重启。 建议参考表1在升级前修改业务容器的QosClass规避该问题。 v1.13升级至v1.15 vpc集群升级后，由于网络组件的升级，master节点会额外占一个网段。在Master占用了网段后，无可用容器网段时，新建节点无法分配到网段，调度在该节点的pod会无法运行。 一般集群内节点数量快占满容器网段场景下会出现该问题。例如，容器网段为10.0.0.0/16，可用IP数量为65536，VPC网络IP分配是分配固定大小的网段（使用掩码实现，确定每个节点最多分配多少容器IP），例如上限为128，则此时集群最多支撑65536/128=512个节点，然后去掉Master节点数量为509，此时是1.13集群支持的节点数。集群升级后，在此基础上3台Master节点会各占用1个网段，最终结果就是506台节点。 表1 1.15版本升级前后QosClass变化 init容器（根据spec.initContainers计算） 业务容器（根据spec.containers计算） Pod（根据spec.containers和spec.initContainers计算） 是否受影响 Guaranteed Besteffort Burstable 是 Guaranteed Burstable Burstable 否 Guaranteed Guaranteed Guaranteed 否 Besteffort Besteffort Besteffort 否 Besteffort Burstable Burstable 否 Besteffort Guaranteed Burstable 是 Burstable Besteffort Burstable 是 Burstable Burstable Burstable 否 Burstable Guaranteed Burstable 是

解决方案 问题场景一：包管理器命令执行失败 检查到包管理器命令rpm或dpkg命令执行失败，请登录节点排查下列命令的可用性。 rpm系统： rpm -qa dpkg系统： dpkg -l 问题场景二：systemctl status命令执行失败 检查到节点systemctl status命令不可用，将影响众多检查项，请登录节点排查下列命令的可用性。 systemctl status kubelet

解决方案 问题场景一：节点镜像非CCE标准镜像 CCE节点运行依赖创建时的初始标准内核版本，CCE基于该内核版本做了全面的兼容性测试，非标准的内核版本可能在节点升级中因兼容性问题导致节点升级失败，详情请参见高危操作及解决方案。 当前CCE不建议该类节点进行升级，建议您在升级前重置节点至标准内核版本。 问题场景二：特殊版本镜像存在缺陷 检查到本次升级涉及1.17 欧拉2.8 Arm镜像，该版本镜像存在缺陷，其上docker重启后将影响"docker exec"命令，升级集群版本时将触发docker版本更新，触发docker重启，因此存在建议： 建议您提前排空、隔离该节点后进行集群升级。 建议您升级至1.19及更高版本后，通过重置节点操作更换更高版本镜像，例如欧拉2.9镜像。

升级前检查项 集群升级前，系统将自动进行全面的升级前检查，当集群不满足升级前检查条件时将无法继续升级。为了能够更好地避免升级风险，本文提供全量的升级前检查问题及解决方案，帮助您对可能存在的升级故障进行预处理。 表1 检查项列表 序号 检查项名称 检查项说明 1 节点限制检查 检查节点是否可用 检查节点操作系统是否支持升级 检查节点是否含有非预期的节点池标签 检查K8s节点名称是否与云服务器保持一致 2 升级管控检查 检查集群是否处于升级管控中。 3 插件检查 检查插件状态是否正常 检查插件是否支持目标版本 4 Helm模板检查 检查当前HelmRelease记录中是否含有目标集群版本不支持的K8s废弃API，可能导致升级后helm模板不可用。 5 Master节点SSH联通性检查 检查当前CCE是否能连接至您的Master节点。 6 安全组检查 检查Node节点安全组规则中，协议端口为ICMP:全部，源地址为Master节点安全组的规则是否被删除。 7 残留待迁移节点检查 检查节点是否需要迁移。 8 K8s废弃资源检查 检查集群是否存在对应版本已经废弃的资源。 9 兼容性风险检查 请您阅读版本兼容性差异，并确认不受影响。补丁升级不涉及版本兼容性差异。 10 节点CCE Agent版本检查 检测当前节点的CCE包管理组件cce-agent是否为最新版本。 11 节点CPU使用率检查 检查节点CPU使用情况，是否超过90%。 12 CRD检查 检查集群关键CRD "packageversions.version.cce.io"是否被删除。 检查集群关键CRD "network-attachment-definitions.k8s.cni.cncf.io"是否被删除。 13 节点磁盘检查 检查节点关键数据盘使用量是否满足升级要求 检查/tmp目录是否存在500MB可用空间 14 节点DNS检查 检查当前节点DNS配置是否能正常解析OBS地址 检查当前节点是否能访问存储升级组件包的OBS地址 15 节点关键目录文件权限检查 检查CCE使用的目录/var/paas内文件的属主和属组是否都为paas。 16 节点Kubelet检查 检查节点kubelet服务是否运行正常。 17 节点内存检查 检查节点内存使用情况，是否超过90%。 18 节点时钟同步服务器检查 检查节点时钟同步服务器ntpd或chronyd是否运行正常。 19 节点OS检查 检查节点操作系统内核版本是否为CCE支持的版本。 20 节点CPU数量检查 检查Master节点的CPU数量是否大于2核。 21 节点Python命令检查 检查Node节点中Python命令是否可用。 22 ASM网格版本检查 检查集群是否使用ASM网格服务 检查当前ASM版本是否支持目标集群版本 23 节点Ready检查 检查集群内节点是否Ready。 24 节点journald检查 检查节点上的journald状态是否正常。 25 节点干扰ContainerdSock检查 检查节点上是否存在干扰的Containerd.Sock文件。该文件影响euler操作系统下的容器运行时启动。 26 内部错误 在升级前检查流程中是否出现内部错误。 27 节点挂载点检查 检查节点上是否存在不可访问的挂载点。 28 K8s节点污点检查 检查节点上是否存在集群升级需要使用到的污点。 29 everest插件版本限制检查 检查集群当前everest插件版本是否存在兼容性限制。 30 cce-hpa-controller插件限制检查 检查到目标cce-controller-hpa插件版本是否存在兼容性限制。 31 增强型CPU管理策略检查 检查当前集群版本和要升级的目标版本是否支持增强型CPU管理策略。 32 用户节点组件健康检查 检查用户节点的容器运行时组件和网络组件等是否健康。 33 控制节点组件健康检查 检查控制节点的Kubernetes组件、容器运行时组件、网络组件等是否健康。 34 K8s组件内存资源限制检查 检查K8s组件例如etcd、kube-controller-manager等组件是否资源超出限制。 35 K8s废弃API检查 系统会扫描过去一天的审计日志，检查用户是否调用目标K8s版本已废弃的API。 说明： 由于审计日志的时间范围有限，该检查项仅作为辅助手段，集群中可能已使用即将废弃的API，但未在过去一天的审计日志中体现，请您充分排查。 36 节点NetworkManager检查 检查节点上的NetworkManager状态是否正常。 37 节点ID文件检查 检查节点的ID文件内容是否符合格式。 38 节点配置一致性检查 在升级集群版本至v1.19及以上版本时，将对您的节点上的Kubenertes组件的配置进行检查，检查您是否后台修改过配置文件。 39 节点配置文件检查 检查节点上关键组件的配置文件是否存在。 40 CoreDNS配置一致性检查 检查当前CoreDNS关键配置Corefile是否同Helm Release记录存在差异，差异的部分可能在插件升级时被覆盖，影响集群内部域名解析。 41 节点Sudo检查 检查当前节点sudo命令，sudo相关文件是否正常。 42 节点关键命令检查 检查节点升级依赖的一些关键命令是否能正常执行。 43 节点sock文件挂载检查 检查节点上的Pod是否直接挂载docker/containerd.sock文件。升级过程中Docker/Containerd将会重启，宿主机sock文件发生变化，但是容器内的sock文件不会随之变化，二者不匹配，导致您的业务无法访问Docker/Containerd。Pod重建后sock文件重新挂载，可恢复正常。 44 HTTPS类型负载均衡证书一致性检查 检查HTTPS类型负载均衡所使用的证书，是否在ELB服务侧被修改。 45 节点挂载检查 检查节点上默认挂载目录及软链接是否被手动挂载或修改。 46 节点paas用户登录权限检查 检查paas用户是否有登录权限。 47 ELB IPv4私网地址检查 检查集群内负载均衡类型的Service所关联的ELB实例是否包含IPv4私网IP。 48 检查历史升级记录是否满足升级条件 检查集群最初版本是否小于v1.11，且升级的目标版本大于v1.23。 49 检查集群管理平面网段是否与主干配置一致 检查集群管理平面网段是否与主干配置一致。 50 GPU插件检查 检查到本次升级涉及GPU插件，可能影响新建GPU节点时GPU驱动的安装。 51 节点系统参数检查 检查您节点上默认系统参数是否被修改。 52 残留packageversion检查 检查当前集群中是否存在残留的packageversion。 53 节点命令行检查 检查节点中是否存在升级所必须的命令。 54 节点交换区检查 检查集群节点上是否开启交换区。 55 nginx-ingress插件升级检查 检查nginx-ingress插件升级路径是否涉及兼容问题。 56 云原生监控插件升级检查 在集群升级过程中，云原生监控插件从3.9.0之前的版本升级至3.9.0之后的版本升级时，存在兼容性问题，需检查该插件是否开启了grafana的开关。 57 Containerd Pod重启风险检查 检查当前集群内使用containerd的节点在升级containerd组件时，节点上运行的业务容器是否可能发生重启，造成业务影响。 58 GPU插件关键参数检查 检查CCE GPU插件中部分配置是否被侵入式修改，被侵入式修改的插件可能导致升级失败。 59 GPU/NPU Pod重建风险检查 检查当前集群升级重启kubelet时，节点上运行的GPU/NPU业务容器是否可能发生重建，造成业务影响。 父主题： 升级前检查异常问题排查

解决方案 使用kubectl连接集群。 执行以下命令获取插件实例详情。 kubectl get ds nvidia-driver-installer -nkube-system -oyaml 请检查UpdateStrategy字段值是否被修改为OnDelete，应改回RollingUpdate。 请检查NVIDIA_DRIVER_DOWNLOAD_URL字段是否与插件页面的GPU插件详情地址不一致，若不一致，请在页面上修改。 图1 插件页面编辑GPU插件

问题根因 NGINX Ingress控制器插件基于开源社区Nginx Ingress Controller的模板与镜像。 对于社区较老版本的Nginx Ingress Controller来说（社区版本v0.49及以下，对应CCE插件版本v1.x.x），在创建Ingress时没有指定Ingress类别为nginx，即annotations中未添加kubernetes.io/ingress.class: nginx的情况，也可以被Nginx Ingress Controller纳管。详情请参见社区代码。 但对于较新版本的Nginx Ingress Controller来说（社区版本v1.0.0及以上，对应CCE插件版本2.x.x），如果在创建Ingress时没有显示指定Ingress类别为nginx，该资源将被Nginx Ingress Controller忽略，Ingress规则失效，导致服务中断。详情请参见请参见社区代码。 社区相关PR链接为：https://github.com/kubernetes/ingress-nginx/pull/7341 目前有两种方式指定Ingress类别： 通过annotations指定，为Ingress资源添加annotations（kubernetes.io/ingress.class: nginx）。 通过spec指定，.spec.ingressClassName字段配置为nginx。但需要配套具有IngressClass资源。 示例如下： apiVersion: networking.k8s.io/v1beta1 kind: Ingress metadata: name: test namespace: default annotations: kubernetes.io/ingress.class: nginx spec: ingressClassName: nginx rules: … status: loadBalancer: {}

解决方案 问题场景一：检查到应用存在该异常，进行整改。 推荐您使用挂载目录的方式挂载sock文件。例如，若宿主机sock文件路径为/var/run/docker.sock，您可参考下述配置进行整改。注意，该整改生效时会触发Pod重建。 kind: Deployment apiVersion: apps/v1 metadata: name: test spec: replicas: 1 selector: matchLabels: app: nginx template: metadata: app: nginx spec: containers: - name: container-1 image: 'nginx' imagePullPolicy: IfNotPresent volumeMounts: - name: sock-dir mountPath: /var/run imagePullSecrets: - name: default-secret volumes: - name: sock-dir hostPath: path: /var/run 问题场景二：检查到应用存在该异常，明确应用使用场景后，接受sock短暂不可访问风险，继续升级。 请选择跳过该检查项异常后重新检查，在集群升级完成后删除存量Pod，触发Pod重建，访问将恢复。 问题场景三：部分老版本的CCE插件存在该异常 请将老版本的CCE插件升级至最新版本。例如1.2.2以下的dolphin插件存在该问题，需升级至1.2.2及以上版本。 问题场景四： 日志分析 里面出现“failed to execute docker ps -aq”错误。 该报错出现一般是因为容器引擎功能异常导致，请您提工单联系运维人员处理。

检查项内容 检查节点上的Pod是否直接挂载docker/containerd.sock文件。升级过程中Docker/Containerd将会重启，宿主机sock文件发生变化，但是容器内的sock文件不会随之变化，二者不匹配，导致您的业务无法访问Docker/Containerd。Pod重建后sock文件重新挂载，可恢复正常。 通常K8S集群用户基于如下场景在容器中使用上述sock文件： 监控类应用，以DaemonSet形式部署，通过sock文件连接Docker/Containerd，获取节点容器状态信息。 编译平台类应用，通过sock文件连接Docker/Containerd，创建程序编译用容器。

检查项内容 检查节点上关键组件的配置文件是否存在。 当前检查文件列表如下： 文件名 文件内容 备注 /opt/cloud/cce/kubernetes/kubelet/kubelet kubelet命令行启动参数 - /opt/cloud/cce/kubernetes/kubelet/kubelet_config.yaml kubelet启动参数配置 - /opt/cloud/cce/kubernetes/kube-proxy/kube-proxy kube-proxy命令行启动参数 - /etc/sysconfig/docker docker配置文件 containerd运行时或Debain-Group机器不检查 /etc/default/docker docker配置文件 containerd运行时或Centos-Group机器不检查