Kubernetes v1.37 StorageVersionMigration 升级前如何规划

Kubernetes v1.37 的 StorageVersionMigration 已经进入稳定阶段，并在 v1.37 集群中默认启用。升级前不要把它理解成“执行一次命令就完成版本迁移”，更稳妥的做法是按 API group 和 resource 拆分计划：先确认哪个版本是新的 storage version，再逐项创建迁移对象，最后用状态和 CRD 的 storedVersions 判断是否收尾。

官方资料：https://kubernetes.io/blog/2026/08/31/kubernetes-v1-37-storage-version-migration-ga/

官方任务指南：https://kubernetes.io/docs/tasks/manage-kubernetes-objects/storage-version-migration/

先把升级对象和回退边界列清楚

先执行版本和 API 检查，确认当前连接的是目标集群，并记录待迁移 CRD 的 group、plural resource、served 版本、storage 版本以及 status.storedVersions。v1.37 的稳定 API 是 storagemigration.k8s.io/v1；如果控制面还不是 v1.37，不能直接套用“默认启用”的判断，应按实际版本和特性门控核对。

# 先确认客户端连接的控制面版本，避免把计划应用到错误集群
kubectl version

# 确认迁移 API 可发现，并查看 CRD 的版本存储状态
kubectl api-resources | grep -i storageversionmigration
kubectl get crd crontabs.example.com -o jsonpath='{.status.storedVersions}{"\n"}'

这里的重点不是记住某个命令，而是建立迁移清单。若旧版本仍在 storedVersions 中，说明还有对象以旧存储版本存在；若转换 webhook、schema 或客户端仍依赖旧字段，先修兼容性，不要急着发起迁移。

先更新 CRD，再按资源创建迁移对象

规划顺序建议是“CRD 目标版本就绪，再提交迁移请求”。下面的示例只针对一个自定义资源，实际项目要把 group 和 resource 换成自己的值；resource 填复数名，不是 Kind。

# 迁移请求只描述一个 group/resource，便于单独观察和重试
apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-storage-migration
spec:
  resource:
    group: example.com
    resource: crontabs

应用后不要马上删除旧版本。先等待迁移条件完成，再检查 CRD 的 storedVersions 是否只剩目标版本。官方 API 将迁移对象的资源指向固定下来，状态中的 Succeeded 反映控制器是否完成了这项资源的重写。

# 创建迁移对象，并等待该对象报告成功
kubectl apply -f crontabs-storage-migration.yaml
kubectl wait --for=condition=Succeeded \
  storageversionmigration.storagemigration.k8s.io/crontabs-storage-migration

# 成功后再次检查旧存储版本是否已经退出记录
kubectl get crd crontabs.example.com -o jsonpath='{.status.storedVersions}{"\n"}'

把观察、灰度和回归检查写进发布窗口

大资源量或高写入资源不要在同一窗口一次创建很多迁移对象。可以先选一个低风险资源，记录迁移开始前后的对象数量、API server 和 etcd 负载、转换 webhook 错误，再按清单继续。迁移期间重点看状态条件和事件；如果出现失败条件，先保留对象和日志，不要靠反复 apply 掩盖原因。

完成后至少做三类检查：用旧版本和新版本客户端各读一次，验证转换结果一致；抽样写入一条业务对象，验证 webhook 和 schema；确认 CRD 的 storedVersions 已移除旧版本。若业务仍依赖旧版本 API，回滚 CRD 文件并不等于把已经重写的对象恢复成旧编码，因此回退方案要在升级前单独评审。

常见问题

StorageVersionMigration 会修改 API 版本字段吗？

它的目标是重新写入对象，使对象落到当前默认存储版本；客户端请求使用哪个 served 版本，仍由 API 版本协商和转换规则决定。

为什么 apply 成功还不能算迁移完成？

apply 只说明迁移请求对象被接受。真正的完成信号应看迁移对象的 Succeeded 条件、失败信息和 CRD 的 storedVersions。

能不能把多个资源写进一个迁移对象？

不能。一个 StorageVersionMigration 指向一个 group/resource，多个资源应拆成多个对象，便于隔离风险和记录结果。