Kubernetes v1.37：存储版本迁移默认启用

存储版本迁移（Storage Version Migration，SVM）在 Kubernetes v1.37 中正式达到一般可用（GA）阶段。

经过多个版本的开发和测试，内置的 StorageVersionMigration API（storagemigration.k8s.io/v1）及控制平面控制器已完全稳定，并在所有 v1.37 Kubernetes 集群中默认启用。

旧存储版本带来的问题

Kubernetes 将 API 资源按特定的存储版本，也就是特定模式表示，写入存储。Kubernetes 与对象存储交互的机制要求资源发生修改，才能确保资源按最新存储版本保存。因此，切换资源的存储版本会带来一些问题。

例如，CRD 演进时，可能需要删除旧 API 版本 v1alpha1，只保留较新的 v1beta1 和 v1。如果存储中仍有使用旧 alpha 版本保存的资源，就不能直接删除该版本。

为了避免问题，可以指定 v1 为新的存储版本，但仅有这一步还不够。新写入的对象会按 v1 保存，已有资源却可能仍以 v1alpha1 或 v1beta1 保存在存储中。必须将每一个旧资源重新写入，使其不再按 alpha 版本序列化和存储，才能安全地从 CRD 的 .status.storedVersions 中移除 v1alpha1，或停止提供该版本的 API。

另一个相关场景是静态加密和密钥轮换。启用静态加密或轮换加密密钥后，已存储的资源仍可能未加密，或仍由旧密钥加密；只有主动经 Kubernetes API 服务器重新写入，它们才会采用新配置。

过去，集群管理员和 CRD 作者需要依赖手工编写的 kubectl get / kubectl replace 脚本，或者部署树外的 kube-storage-version-migrator 组件来强制重写。这些方式通常繁琐、容易出错，而且难以监控。

存储版本迁移如何工作

创建一个声明式的 StorageVersionMigration 对象，即可启动迁移。Kubernetes 控制平面内置的 StorageVersionMigrator 控制器会监听这些对象，自动将已有资源迁移到对应 API 的默认存储版本。

示例：迁移自定义资源 API

假设已经更新 CustomResourceDefinition crontabs.example.com，将其存储版本设为 v1。要让所有已有资源摆脱旧存储版本，可以创建：

apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs

使用 kubectl 应用清单：

kubectl apply -f crontabs-migration.yaml

监控与验证迁移

迁移进行时，StorageVersionMigrator 控制器会更新 StorageVersionMigration 对象的 status。使用以下命令检查：

kubectl get storageversionmigration.storagemigration.k8s.io/crontabs-migration -o yaml

成功迁移会报告值为 True 的 Succeeded 条件：

status:
  conditions:
    - type: Running
      status: "False"
      lastUpdateTime: "2026-08-02T10:05:00Z"
      reason: StorageVersionMigrationInProgress
    - type: Succeeded
      status: "True"
      lastUpdateTime: "2026-08-02T10:05:00Z"
      reason: StorageVersionMigrationSucceeded

迁移成功后，存储中的所有该类资源实例都应采用当前存储版本。对于 CRD，.status.storedVersions 应更新为仅包含首选版本。如果迁移成功后此字段仍未更新，说明迁移期间 CRD 被修改过；此时应重试迁移，才能安全地弃用旧存储版本。

在 CRD 清单中包含迁移

StorageVersionMigration 是标准的声明式 Kubernetes API，因此 CRD 作者可以在升级 CRD 的同时捆绑或触发迁移。例如，可以把迁移对象与更新后的 CustomResourceDefinition 放在同一份清单中：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.example.com
spec:
  group: example.com
  # Updated versions list where v1 has storage: true
  ...
---
apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: crontabs-migration
spec:
  resource:
    group: example.com
    resource: crontabs