更新时间:2024-01-26 GMT+08:00

升级前须知

升级前,您可以在CCE控制台确认您的集群是否可以进行升级操作。确认方法请参见升级概述

注意事项

升级集群前,您需要知晓以下事项:

  • 集群升级操作不可回退,请务必慎重并选择合适的时间段进行升级,以减少升级对您的业务带来的影响。为了您的数据安全,强烈建议您先备份数据然后再升级。
  • 集群升级前,请确认集群中未执行高危操作,否则可能导致集群升级失败或升级后配置丢失。例如,常见的高危操作有本地修改集群节点的配置、通过ELB控制台修改CCE管理的监听器配置等。建议您通过CCE控制台修改相关配置,以便在升级时自动继承。
  • 集群升级前,请查看集群状态是否均为健康状态。
  • 集群升级前,请参考Kubernetes版本发布说明了解每个集群版本发布的特性以及差异,否则可能因为应用不兼容新集群版本而导致升级后异常。例如,您需要检查集群中是否使用了目标版本废弃的API,否则可能导致升级后调用接口失败,详情请参见废弃API说明

集群升级时,以下几点注意事项可能会对您的业务存在影响,请您关注:

  • 集群升级过程中,不建议对集群进行任何操作。尤其是,请勿关机、重启或删除节点,否则会导致升级失败。
  • 集群升级过程中,已运行工作负载业务不会中断,但API Server访问会短暂中断,如果业务需要访问API Server可能会受到影响。
  • 集群升级过程中,将会给节点打上“node.kubernetes.io/upgrade”(效果为“NoSchedule”)的污点,并在集群升级完成后移除该污点。请您不要在节点上手动添加相同键名的污点,即使污点效果不同,也可能会在升级后被系统误删除。

约束与限制

  • 当前支持虚拟机节点的CCE集群升级。
  • 当集群中存在使用私有镜像的节点时,暂不支持升级。
  • 集群升级后,如版本特性中修复了容器引擎Containerd相关漏洞,存量节点需要手动重启Containerd才可以生效,对于存量Pod同样需要通过重启Pod才能生效。
  • 若您将节点上的docker.sock文件通过HostPath方式挂载到Pod内,即docker in docker场景,在升级过程中Docker将会重启,而容器内的sock文件不会变化,可能导致您业务异常,推荐您使用挂载目录的方式挂载sock文件。
  • 容器隧道网络集群升级至1.19.16-r4、1.21.7-r0、1.23.5-r0、1.25.1-r0及之后的版本时,会移除匹配目的地址是容器网段且源地址非容器网段的SNAT规则;如果您之前通过配置VPC路由实现集群外直接访问所有的Pod IP,升级后只支持直接访问对应节点上的Pod IP。

废弃API说明

随着Kubernetes API的演化,API会周期性地被重组或升级,老的API会被弃用并被最终删除。以下为各Kubernetes社区版本中被废弃的API,更多已废弃的API说明请参见已弃用 API 的迁移指南

当某API被废弃时,已经创建的资源对象不受影响,但新建或编辑该资源时将出现API版本被拦截的情况。

表1 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版本开始可用)

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

  • 每个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 字段只能设置为 NormalWarning 之一。
  • involvedObject 字段被更名为 regarding
  • actionreasonreportingControllerreportingInstance 字段 在创建新的 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版本开始可用)

-

表2 Kubernetes社区v1.22版本中废弃的API

资源名称

废弃API版本

替代API版本

变更说明

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 版本中可选的值只能是 NoneNoneOnDryRun 之一。
  • 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版本开始可用)

certificates.k8s.io/v1 中需要额外注意的变更:
  • 对于请求证书的 API 客户端而言:
    • spec.signerName 现在变成必需字段(参阅 已知的 Kubernetes 签署者), 并且通过 certificates.k8s.io/v1 API 不可以创建签署者为 kubernetes.io/legacy-unknown 的请求。
    • spec.usages 现在变成必需字段,其中不可以包含重复的字符串值, 并且只能包含已知的用法字符串。
  • 对于要批准或者签署证书的 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版本开始可用)

  • spec.backend 字段被更名为 spec.defaultBackend
  • 后端的 serviceName 字段被更名为 service.name
  • 数值表示的后端 servicePort 字段被更名为 service.port.number
  • 字符串表示的后端 servicePort 字段被更名为 service.port.name
  • 对所有要指定的路径,pathType 都成为必需字段。 可选项为 PrefixExactImplementationSpecific。 要匹配 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中提供。
表3 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版本开始可用)

  • spec.templateGeneration 字段被删除。
  • spec.selector 现在变成必需字段,并且在对象创建之后不可变更; 可以将现有模板的标签作为选择算符以实现无缝迁移。
  • spec.updateStrategy.type 的默认值变为 RollingUpdateextensions/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 版本中的默认行为是保留所有历史记录)。
  • maxSurgemaxUnavailable 的默认值变为 25% (在 extensions/v1beta1 API 版本中,这些字段的默认值是 1)。

StatefulSet

apps/v1beta1

apps/v1beta2

apps/v1

(该API从社区v1.9版本开始可用)

  • spec.selector 字段现在变为必需字段,并且在 StatefulSet 创建之后不可变更; 可以使用现有的模板的标签作为选择算符以实现无缝迁移。
  • spec.updateStrategy.type 的默认值变为 RollingUpdateapps/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 版本中移除。

版本差异说明

版本升级路径

版本差异

建议自检措施

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,请参见从PodSecurityPolicy迁移到Pod Security Admission
    3. 确认迁移后功能正常,再升级为CCE v1.25版本。
  • 如果您不再使用PodSecurityPolicy能力,则可以在删除集群中的PodSecurityPolicy后,直接升级为CCE v1.25版本。

v1.21升级至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.23

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。

  1. 正常升级流程不会触发此场景。
  2. 在Master升级完成后尽量避免使用暂停升级功能,快速升级完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.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中容器重启。

建议参考表4在升级前修改业务容器的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台节点。

表4 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

升级备份说明

目前集群升级备份方式如下:

  • 集群ETCD数据库备份:CCE服务会在集群升级流程中对etcd数据库进行备份,无需用户确认。
  • Master节点整机备份:在升级界面对集群的Master节点进行整机备份,需要用户手动确认,备份过程会使用云备份服务,备份通常耗时在20分钟左右,若当前局点云备份任务排队较多时,备份时间可能同步延长,推荐用户使用进行整机备份。