KnoAI 技术站

主题

Kubernetes v1.37：Storage Version Migration（SVM）正式 GA —— 存储版本演进终于“自驱动” ​

一句话摘要：Kubernetes v1.37 将 StorageVersionMigration（SVM）控制器设为默认启用（GA），标志着 Kubernetes 首次在控制平面内原生、自动、可观察地完成存量 API 对象的存储版本升级（如从 v1alpha1 → v1）与加密密钥轮转触发重写，彻底告别 kubectl get | kubectl replace 脚本和外部 kube-storage-version-migrator 组件。

🌐 背景动机：为什么“存储版本静默滞留”是 SRE 的隐形定时炸弹？ ​

Kubernetes 的 API 机制天然存在一个关键张力：API 版本演进 ≠ 存储版本即时更新。

当你声明一个 CRD（例如 MyDatabase.v1.example.com），其 .spec.versions 中可定义多个可服务版本（v1alpha1, v1beta1, v1），但其中仅有一个被指定为 .spec.conversion.strategy: Webhook 或 .spec.conversion.strategy: None 下的 storage version（通过 .spec.versions[n].storage: true 标记）。这个 storage version 是 etcd 中对象实际序列化的 schema——它决定了 JSON/YAML 字节流如何落盘。

⚠️ 关键问题在于：API Server 仅在 写入（create/update/patch）时执行 conversion，而 读取（get/list/watch）时仅做反序列化 + 可选的 on-the-fly conversion。
这意味着：

  • 一旦你将 CRD 的 storage version 从 v1alpha1 切换到 v1，所有新创建的对象立刻以 v1 格式存入 etcd；
  • 但已有数万条 v1alpha1 格式的旧对象，仍静静躺在 etcd 里，永不自动升级；
  • 你无法安全删除 v1alpha1 的 serving 支持（即从 .status.storedVersions 中移除），因为 kubectl get mydatabases --version=v1alpha1 仍需能成功返回这些“过期但合法”的对象；
  • 更危险的是：当启用 EncryptionConfiguration 进行静态加密或轮换 KMS 密钥时，只有被重新 PUT/PATCH 的对象才会用新密钥加密——etcd 中大量“冷数据”长期裸奔（未加密）或滞留在旧密钥下，直接违反 PCI-DSS / HIPAA 等合规基线。

过去，SRE 团队只能靠三类脆弱方案“硬扛”：

  1. 手工脚本暴力重写：kubectl get mydbs -o json | jq 'del(.metadata.resourceVersion, .metadata.uid)' | kubectl replace --force --raw="/apis/example.com/v1/mydatabases" —— 效率低、易出错、无进度跟踪、阻塞集群写入；
  2. 外部迁移器组件：kube-storage-version-migrator（由 SIG-API-Machinery 维护的 out-of-tree controller）—— 需额外部署、权限管理复杂、与 kube-apiserver 协同弱、缺乏统一观测面；
  3. “等用户自然触发”：寄希望于业务方主动 PATCH 对象——在稳定运行的生产集群中，某些 CR 实例可能数月无变更，成为永久的技术债。

这本质上暴露了 Kubernetes 控制平面的一个能力缺口：缺乏对“存量数据格式现代化”的声明式、可审计、可中断的生命周期管理能力。 SVM 的 GA，正是对这一缺口的精准缝合。

⚙️ 核心技术：StorageVersionMigration API 与控制器工作流 ​

SVM 的核心是一个内置的、集群范围的 controller，监听 storagemigration.k8s.io/v1 类型的 StorageVersionMigration 资源。它不修改用户对象语义，只驱动 API Server 对目标资源执行“无损重写”（read → convert → write back），确保其以新 storage version 持久化。

✅ 启用状态验证（v1.37 默认开启） ​

无需任何操作，v1.37+ 集群中以下组件已就绪：

bash
# 查看控制器是否运行（应处于 Running 状态）
kubectl get pods -n kube-system | grep storage-version-migration

# 检查 API 资源可用性
kubectl api-resources | grep storagemigration
# 输出：storageversionmigrations          svm          storagemigration.k8s.io/v1   false        StorageVersionMigration

📜 声明一次迁移任务（YAML 示例） ​

假设你有一个 CRD clusters.database.example.com，当前 storage version 为 v1beta1，计划升级至 v1：

yaml
# svm-migrate-clusters.yaml
apiVersion: storagemigration.k8s.io/v1
kind: StorageVersionMigration
metadata:
  name: migrate-clusters-to-v1
  namespace: default  # 注意：SVM 资源是 namespaced，但影响全局存储
spec:
  resource:
    group: database.example.com
    version: v1beta1  # 当前 storage version（必须匹配 CRD.status.storedVersions 中的旧版）
    resource: clusters
  # targetVersion 是 CRD 中新设置的 storage version（需提前在 CRD 中配置好！）
  # 即：先更新 CRD.spec.versions[*].storage=true for v1，再提交此 SVM
  targetVersion: v1
  # 可选：限制并发重写速率（避免冲击 etcd）
  progressDeadlineSeconds: 3600
  # 可选：分批次处理（按 namespace 或 label selector）
  scope:
    namespace: "prod"  # 仅迁移 prod 命名空间下的 clusters

🔁 迁移过程详解（Controller 如何工作？） ​

  1. 发现阶段：Controller 列举所有 clusters.database.example.com 对象（受 scope 限制），记录其当前 apiVersion 和 resourceVersion；
  2. 转换阶段：对每个对象发起 GET /apis/database.example.com/v1beta1/namespaces/{ns}/clusters/{name} → API Server 自动将其转换为 v1 内部表示；
  3. 写回阶段：Controller 发起 PUT /apis/database.example.com/v1/namespaces/{ns}/clusters/{name}，携带转换后的对象（含原始 metadata.uid 和 metadata.resourceVersion）；
  4. 幂等保障：若对象已在 etcd 中为 v1 格式，API Server 返回 409 Conflict，Controller 跳过并标记为 Succeeded；
  5. 状态反馈：status.conditions 实时反映进度，status.resourcesMigrated 统计成功数，status.failedResources 列出失败项（含错误原因）。

💡 技术判断：SVM 并非“后台扫描 etcd”，而是严格走 Kubernetes API 通道，因此完全兼容 RBAC、Admission Webhook、Audit Logging。这意味着你可以审计每一次重写（audit.log 中出现 update 动作）、拦截恶意迁移（通过 ValidatingWebhook 拒绝非法 StorageVersionMigration 创建）、甚至在重写前注入自定义逻辑（e.g., 数据校验 webhook）。

🛠️ 运维建议：从“被动救火”到“主动治理” ​

✅ 最佳实践清单 ​

场景推荐动作注意事项
CRD 版本迭代在 kubectl apply -f crd.yaml 切换 storage version 后，立即提交 StorageVersionMigration必须确保 CRD 中 v1 已存在且 storage: true，否则 SVM 会报 InvalidTargetVersion
静态加密密钥轮转创建 SVM 任务指向所有需加密的内置资源（如 secrets, configmaps）对 Secret 迁移会触发重加密，但 ServiceAccount token 不受影响（因其由 controller-manager 管理）
大规模集群迁移使用 scope.namespaceSelector + progressDeadlineSeconds 分批执行避免单次迁移超 10k 对象；监控 etcd_disk_wal_fsync_duration_seconds 防止 wal 延迟飙升
故障排查kubectl describe svm migrate-clusters-to-v1 查看 status.conditions 和 status.failedResources失败常见原因：RBAC 权限不足（需 update clusters）、conversion webhook timeout、etcd transient error

⚠️ 风险规避提示 ​

  • 不要删除正在迁移中的 CRD 版本：即使 SVM 进度显示 100%，也请等待 kubectl get crd clusters.database.example.com -o jsonpath='{.status.storedVersions}' 确认旧版已消失；
  • SVM 不替代备份：迁移前务必执行 etcdctl snapshot save —— SVM 本身不保证原子性，极端情况下可能产生部分对象升级、部分未升级的状态；
  • 第三方 Operator 兼容性：若 CR 的 finalizer 依赖特定 apiVersion，重写后可能触发意外 reconcile；建议在测试集群中验证 operator 行为。

🔗 延伸阅读：超越 SVM 的存储治理演进 ​

SVM 的 GA 是 Kubernetes 存储层自治化的里程碑，但它只是更大图景的一环：

  • Kubernetes v1.38 规划中：StorageVersionMigration 将支持 dryRun: true 模式，允许预估迁移耗时与资源开销；
  • etcd v3.6+ 深度集成：社区正探索让 etcd 提供 “schema-aware compaction”，在压缩历史版本时自动丢弃旧 storage version 的冗余字段（减少存储膨胀）；
  • AI-Native Storage 治理：结合 vLLM Serving 的可观测性，未来可能出现 StorageVersionMigrationPolicy CRD，根据对象访问热度、P99 延迟、加密密钥生命周期等指标，AI 驱动动态调度迁移优先级（如：高频访问的 Secret 优先轮转密钥，冷数据延后）。

📌 最后提醒：SVM 不是银弹。它解决的是“数据格式一致性”问题，而非“数据语义兼容性”。当你从 v1alpha1 升级到 v1 时，若 conversion webhook 引入了字段重命名或默认值变更，仍需业务方充分测试。真正的稳定性，永远建立在清晰的 API 设计契约与渐进式迁移策略之上。

作者注：本文基于 Kubernetes 官方 v1.37 博客深度解读，并融合一线 SRE 实战经验。欢迎在 KnoAI 技术站 讨论 SVM 在多租户、FinOps、AI infra 场景下的落地细节。