升级前须知

所有升级路径

请关注Kubernetes API变更，详情请参见废弃API说明。

检查集群中已使用的API版本，避免使用已废弃的API版本或修改为废弃API说明中建议替换的API版本。

v1.28升级至v1.29、v1.31

Kubernetes v1.29中更改kube-proxy启动的行为，允许kube-proxy设置低于节点sysctl设置的参数值。如节点nf_conntrack_max内核参数值设置为1000000，而kube-proxy计算的值为131072，那么此内核参数会使用kube-proxy计算的值131072。社区PR链接为：https://github.com/kubernetes/kubernetes/pull/120448

产生大量链接的节点例如网关节点极可能遇到该问题。请务必确认nf_conntrack_max是否曾使用sysctl修改为较大值（例如4294967295或1000000），该参数在节点升级后会以kube-proxy计算的值为准，被刷新覆盖为一个较小值（10w+或20w+），影响业务高峰期流量。

请使用节点池kube-proxy组件配置conntrack-min替代直接修改OS内核参数nf_conntrack_max，参考节点池配置管理。

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中，需要参照以下步骤进行：
  1. 确认集群为CCE v1.23的最新版本。
  2. 迁移PodSecurityPolicy的相关能力迁移到Pod Security Admission，请参见Pod Security Admission配置。
  3. 确认迁移后功能正常，再升级为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存在兼容性问题。若控制节点升级成功后，节点升级失败或待升级节点发生重启，则节点有极大概率为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。

1. 正常升级流程不会触发此场景。
2. 在控制节点升级完成后尽量避免使用暂停升级功能，快速升级完Node节点。
3. 若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.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规避该问题。

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

是

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。

FlowSchema 和 PriorityLevelConfiguration

flowcontrol.apiserver.k8s.io/v1beta2

flowcontrol.apiserver.k8s.io/v1

（该API从社区v1.29版本开始可用）

flowcontrol.apiserver.k8s.io/v1beta3

（该API从社区v1.26版本开始可用）

• flowcontrol.apiserver.k8s.io/v1中的显着变化：

  PriorityLevelConfiguration的spec.limited.assuredConcurrencyShares字段已被重命名为spec.limited.nominalConcurrencyShares，仅在未指定时默认为30，并且显式值0不会更改为 30。

• flowcontrol.apiserver.k8s.io/v1beta3中需要额外注意的变更：

  PriorityLevelConfiguration的spec.limited.assuredConcurrencyShares字段已被更名为spec.limited.nominalConcurrencyShares。

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版本开始可用）

-

CronJob

batch/v1beta1

batch/v1

（该API从社区v1.21版本开始可用）

-

EndpointSlice

discovery.k8s.io/v1beta1

discovery.k8s.io/v1

（该API从社区v1.21版本开始可用）

此次更新需注意以下变更：

• 每个Endpoint中，topology["kubernetes.io/hostname"]字段已被弃用，请使用nodeName字段代替。
• 每个Endpoint中，topology["kubernetes.io/zone"]字段已被弃用，请使用zone字段代替。
• topology字段被替换为deprecatedTopology，并且在 v1 版本中不可写入。

Event

events.k8s.io/v1beta1

events.k8s.io/v1

（该API从社区v1.19版本开始可用）

此次更新需注意以下变更：

• type 字段只能设置为 Normal 和 Warning 之一。
• involvedObject 字段被更名为 regarding。
• action、reason、reportingController 和 reportingInstance 字段 在创建新的 events.k8s.io/v1 版本 Event 时都是必需的字段。
• 使用 eventTime 而不是已被弃用的 firstTimestamp 字段 （该字段已被更名为 deprecatedFirstTimestamp，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。
• 使用 series.lastObservedTime 而不是已被弃用的 lastTimestamp 字段 （该字段已被更名为 deprecatedLastTimestamp，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。
• 使用 series.count 而不是已被弃用的 count 字段 （该字段已被更名为 deprecatedCount，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。
• 使用 reportingController 而不是已被弃用的 source.component 字段 （该字段已被更名为 deprecatedSource.component，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。
• 使用 reportingInstance 而不是已被弃用的 source.host 字段 （该字段已被更名为 deprecatedSource.host，且不允许出现在新的 events.k8s.io/v1 Event 对象中）。

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准入控制器也会被删除。

请使用Pod Security Admission配置替代。

RuntimeClass

node.k8s.io/v1beta1

node.k8s.io/v1（该API从社区v1.20版本开始可用）

-

MutatingWebhookConfiguration

ValidatingWebhookConfiguration

admissionregistration.k8s.io/v1beta1

admissionregistration.k8s.io/v1

（该API从社区v1.16版本开始可用）

• webhooks[*].failurePolicy 在 v1 版本中默认值从 Ignore 改为 Fail。
• webhooks[*].matchPolicy 在 v1 版本中默认值从 Exact 改为 Equivalent。
• webhooks[*].timeoutSeconds 在 v1 版本中默认值从 30s 改为 10s。
• webhooks[*].sideEffects 的默认值被删除，并且该字段变为必须指定； 在 v1 版本中可选的值只能是 None 和 NoneOnDryRun 之一。
• webhooks[*].admissionReviewVersions 的默认值被删除，在 v1 版本中此字段变为必须指定（AdmissionReview 的被支持版本包括 v1 和 v1beta1）。
• webhooks[*].name 必须在通过 admissionregistration.k8s.io/v1 创建的对象列表中唯一。

CustomResourceDefinition

apiextensions.k8s.io/v1beta1

apiextensions/v1

（该API从社区v1.16版本开始可用）

• spec.scope 的默认值不再是 Namespaced，该字段必须显式指定。
• spec.version 在 v1 版本中被删除，应改用 spec.versions。
• spec.validation 在 v1 版本中被删除，应改用 spec.versions[*].schema。
• spec.subresources 在 v1 版本中被删除，应改用 spec.versions[*].subresources。
• spec.additionalPrinterColumns 在 v1 版本中被删除，应改用 spec.versions[*].additionalPrinterColumns。
• spec.conversion.webhookClientConfig 在 v1 版本中被移动到 spec.conversion.webhook.clientConfig 中。
• spec.conversion.conversionReviewVersions 在 v1 版本中被移动到 spec.conversion.webhook.conversionReviewVersions

• spec.versions[*].schema.openAPIV3Schema 在创建 v1 版本的 CustomResourceDefinition 对象时变成必需字段，并且其取值必须是一个结构化的 Schema。
• spec.preserveUnknownFields: true 在创建 v1 版本的 CustomResourceDefinition 对象时不允许指定；该配置必须在 Schema 定义中使用 x-kubernetes-preserve-unknown-fields: true 来设置。
• 在 v1 版本中，additionalPrinterColumns 的条目中的 JSONPath 字段被更名为 jsonPath（补丁 #66531）。

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（补丁 #32709）

CertificateSigningRequest

certificates.k8s.io/v1beta1

certificates.k8s.io/v1

（该API从社区v1.19版本开始可用）

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版本开始可用）

• spec.backend 字段被更名为 spec.defaultBackend。
• 后端的 serviceName 字段被更名为 service.name。
• 数值表示的后端 servicePort 字段被更名为 service.port.number。
• 字符串表示的后端 servicePort 字段被更名为 service.port.name。
• 对所有要指定的路径，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

• CSIDriver从社区v1.19版本开始在storage.k8s.io/v1中提供。
• CSINode从社区v1.17版本开始在storage.k8s.io/v1中提供。
• StorageClass从社区v1.6 版本开始在storage.k8s.io/v1中提供。
• VolumeAttachment从社区v1.13版本开始在storage.k8s.io/v1中提供。

NetworkPolicy

extensions/v1beta1

networking.k8s.io/v1

（该API从社区v1.8版本开始可用）

-

DaemonSet

extensions/v1beta1

apps/v1beta2

apps/v1

（该API从社区v1.9版本开始可用）

• spec.templateGeneration 字段被删除。
• spec.selector 现在变成必需字段，并且在对象创建之后不可变更； 可以将现有模板的标签作为选择算符以实现无缝迁移。
• spec.updateStrategy.type 的默认值变为 RollingUpdate （extensions/v1beta1 API 版本中的默认值是 OnDelete）。

Deployment

extensions/v1beta1

apps/v1beta1

apps/v1beta2

apps/v1

（该API从社区v1.9版本开始可用）

• spec.rollbackTo 字段被删除。
• spec.selector 字段现在变为必需字段，并且在 Deployment 创建之后不可变更； 可以使用现有的模板的标签作为选择算符以实现无缝迁移。
• spec.progressDeadlineSeconds 的默认值变为 600 秒 （extensions/v1beta1 中的默认值是没有期限）。
• spec.revisionHistoryLimit 的默认值变为 10 （apps/v1beta1 API 版本中此字段默认值为 2，在extensions/v1beta1 API 版本中的默认行为是保留所有历史记录）。
• maxSurge 和 maxUnavailable 的默认值变为 25% （在 extensions/v1beta1 API 版本中，这些字段的默认值是 1）。

StatefulSet

apps/v1beta1

apps/v1beta2

apps/v1

（该API从社区v1.9版本开始可用）

• spec.selector 字段现在变为必需字段，并且在 StatefulSet 创建之后不可变更； 可以使用现有的模板的标签作为选择算符以实现无缝迁移。
• spec.updateStrategy.type 的默认值变为 RollingUpdate （apps/v1beta1 API 版本中的默认值是 OnDelete）。

ReplicaSet

extensions/v1beta1

apps/v1beta1

apps/v1beta2

apps/v1

（该API从社区v1.9版本开始可用）

spec.selector 现在变成必需字段，并且在对象创建之后不可变更； 可以将现有模板的标签作为选择算符以实现无缝迁移。

PodSecurityPolicy

extensions/v1beta1

policy/v1beta1

（该API从社区v1.10版本开始可用）

policy/v1beta1 API 版本的 PodSecurityPolicy 会在 v1.25 版本中移除。