升级前须知
更新时间 2026-03-24 13:48:08
最近更新时间: 2026-03-24 13:48:08
本文主要介绍集群升级前须知
升级前，您可以在CCE控制台确认您的集群是否可以进行升级操作。确认方法请参见集群升级概述。
注意事项
升级集群前，您需要知晓以下事项：
- 请务必慎重并选择合适的时间段进行升级，以减少升级对您的业务带来的影响。
- 集群升级前，请参考Kubernetes版本发布说明了解每个集群版本发布的特性以及差异，否则可能因为应用不兼容新集群版本而导致升级后异常。例如，您需要检查集群中是否使用了目标版本废弃的API，否则可能导致升级后调用接口失败。
- 在配置中心修改集群配置后的10分钟内请勿进行集群升级操作，否则可能由于操作冲突导致集群升级失败。
集群升级时，以下几点注意事项可能会对您的业务存在影响，请您关注： - 集群升级过程中，不建议对集群进行任何操作。尤其是关机、重启或删除节点等操作，都会导致升级失败。
- 集群升级前，请确认集群中未执行高危操作，否则可能导致集群升级失败或升级后配置丢失。例如，常见的高危操作有本地修改集群节点的配置、通过ELB控制台修改CCE管理的监听器配置等。建议您通过CCE控制台修改相关配置，以便在升级时自动继承。
- 集群升级过程中，已运行工作负载业务不会中断，但API Server访问会短暂中断，如果业务需要访问API Server可能会受到影响。
- 集群升级过程中默认不限制应用调度。但下列旧版本集群升级过程中，仍然会给节点打上“node.kubernetes.io/upgrade”（效果为“NoSchedule”）的污点，并在集群升级完成后移除该污点。
- 所有v1.15集群
- 所有v1.17集群
- 补丁版本小于等于v1.19.16-r4的1.19集群
- 补丁版本小于等于v1.21.7-r0的1.21集群
- 补丁版本小于等于v1.23.5-r0的1.23集群
- 集群升级过程中，如果同时升级插件，在集群资源使用率较高的情况下可能会导致插件Pod抢占业务Pod资源，业务Pod被驱逐重建，插件升级完成后将自动恢复。
- 在将集群升级至v1.28及以上版本时，系统会创建同等数量的新控制节点逐步替换旧节点，升级完成后控制节点的IP地址将发生变更。若您原先直接通过控制节点IP访问集群，请改用集群统一的公网或内网地址进行访问，详见集群连接信息。
- 集群升级过程中，系统将自动编辑/etc/rc.local文件。此操作可能会触发某些安全程序的相应告警，请您知悉并忽略由此产生的安全告警。
约束与限制
- 集群升级出现异常时，集群可通过备份数据进行回滚。若您在升级成功之后对集群进行了其它操作（例如变更集群规格），将无法再通过备份数据回滚。
- 容器隧道网络集群升级至1.19.16-r4、1.21.7-r0、1.23.5-r0、1.25.1-r0及之后的版本时，会移除匹配目的地址是容器网段且源地址非容器网段的SNAT规则；如果您之前通过配置VPC路由实现集群外直接访问所有的Pod IP，升级后只支持直接访问对应节点上的Pod IP。
- NGINX Ingress控制器插件新版本配置优雅退出和ELB删除后端控制器宽限时间，支持无损升级。以下插件版本升级过程可能会出现服务短暂不可用，若集群中已安装下列版本的插件，请选择业务低峰期进行升级，具体版本如下：
| 插件版本 | 小版本范围 |
|---|---|
| 2.1.x | x < 32 |
| 2.2.x | x < 41 |
| 2.4.x | x < 4 |
版本差异说明
| 版本升级路径 | 版本差异 | 建议自检措施 |
|---|---|---|
| 升级至v1.28、v1.29、v1.30、v1.31、v1.32 | 请关注Kubernetes API变更。 | 检查集群中已使用的API版本，避免使用已废弃的API版本。 |
| v1.23/v1.25 升级至v1.27 | 容器运行时Docker不再被推荐使用，建议您使用Containerd进行替换。 | 已纳入升级前检查。 |
| v1.23升级至v1.25 | 在Kubernetes v1.25版本中，PodSecurityPolicy已被移除，并提供Pod安全性准入控制器作为PodSecurityPolicy的替代。 | l 如果您需要将PodSecurityPolicy的相关能力迁移到Pod Security Admission中，需要参照以下步骤进行： 1. 确认集群为CCE v1.23的最新版本。 2. 迁移PodSecurityPolicy的相关能力迁移到Pod Security Admission。 3. 确认迁移后功能正常，再升级为CCE v1.25版本。 l 如果您不再使用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规则失效，导致服务中断。 | 已纳入升级前检查。 |
| 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.509CommonName，CCE的v1.19版本的kube-apiserver编译的版本为v1.15，若客户的webhook证书没有Subject Alternative Names (SAN)，kube-apiserver不再默认将X509证书的CommonName字段作为hostname处理，最终导致认证失败。 | 升级前检查您自建webhook server的证书是否配置了SAN字段。 l 若无自建webhook server则不涉及。 l 若未配置，建议您配置使用SAN字段指定证书支持的IP及域名。 |
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 | 是 |
废弃API说明
随着Kubernetes API的演化，API会周期性地被重组或升级，部分API会被弃用并被最终删除。以下为各Kubernetes社区版本中被废弃的API。
当某API被废弃时，已经创建的资源对象不受影响，但新建或编辑该资源时将出现API版本被拦截的情况。
表 Kubernetes社区v1.32版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| FlowSchema和PriorityLevelConfiguration | flowcontrol.apiserver.k8s.io/v1beta3 | flowcontrol.apiserver.k8s.io/v1 （该API从社区v1.29版本开始可用） | flowcontrol.apiserver.k8s.io/v1中的显着变化： PriorityLevelConfiguration的spec.limited.assuredConcurrencyShares字段已被重命名为spec.limited.nominalConcurrencyShares，仅在未指定时默认为30，并且显式值0不会更改为30。 |
表 Kubernetes社区v1.29版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| FlowSchema和PriorityLevelConfiguration | flowcontrol.apiserver.k8s.io/v1beta2 | flowcontrol.apiserver.k8s.io/v1 （该API从社区v1.29版本开始可用） flowcontrol.apiserver.k8s.io/v1beta3 （该API从社区v1.26版本开始可用） | lflowcontrol.apiserver.k8s.io/v1中的显着变化： PriorityLevelConfiguration的spec.limited.assuredConcurrencyShares字段已被重命名为spec.limited.nominalConcurrencyShares，仅在未指定时默认为30，并且显式值0不会更改为30。 l flowcontrol.apiserver.k8s.io/v1beta3中需要额外注意的变更： PriorityLevelConfiguration的spec.limited.assuredConcurrencyShares字段已被更名为spec.limited.nominalConcurrencyShares。 |
表1 Kubernetes社区v1.27版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| CSIStorageCapacity | storage.k8s.io/v1beta1 | storage.k8s.io/v1 （该API从社区v1.24版本开始可用） | - |
| FlowSchema和PriorityLevelConfiguration | flowcontrol.apiserver.k8s.io/v1beta1 | flowcontrol.apiserver.k8s.io/v1beta3 （该API从社区v1.26版本开始可用） | - |
| HorizontalPodAutoscaler | autoscaling/v2beta2 | autoscaling/v2 （该API从社区v1.23版本开始可用） | - |
表 Kubernetes社区v1.25版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| CronJob | batch/v1beta1 | batch/v1 （该API从社区v1.21版本开始可用） | - |
| EndpointSlice | discovery.k8s.io/v1beta1 | discovery.k8s.io/v1 （该API从社区v1.21版本开始可用） | 此次更新需注意以下变更： l 每个Endpoint中，topology["kubernetes.io/hostname"] 字段已被弃用，请使用nodeName字段代替。 l 每个Endpoint中， topology["kubernetes.io/zone"] 字段已被弃用，请使用zone字段代替。 l topology字段被替换为 deprecatedTopology ，并且在v1版本中不可写入。 |
| Event | events.k8s.io/v1beta1 | events.k8s.io/v1 （该API从社区v1.19版本开始可用） | 此次更新需注意以下变更： ltype字段只能设置为 Normal和 Warning之一。 l involvedObject字段被更名为 regarding 。 l action 、 reason 、reportingController和 reportingInstance字段 在创建新的 events.k8s.io/v1版本Event时都是必需的字段。 l 使用 eventTime而不是已被弃用的 firstTimestamp字段 （该字段已被更名为 deprecatedFirstTimestamp ，且不允许出现在新的 events.k8s.io/v1Event对象中）。 l 使用 series.lastObservedTime而不是已被弃用的 lastTimestamp字段 （该字段已被更名为 deprecatedLastTimestamp ，且不允许出现在新的 events.k8s.io/v1Event对象中）。 l 使用 series.count而不是已被弃用的 count字段 （该字段已被更名为 deprecatedCount ，且不允许出现在新的 events.k8s.io/v1Event对象中）。 l 使用 reportingController而不是已被弃用的 source.component字段 （该字段已被更名为 deprecatedSource.component ，且不允许出现在新的 events.k8s.io/v1Event对象中）。 l 使用 reportingInstance而不是已被弃用的 source.host字段 （该字段已被更名为 deprecatedSource.host ，且不允许出现在新的 events.k8s.io/v1Event对象中）。 |
| HorizontalPodAutoscaler | autoscaling/v2beta1 | autoscaling/v2 （该API从社区v1.23版本开始可用） | - |
| PodDisruptionBudget | policy/v1beta1 | policy/v1 （该API从社区v1.21版本开始可用） | 在policy/v1版本的 PodDisruptionBudget中将 spec.selector设置为空（{}）时会选择名字空间中的所有Pod（在 policy/v1beta1版本中，空的 spec.selector不会选择任何Pod）。如果 spec.selector未设置，则在两个API版本下都不会选择任何Pod。 |
| PodSecurityPolicy | policy/v1beta1 | - | 从社区v1.25版本开始，PodSecurityPolicy资源不再提供policy/v1beta1版本的API，并且PodSecurityPolicy准入控制器也会被删除。 |
| RuntimeClass | node.k8s.io/v1beta1 | node.k8s.io/v1（该API从社区v1.20版本开始可用） | - |
表 Kubernetes社区v1.22版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| MutatingWebhookConfiguration ValidatingWebhookConfiguration | admissionregistration.k8s.io/v1beta1 | admissionregistration.k8s.io/v1 （该API从社区v1.16版本开始可用） | lwebhooks[*].failurePolicy在v1版本中默认值从 Ignore改为 Fail 。 l webhooks[*].matchPolicy在v1版本中默认值从 Exact改为 Equivalent 。 l webhooks[*].timeoutSeconds在v1版本中默认值从 30s改为 10s 。 l webhooks[*].sideEffects的默认值被删除，并且该字段变为必须指定； 在v1版本中可选的值只能是 None和 NoneOnDryRun之一。 l webhooks[*].admissionReviewVersions的默认值被删除，在v1版本中此字段变为必须指定（AdmissionReview的被支持版本包括v1和v1beta1）。 l webhooks[*].name必须在通过 admissionregistration.k8s.io/v1创建的对象列表中唯一。 |
| CustomResourceDefinition | apiextensions.k8s.io/v1beta1 | apiextensions/v1 （该API从社区v1.16版本开始可用） | lspec.scope的默认值不再是 Namespaced ，该字段必须显式指定。 l spec.version在v1版本中被删除，应改用 spec.versions 。 l spec.validation在v1版本中被删除，应改用 spec.versions[*].schema 。 l spec.subresources在v1版本中被删除，应改用 spec.versions[*].subresources 。 l spec.additionalPrinterColumns在v1版本中被删除，应改用 spec.versions[*].additionalPrinterColumns 。 l spec.conversion.webhookClientConfig在v1版本中被移动到 spec.conversion.webhook.clientConfig中。 l spec.conversion.conversionReviewVersions在v1版本中被移动到 spec.conversion.webhook.conversionReviewVersions l spec.versions[*].schema.openAPIV3Schema在创建v1版本的 CustomResourceDefinition对象时变成必需字段，并且其取值必须是一个结构化的Schema。 l spec.preserveUnknownFields: true在创建v1版本的 CustomResourceDefinition对象时不允许指定；该配置必须在Schema定义中使用 x-kubernetes-preserve-unknown-fields: true来设置。 l 在v1版本中，additionalPrinterColumns 的条目中的 JSONPath字段被更名为 jsonPath 。 |
| APIService | apiregistration/v1beta1 | apiregistration.k8s.io/v1 （该API从社区v1.10版本开始可用） | - |
| TokenReview | authentication.k8s.io/v1beta1 | authentication.k8s.io/v1 （该API从社区v1.6版本开始可用） | - |
| LocalSubjectAccessReview SelfSubjectAccessReview SubjectAccessReview SelfSubjectRulesReview | authorization.k8s.io/v1beta1 | authorization.k8s.io/v1 （该API从社区v1.16版本开始可用） | spec.group在v1版本中被更名为 spec.groups |
| CertificateSigningRequest | certificates.k8s.io/v1beta1 | certificates.k8s.io/v1 （该API从社区v1.19版本开始可用） | certificates.k8s.io/v1中需要额外注意的变更： l 对于请求证书的API客户端而言： − spec.signerName现在变成必需字段， 并且通过certificates.k8s.io/v1 API不可以创建签署者为 kubernetes.io/legacy-unknown的请求。 − spec.usages现在变成必需字段，其中不可以包含重复的字符串值， 并且只能包含已知的用法字符串。 l 对于要批准或者签署证书的API客户端而言： − status.conditions中不可以包含重复的类型。 − status.conditions[*].status字段现在变为必需字段。 − status.certificate必须是PEM编码的，而且其中只能包含CERTIFICATE数据块。 |
| Lease | coordination.k8s.io/v1beta1 | coordination.k8s.io/v1 （该API从社区v1.14版本开始可用） | - |
| Ingress | networking.k8s.io/v1beta1 extensions/v1beta1 | networking.k8s.io/v1 （该API从社区v1.19版本开始可用） | lspec.backend字段被更名为 spec.defaultBackend 。 l 后端的 serviceName字段被更名为 service.name 。 l 数值表示的后端 servicePort字段被更名为 service.port.number 。 l 字符串表示的后端 servicePort字段被更名为 service.port.name 。 l 对所有要指定的路径，pathType都成为必需字段。 可选项为 Prefix 、Exact和 ImplementationSpecific 。 要匹配v1beta1版本中未定义路径类型时的行为，可使用 ImplementationSpecific 。 |
| IngressClass | networking.k8s.io/v1beta1 | networking.k8s.io/v1 （该API从社区v1.19版本开始可用） | - |
| ClusterRole ClusterRoleBinding Role RoleBinding | rbac.authorization.k8s.io/v1beta1 | rbac.authorization.k8s.io/v1 （该API从社区v1.8版本开始可用） | - |
| PriorityClass | scheduling.k8s.io/v1beta1 | scheduling.k8s.io/v1 （该API从社区v1.14版本开始可用） | - |
| CSIDriver CSINode StorageClass VolumeAttachment | storage.k8s.io/v1beta1 | storage.k8s.io/v1 | l CSIDriver从社区v1.19版本开始在storage.k8s.io/v1中提供。 l CSINode从社区v1.17版本开始在storage.k8s.io/v1中提供。 l StorageClass从社区v1.6版本开始在storage.k8s.io/v1中提供。 l VolumeAttachment从社区v1.13版本开始在storage.k8s.io/v1中提供。 |
表 Kubernetes社区v1.16版本中废弃的API
| 资源名称 | 废弃API版本 | 替代API版本 | 变更说明 |
|---|---|---|---|
| NetworkPolicy | extensions/v1beta1 | networking.k8s.io/v1 （该API从社区v1.8版本开始可用） | - |
| DaemonSet | extensions/v1beta1 apps/v1beta2 | apps/v1 （该API从社区v1.9版本开始可用） | lspec.templateGeneration字段被删除。 l spec.selector现在变成必需字段，并且在对象创建之后不可变更； 可以将现有模板的标签作为选择算符以实现无缝迁移。 l spec.updateStrategy.type的默认值变为 RollingUpdate（extensions/v1beta1API版本中的默认值是 OnDelete ）。 |
| Deployment | extensions/v1beta1 apps/v1beta1 apps/v1beta2 | apps/v1 （该API从社区v1.9版本开始可用） | lspec.rollbackTo字段被删除。 l spec.selector字段现在变为必需字段，并且在Deployment创建之后不可变更； 可以使用现有的模板的标签作为选择算符以实现无缝迁移。 l spec.progressDeadlineSeconds的默认值变为600秒 （extensions/v1beta1中的默认值是没有期限）。 l spec.revisionHistoryLimit的默认值变为10（apps/v1beta1API版本中此字段默认值为2，在extensions/v1beta1API版本中的默认行为是保留所有历史记录）。 l maxSurge和 maxUnavailable的默认值变为25%（在 extensions/v1beta1API版本中，这些字段的默认值是1）。 |
| StatefulSet | apps/v1beta1 apps/v1beta2 | apps/v1 （该API从社区v1.9版本开始可用） | lspec.selector字段现在变为必需字段，并且在StatefulSet创建之后不可变更； 可以使用现有的模板的标签作为选择算符以实现无缝迁移。 l spec.updateStrategy.type的默认值变为 RollingUpdate（apps/v1beta1API版本中的默认值是 OnDelete ）。 |
| ReplicaSet | extensions/v1beta1 apps/v1beta1 apps/v1beta2 | apps/v1 （该API从社区v1.9版本开始可用） | spec.selector现在变成必需字段，并且在对象创建之后不可变更； 可以将现有模板的标签作为选择算符以实现无缝迁移。 |
| PodSecurityPolicy | extensions/v1beta1 | policy/v1beta1 （该API从社区v1.10版本开始可用） | policy/v1beta1API版本的PodSecurityPolicy会在v1.25版本中移除。 |
升级备份说明
目前集群升级备份方式如下：
| 备份方式 | 备份对象 | 备份方式 | 备份时间 | 回滚时间 | 说明 |
|---|---|---|---|---|---|
| etcd数据备份 | etcd数据 | 升级流程中自动备份 | 1-5min | 2h | 必选备份，升级过程中自动进行，用户无需关注 |
| CBR整机备份 | 控制节点磁盘，包括组件镜像、配置、日志以及etcd数据 | 通过页面一键备份（手动触发） | 20min-2h（受当前区域云备份任务排队情况影响） | 20min | 该功能逐步由EVS快照备份替代 |
| EVS快照备份 | 控制节点磁盘，包括组件镜像、配置、日志以及etcd数据 | 通过页面一键备份（手动触发） | 1-5min | 20min | 该功能上线中 对于已上线的区域，EVS快照备份将替代CBR整机备份 |
