版本演进与升级

Kubernetes 每年通常发布三个次要版本（minor version），上游只维护最近三个次要版本。生产环境应使用仍受支持的版本，并及时安装最新补丁版本（patch version）。

版本号 1.36.2 中，1 是主版本，36 是次要版本，2 是补丁版本。次要版本可能引入 API、功能门控和组件行为变化，补丁版本主要包含缺陷和安全修复。

本文记录上游 Kubernetes 的主要变化。云厂商托管集群、CNI、CSI、Ingress Controller、GPU Operator 等组件有独立的兼容矩阵，升级前必须分别确认。

支持状态

截至 2026 年 8 月，上游维护的次要版本为 1.36、1.35 和 1.34。1.33 及更早版本已经停止维护，不再接收常规缺陷和安全修复。

版本	状态	说明
1.36	当前版本	适合新建集群，选择最新可用补丁版本
1.35	受支持	可用于组件尚未适配 1.36 的环境
1.34	受支持，接近维护阶段	应规划升级，不建议作为新集群长期基线
1.33 及更早版本	EOL	应逐个次要版本升级到受支持版本

具体补丁版本和 EOL 日期以官方发布页面为准，不在长期文档中固定容易过期的补丁号。

---

逐版本主要变化

Kubernetes 1.23

1.23 是本系列旧环境的起点，目前已经 EOL。

主要变化：

• IPv4/IPv6 双栈网络进入 GA。
• HorizontalPodAutoscaler 的 autoscaling/v2 API 进入 GA，支持多指标和更完整的扩缩容行为配置。
• Pod Security Admission 进入 Beta，为后续替代 PodSecurityPolicy 做准备。
• CSI Migration 持续推进，存储插件逐渐从 Kubernetes 核心代码迁移到 CSI 驱动。

升级关注：

• 这是最后一个内置 dockershim 的版本。
• 在升级 1.24 前将运行时迁移到 containerd、CRI-O，或者显式部署 cri-dockerd。
• 将 HPA 清单迁移到 autoscaling/v2。

Kubernetes 1.24

主要变化：

• dockershim 从 kubelet 中移除，Docker Engine 不再能够作为内置 CRI 运行时直接使用。
• ServiceAccount 不再自动创建长期有效的 Secret Token，推荐使用 TokenRequest API 和投射式短期 Token。
• StatefulSet 支持配置滚动更新期间最大不可用副本数，发布时仍属于 Alpha 能力。
• OpenAPI v3 支持进入 Beta，服务端字段校验能力继续增强。

升级关注：

• 确认每个节点都使用可用的 CRI endpoint。
• 依赖自动生成 *-token-* Secret 的脚本改用短期 Token：

kubectl create token <service-account> -n <namespace>

Kubernetes 1.25

主要变化：

• Pod Security Admission 进入 GA，通过命名空间标签实施 privileged、baseline 和 restricted 策略。
• cgroup v2 支持进入 GA。
• 临时容器（Ephemeral Containers）进入 GA，可配合 kubectl debug 排查运行中的 Pod。
• Core CSI Migration 进入 GA，云存储应使用对应 CSI 驱动。

移除与兼容性：

• PodSecurityPolicy 被移除，应迁移到 Pod Security Admission 或准入控制器。
• batch/v1beta1 CronJob、policy/v1beta1 PodDisruptionBudget、autoscaling/v2beta1 HPA 不再提供。
• PDB 使用 policy/v1 时，空选择器 {} 会匹配命名空间内所有 Pod，与旧 API 的语义不同。

Kubernetes 1.26

主要变化：

• Kubernetes 容器镜像仓库迁移到 registry.k8s.io。
• Windows HostProcess Containers 进入 GA。
• StatefulSet 的 minReadySeconds 进入 GA。
• Dynamic Resource Allocation（DRA）首次以 Alpha 形式引入，用于表达 GPU、加速器等设备需求。

移除与兼容性：

• autoscaling/v2beta2 HPA 不再提供，必须使用 autoscaling/v2。
• flowcontrol.apiserver.k8s.io/v1beta1 不再提供。
• 旧镜像地址白名单、镜像代理和离线同步任务需要加入 registry.k8s.io。

Kubernetes 1.27

主要变化：

• StatefulSet 的 startOrdinal 进入 Beta，可让副本序号从非零值开始。
• Job 的可变调度指令进入 GA，可在 Job 挂起期间修改节点选择、亲和性等调度字段。
• Pod 原地调整 CPU/内存资源（In-place Pod Resize）以 Alpha 形式引入。
• Seccomp 默认配置能力进入 GA。

移除与兼容性：

• storage.k8s.io/v1beta1 CSIStorageCapacity 不再提供，应使用 storage.k8s.io/v1。
• 大部分云厂商 in-tree 存储插件已完成 CSI 迁移，应检查 StorageClass 的 provisioner。

Kubernetes 1.28

主要变化：

• 原生 Sidecar Containers 进入 Alpha，通过带 restartPolicy: Always 的 init container 表达先启动、后终止的 sidecar。
• Linux 节点 swap 支持进入 Beta，但仍需显式配置 kubelet 策略。
• 非优雅节点关闭处理进入 GA，节点突然断电时可正确处理卷和 Pod。
• Retroactive Default StorageClass Assignment 进入 GA，可为较早创建且未指定 StorageClass 的 PVC 补用默认类。
• Mixed Version Proxy 进入 Alpha，改进多控制平面滚动升级期间的 API 请求路由。

升级关注：

• 使用 sidecar 新语义前，确认 kubelet、运行时及相关控制器全部支持。
• 允许 swap 不等于取消资源管理，仍需设置 requests、limits 和 memorySwap。

Kubernetes 1.29

主要变化：

• ReadWriteOncePod 访问模式进入 GA，保证一个 PVC 同时只被集群中的一个 Pod 挂载。
• CSI 卷扩容相关的 NodeExpandSecret 能力进入 GA。
• LoadBalancerIPMode 进入 Alpha，用于描述 LoadBalancer 地址是 VIP 还是 Proxy 模式。
• VolumeAttributesClass 进入 Alpha，为在线修改卷属性提供 API 基础。
• Sidecar Containers 升级为 Beta并默认启用。

架构变化：

• 云厂商集成已经外置，cloud-controller-manager 和 CSI 驱动由云厂商独立维护。
• Gateway API 1.0 在 Kubernetes 项目之外独立发布，新的南北向流量设计应开始评估 Gateway API。

Kubernetes 1.30

主要变化：

• AppArmor 支持进入 GA，Pod 可通过 securityContext.appArmorProfile 使用结构化配置。
• kubelet VolumeManager 在重启后的卷状态重建进入 GA，提高节点重启后的存储可靠性。
• Aggregated Discovery 进入 GA，降低客户端发现大量 API Group 的开销。
• kubectl delete --interactive 进入 GA，为批量删除增加交互确认。

移除与兼容性：

• SecurityContextDeny 准入插件被移除，应使用 Pod Security Admission。
• AppArmor 的旧注解写法应迁移到结构化字段。

Kubernetes 1.31

主要变化：

• AppArmor 旧 Beta 注解被移除，应使用 securityContext.appArmorProfile。
• 通过 watch cache 提供强一致读取进入 Beta，降低大型集群对 etcd 的直接读取压力。
• OCI Image Volume 进入 Alpha，可把 OCI artifact 作为只读卷使用。
• kube-proxy 的 nftables 模式进入 Alpha，为新 Linux 数据面实现提供选择。
• 调度器 QueueingHint 机制继续完善，减少无意义的 Pod 重入队。

升级关注：

• 检查清单是否仍使用 container.apparmor.security.beta.kubernetes.io/* 注解。
• 自定义调度器插件需要检查 QueueingHint 相关接口变化。

Kubernetes 1.32

主要变化：

• StatefulSet PVC 自动删除策略进入 GA，可通过 persistentVolumeClaimRetentionPolicy 控制缩容或删除时的 PVC 行为。
• 结构化鉴权配置进入 GA，API Server 可以用配置文件组织多个 authorizer 和 CEL 条件。
• Custom Resource Field Selectors 进入 GA，CRD 可以声明可索引字段。
• memory-backed emptyDir 的尺寸核算得到改进。
• 新版结构化参数 DRA 进入 Beta，旧 DRA 实现被移除。

移除与兼容性：

• flowcontrol.apiserver.k8s.io/v1beta3 被移除，使用 flowcontrol.apiserver.k8s.io/v1。
• 使用早期 DRA API 的清单和驱动必须迁移。

Kubernetes 1.33

主要变化：

• Pod 原地调整 CPU/内存资源进入 Beta并默认启用，通过 Pod resize 子资源操作。
• Job successPolicy 进入 GA，可定义 Indexed Job 达到何种成功条件后结束。
• Job 每索引重试限制进入 GA，适合并行批处理任务隔离失败。
• Volume Populators 进入 GA，PVC 可以从自定义数据源填充。
• Sidecar Containers 进入 GA，原生 sidecar 生命周期语义可以稳定使用。
• Pod 的 metadata.generation 和 status.observedGeneration 初步引入，便于跟踪 kubelet 是否观察到最新 Pod 规约。

升级关注：

• VPA 或自研资源控制器需要确认是否使用 resize 子资源。
• 镜像拉取凭据校验增强仍包含实验性能力，启用 feature gate 前需验证运行时支持。

Kubernetes 1.34

主要变化：

• Dynamic Resource Allocation 核心能力进入 GA，为 GPU、TPU、NIC 等设备提供比传统 Device Plugin 更灵活的声明和分配模型。
• AppArmor、Node Swap、API Server Tracing、结构化认证配置等能力进入 GA。
• VolumeAttributesClass 进入 GA，可在 CSI 驱动支持时修改卷类型或性能属性。
• Job podReplacementPolicy 进入 GA，可等待失败 Pod 完全终止后再创建替代 Pod。
• LIST 请求的流式编码和 watch cache 优化降低大型集群控制面内存峰值。

实验性能力：

• Container Restart Rules 进入 Alpha，可根据容器退出码定义单容器重启策略。
• Pod Certificate 和运行时环境变量文件进入 Alpha，不应直接作为通用生产基线。

Kubernetes 1.35

主要变化：

• Pod metadata.generation、status.observedGeneration 进入 GA，控制器能够可靠判断 kubelet 是否处理了最新规约。
• Service trafficDistribution 增加 PreferSameNode；PreferClose 以更明确的 PreferSameZone 名称表达同可用区偏好。
• Job managedBy 进入 GA，外部控制器可以接管特定 Job 的协调逻辑。
• Pod 原地资源调整进入 GA，CPU 和内存调整不再总是要求重建 Pod。
• supplementalGroupsPolicy 进入 GA，加强挂载卷时附加组的控制。

实验性能力：

• Workload API 与 PodGroup/Gang Scheduling 进入 Alpha，面向 AI、HPC 和批处理的成组调度。
• Restart All Containers、挂起 Job 的可变资源等能力进入 Alpha。

Kubernetes 1.36

主要变化：

• Kubernetes 内置类型的 Declarative Validation 进入 GA，使 API 校验规则更统一。
• Mixed Version Proxy 进入 Beta并默认启用，改善 HA 控制平面滚动升级期间的跨版本 API 请求。
• 工作负载感知调度继续演进，Workload/PodGroup API 更新为 scheduling.k8s.io/v1alpha2，仍属于实验性功能。
• Server-side Sharded List/Watch 进入 Alpha，为超大规模控制器减少每个副本接收的无关事件。
• kubeadm 配置使用 kubeadm.k8s.io/v1beta4，新搭建文档不应再以 v1beta3 为基线。

移除与弃用：

• gitRepo volume 被永久禁用，应改用 init container 或 git-sync 一类工具拉取仓库内容。
• Service.spec.externalIPs 被弃用，新设计应优先使用 LoadBalancer、Gateway API 或受控网络方案。

---

kubeadm 升级原则

逐个次要版本升级

kubeadm 不支持跳过次要版本。一个 1.23 集群必须按以下路径升级：

1.23 → 1.24 → 1.25 → 1.26 → 1.27 → 1.28 → 1.29
     → 1.30 → 1.31 → 1.32 → 1.33 → 1.34 → 1.35 → 1.36

每一跳都应先升级到当前次要版本的最新补丁，再进入下一个次要版本。如此长的跨代升级需要分别验证 CNI、CSI、CoreDNS、Ingress/Gateway、监控和业务 API；在很多情况下，新建受支持版本集群并迁移工作负载比原地连续升级风险更低。

版本偏差

• kube-apiserver 是版本偏差的基准，HA 控制平面升级期间允许短暂存在受支持范围内的版本差异。
• kubelet 不能比 kube-apiserver 新。
• kube-controller-manager、kube-scheduler 和 cloud-controller-manager 不应比 kube-apiserver 新。
• kubeadm 的具体偏差范围随版本变化，操作前应阅读目标版本的官方升级说明。

单个次要版本的升级顺序

1. 阅读源版本和目标版本 release notes、弃用指南及组件兼容矩阵。
2. 升级源版本到该 minor 的最新 patch。
3. 检查废弃 API、准入策略、feature gate 和运行时配置。
4. 备份 etcd，并在隔离环境验证快照可以恢复。
5. 先升级第一个 control plane 节点的 kubeadm，再执行 kubeadm upgrade apply。
6. 逐个升级其余 control plane 节点，执行 kubeadm upgrade node。
7. 逐个 drain、升级、重启并 uncordon worker 节点。
8. 验证系统组件、DNS、网络策略、存储挂载、服务入口和业务指标。

---

升级前检查

集群和组件状态

kubeadm version
kubectl version
kubelet --version
kubectl get nodes -o wide
kubectl get pods -A
kubectl get --raw='/readyz?verbose'

确认节点处于 Ready，控制平面和系统 Pod 正常，没有无法解释的持续告警，并且节点具有足够空间完成镜像拉取和静态 Pod 更新。

检查废弃 API

可以通过 API Server 返回的 deprecation warning、apiserver_requested_deprecated_apis 指标、审计日志以及 Pluto、kubent 等工具定位旧 API。

清单修改后先使用服务端校验：

kubectl apply --server-side --dry-run=server -f <manifest.yaml>

检查 PodDisruptionBudget

kubectl get pdb -A
kubectl get pods -A -o wide

PDB、单副本工作负载、本地卷和 emptyDir 都会影响 drain。不要为了让 drain 通过而直接删除保护措施，应先确认可接受的业务中断方式。

备份 etcd

以下示例适用于 kubeadm 本地 etcd。外置 etcd 应使用其独立证书和备份流程：

export ETCDCTL_API=3
etcdctl snapshot save /var/backups/etcd-snapshot.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
  --key=/etc/kubernetes/pki/etcd/healthcheck-client.key

etcdutl snapshot status /var/backups/etcd-snapshot.db --write-out=table

快照文件需要复制到集群外，并定期执行恢复演练。

---

单节点升级模板

不同 Linux 发行版和目标 minor 使用不同的 pkgs.k8s.io 仓库。下面只展示流程，不固定具体版本号。

第一个 control plane 节点

# 将软件源切换到目标 minor 后，先只升级 kubeadm
sudo apt-mark unhold kubeadm
sudo apt-get update
sudo apt-get install -y kubeadm='<target-version>'
sudo apt-mark hold kubeadm

sudo kubeadm upgrade plan
sudo kubeadm upgrade apply <target-version-with-v-prefix>

kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data
sudo apt-mark unhold kubelet kubectl
sudo apt-get install -y kubelet='<target-version>' kubectl='<target-version>'
sudo apt-mark hold kubelet kubectl
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl uncordon <node-name>

不要把 --ignore-preflight-errors=all 写入常规升级流程。若某项预检失败，应理解原因，只对已经评估过的具体检查项使用 --ignore-preflight-errors=<name>。

其他 control plane 和 worker 节点

kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# 在目标节点升级 kubeadm 后执行
sudo kubeadm upgrade node

# 再升级 kubelet，必要时升级 kubectl，并重启 kubelet
sudo systemctl daemon-reload
sudo systemctl restart kubelet

kubectl uncordon <node-name>

每次只操作一个节点，并等待该节点和关键工作负载恢复后再继续。

---

升级后验证

kubectl get nodes -o wide
kubectl get pods -A -o wide
kubectl get events -A --sort-by=.lastTimestamp
kubectl get --raw='/readyz?verbose'
kubectl cluster-info dump --output-directory=/tmp/cluster-info

至少验证：

• 所有节点版本、容器运行时和状态符合预期。
• API Server、scheduler、controller-manager、etcd、CoreDNS 正常。
• Pod 跨节点通信、Service、DNS、NetworkPolicy 正常。
• PVC 可以挂载、写入、扩容和重新调度。
• Ingress 或 Gateway、证书、外部负载均衡正常。
• HPA、监控、日志、告警和备份任务正常。
• 不再产生 deprecated API warning。

参考资料

• Kubernetes Releases
• Upgrading kubeadm clusters
• Version Skew Policy
• Deprecated API Migration Guide
• Kubernetes 1.36 Release