3. 存储API版本演进史：v1/v1beta1/v1alpha1的生命周期与迁移

Kubernetes 存储 API 的版本演进遵循严格的 API 弃用策略，理解 v1alpha1 → v1beta1 → v1 的生命周期是避免版本漂移的核心基础。本章以 v1beta1 → v1 的迁移时间线为例，拆解废弃策略与实操校准点。

3.1 存储API版本层级与生命周期

每个存储 API 资源（如 StorageClass、PersistentVolume、VolumeAttachment）都会经历以下阶段：

3.2 废弃策略与迁移时间线（以 v1beta1 → v1 为例）

Kubernetes 官方对存储 API 的废弃遵循 「N-3」规则：

• 废弃公告（Deprecation Notice）：在 v1beta1 对应的 v1 版本发布时，同步标记 v1beta1 为废弃。
• 保留期：v1beta1 版本至少保留 3 个次要版本（例如 v1.21 废弃 → v1.24 移除）。
• 移除时间：在废弃后的第 4 个次要版本中彻底移除该 beta 版本。

以 VolumeAttachment v1beta1 → v1 的真实迁移时间线为例：

3.3 存储API版本漂移的典型场景

版本漂移不仅发生在集群升级时，也常出现在多团队协作的 YAML 交接中：

• 场景A： 基础设施团队使用 v1beta1 的 CSIDriver 配置，应用团队在 v1 集群中 apply 时报错 no matches for kind "CSIDriver" in version "storage.k8s.io/v1beta1"。
• 场景B： 容量表（Capacity Sheet）中记录的 StorageClass 使用 provisioner: kubernetes.io/aws-ebs，但新集群已废弃该内嵌 provisioner，需改用 ebs.csi.aws.com 并配合 VolumeAttachment v1。
• 场景C： 备份工具（如 Velero）在备份时使用了 v1beta1 的 VolumeSnapshot 资源，恢复到的目标集群已移除该版本，导致恢复失败。

3.4 存储API版本迁移校准流程

以下流程适用于任何 v1beta1 → v1 的存储资源迁移：

1. 扫描当前版本：使用 kubectl get --raw /openapi/v2 | jq '.paths | keys' 或 kubectl api-resources --api-group=storage.k8s.io 确认当前集群中存储 API 的可用版本。
2. 识别废弃资源：运行 kubectl get storageclass,volumeattachment,csidriver -A -o json | jq '.items[].apiVersion' | sort -u 找出仍在使用 v1beta1 的资源。
3. 转换清单：使用 kubectl convert 命令或手动修改 apiVersion 字段（例如 storage.k8s.io/v1beta1 → storage.k8s.io/v1）。
4. 验证兼容性：在测试集群中 apply 转换后的 YAML，确认字段无变化（v1beta1 → v1 通常字段兼容，但需检查 volumeBindingMode 等枚举值）。
5. 更新容量表：在团队共享的容量表中标注版本迁移日期和责任人。

# 示例：转换 VolumeAttachment 的 apiVersion
# 旧版本（v1beta1）
apiVersion: storage.k8s.io/v1beta1
kind: VolumeAttachment
metadata:
  name: test-attachment
spec:
  attacher: ebs.csi.aws.com
  nodeName: worker-1
  source:
    persistentVolumeName: pvc-xxx

# 新版本（v1）—— 字段完全兼容，仅 apiVersion 变化
apiVersion: storage.k8s.io/v1
kind: VolumeAttachment
metadata:
  name: test-attachment
spec:
  attacher: ebs.csi.aws.com
  nodeName: worker-1
  source:
    persistentVolumeName: pvc-xxx

3.5 存储API版本演进全景图

下图展示了存储 API 从 v1alpha1 到 v1 的完整生命周期，以及多团队协作中版本漂移的校准点：

3.6 容量表版本标注规范

在多团队协作的容量表中，建议增加以下版本相关列，避免漂移：