external-snapshotter升级迁移完全指南v1beta1到v1的转换之路与必须避开的5个坑【免费下载链接】external-snapshotterSidecar container that watches Kubernetes Snapshot CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.项目地址: https://gitcode.com/gh_mirrors/ex/external-snapshotterexternal-snapshotter是 Kubernetes CSI 快照体系的幕后功臣它作为 Sidecar 容器监听 VolumeSnapshot 等 CRD 对象并调用 CSI 驱动完成 CreateSnapshot / DeleteSnapshot 操作。如果你的集群还在使用v1beta1版本的 VolumeSnapshot API那么升级到v1已不是可选项而是必选项——本文带你走通这条转换之路并避开 5 个最常见的升级坑。一、先搞懂external-snapshotter 为什么必须升级external-snapshotter 由三个核心组件构成csi-snapshotterSidecar与 CSI 驱动同 Pod 部署负责将 CRD 请求转化为 CSI gRPC 调用源码见 pkg/sidecar-controller/csi_handler.gosnapshot-controller集群级控制器负责解析 VolumeSnapshotClass、创建 Content 对象源码见 pkg/common-controller/snapshot_controller.gowebhook提供验证与版本转换能力源码见 pkg/webhook/webhook.go版本演进的关键节点详见 CHANGELOG/ 目录版本里程碑影响v4.x仅提供 v1beta1 API旧集群普遍停留在这一版v5.0Kubernetes 1.24 快照特性 GA引入v1 API升级窗口开启v6.0彻底移除 v1beta1 API 服务不升级即失效v8.0验证逻辑改为 CRD 内置 CEL 规则最低要求 K8s 1.25⚠️ 关键点从 CHANGELOG/CHANGELOG-6.0.md 起snapshot.storage.k8s.io/v1beta1不再被 API Server 服务。继续引用 v1beta1 的清单将直接创建失败。二、v1beta1 与 v1 API 核心差异速查表升级前先看这张对照表它覆盖了 90% 的修改点对比项v1beta1旧v1新apiVersionsnapshot.storage.k8s.io/v1beta1snapshot.storage.k8s.io/v1VolumeSnapshot 来源顶层字段spec.persistentVolumeClaimName收敛为spec.source.persistentVolumeClaimNameVolumeSnapshotClassdeletePolicy含allowVolumeExpansiondeletionPolicy移除allowVolumeExpansion组快照 APIgroupsnapshot.storage.k8s.io/v1beta1v1beta2v1beta1 仍需转换 webhook 支持组快照状态字段status.volumeSnapshotHandlePairListstatus.volumeSnapshotInfoList以 v1 快照清单为例完整示例见 examples/kubernetes/snapshot-v1.yamlapiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: new-snapshot-demo-v1 spec: volumeSnapshotClassName: csi-hostpath-snapclass-v1 source: persistentVolumeClaimName: hpvc注意source字段的结构化封装这是 v1beta1 清单无法直接通过校验的重灾区。三、最快迁移步骤6 步完成 v1beta1 到 v1 升级步骤 1检查环境基线快照 v1 API 需要Kubernetes ≥ 1.24若升级到 external-snapshotter v8.xCEL 校验需要Kubernetes ≥ 1.25步骤 2更新 CRD用新版本 CRD 清单替换旧版。当前仓库内置的 CRD 位于 client/config/crd/ 目录包括snapshot.storage.k8s.io_volumesnapshots.yamlsnapshot.storage.k8s.io_volumesnapshotclasses.yamlsnapshot.storage.k8s.io_volumesnapshotcontents.yaml步骤 3批量替换业务清单全局搜索snapshot.storage.k8s.io/v1beta1统一改为v1并按上表调整source、deletionPolicy字段结构。步骤 4更新 RBAC从 v5.0 起控制器改用 Patch 替代 Update 以减少冲突需要新增 patch 权限见 CHANGELOG/CHANGELOG-5.0.md。Sidecar 与 Controller 的 RBAC 模板分别位于deploy/kubernetes/csi-snapshotter/rbac-csi-snapshotter.yamldeploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml步骤 5滚动升级组件依次部署新版本 csi-snapshotter 与 snapshot-controller部署清单在 deploy/kubernetes/ 下Sidecar 需要随各 CSI 驱动 Pod 一起重启生效。步骤 6验证# 应能正常列出 v1 快照 kubectl get volumesnapshots.snapshot.storage.k8s.io # 确认 readyToUse 为 true、restoreSize 有值 kubectl get volumesnapshot name -o yaml从快照恢复 PVC 的完整示例可参考 examples/kubernetes/restore.yaml。四、必须避开的 5 个升级坑 ️坑 1以为换个 apiVersion 就行v6.0 起 v1beta1 API 已被移除若清单里仍有残留的 v1beta1 对象引用kubectl apply会直接报错。建议升级前用kubectl get all -A -o yaml | grep v1beta1做一次全量扫描。坑 2忽略 source 字段的结构化改造v1beta1 中平铺在 spec 下的persistentVolumeClaimName/volumeSnapshotContentName在 v1 中必须放进spec.source结构体。只改 apiVersion 不改结构CRD 校验会拒绝创建。坑 3忘记补充 RBAC 的 patch 权限v5.0 引入 Patch 机制后若 RBAC 未同步更新Controller 与 Sidecar 会报forbidden: may not ... patch表现为快照长时间停留在 Creating 状态。这是最容易踩、也最难排查的坑。坑 4组快照场景漏部署 Conversion WebhookVolumeGroupSnapshotContent 同时存在 v1beta1 / v1beta2 两个版本跨版本查询依赖独立的snapshot-conversion-webhook入口见 cmd/snapshot-conversion-webhook/main.go。它会将 v1beta1 的volumeSnapshotHandlePairList转换为 v1beta2 的volumeSnapshotInfoList转换逻辑在 pkg/webhook/convert.go。部署要点部署 Deployment/Service参考 deploy/kubernetes/webhook-example/webhook.yaml用 deploy/kubernetes/webhook-example/create-cert.sh 生成 TLS 证书用 deploy/kubernetes/webhook-example/patch-ca-bundle.sh 将 CA 写入 CRD坑 5继续部署旧验证 Webhook或 K8s 版本低于 1.25v8.0 已把 VolumeSnapshot 系列对象的验证逻辑迁移到CRD 内置 CEL 规则测试用例见 client/hack/cel-tests/旧验证 webhook 已被标记弃用下个版本将移除。此时若继续部署旧 webhook属于冗余组件应及时清理若集群 K8s 1.25CEL 规则无法加载v8.x 的 CRD 将安装失败五、升级验证清单与回滚建议 ✅验证项预期结果kubectl get crd volumesnapshots.snapshot.storage.k8s.io只包含 v1 版本创建 v1 VolumeSnapshot数秒内 ReadyToUsetrueSidecar Pod 日志无forbidden、no matches for kind错误组快照跨版本查询如适用webhook 正常响应/convert请求从快照恢复 PVC新 PVC 容量与 restoreSize 一致回滚提醒由于 v6.0 起 v1beta1 不再被服务升级后无法回退到 v1beta1 版本。建议先在测试集群完整走一遍上述 6 步并备份现有清单与 CRD 后再动生产集群。升级 external-snapshotter 到 v1本质是一次一次改动、长期受益的低风险迁移API 更稳定、验证更内置、恢复流程更友好。对照本文的速查表与避坑清单大多数集群可以在一个维护窗口内平滑完成转换。【免费下载链接】external-snapshotterSidecar container that watches Kubernetes Snapshot CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.项目地址: https://gitcode.com/gh_mirrors/ex/external-snapshotter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
external-snapshotter升级迁移完全指南：v1beta1到v1的转换之路与必须避开的5个坑
external-snapshotter升级迁移完全指南v1beta1到v1的转换之路与必须避开的5个坑【免费下载链接】external-snapshotterSidecar container that watches Kubernetes Snapshot CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.项目地址: https://gitcode.com/gh_mirrors/ex/external-snapshotterexternal-snapshotter是 Kubernetes CSI 快照体系的幕后功臣它作为 Sidecar 容器监听 VolumeSnapshot 等 CRD 对象并调用 CSI 驱动完成 CreateSnapshot / DeleteSnapshot 操作。如果你的集群还在使用v1beta1版本的 VolumeSnapshot API那么升级到v1已不是可选项而是必选项——本文带你走通这条转换之路并避开 5 个最常见的升级坑。一、先搞懂external-snapshotter 为什么必须升级external-snapshotter 由三个核心组件构成csi-snapshotterSidecar与 CSI 驱动同 Pod 部署负责将 CRD 请求转化为 CSI gRPC 调用源码见 pkg/sidecar-controller/csi_handler.gosnapshot-controller集群级控制器负责解析 VolumeSnapshotClass、创建 Content 对象源码见 pkg/common-controller/snapshot_controller.gowebhook提供验证与版本转换能力源码见 pkg/webhook/webhook.go版本演进的关键节点详见 CHANGELOG/ 目录版本里程碑影响v4.x仅提供 v1beta1 API旧集群普遍停留在这一版v5.0Kubernetes 1.24 快照特性 GA引入v1 API升级窗口开启v6.0彻底移除 v1beta1 API 服务不升级即失效v8.0验证逻辑改为 CRD 内置 CEL 规则最低要求 K8s 1.25⚠️ 关键点从 CHANGELOG/CHANGELOG-6.0.md 起snapshot.storage.k8s.io/v1beta1不再被 API Server 服务。继续引用 v1beta1 的清单将直接创建失败。二、v1beta1 与 v1 API 核心差异速查表升级前先看这张对照表它覆盖了 90% 的修改点对比项v1beta1旧v1新apiVersionsnapshot.storage.k8s.io/v1beta1snapshot.storage.k8s.io/v1VolumeSnapshot 来源顶层字段spec.persistentVolumeClaimName收敛为spec.source.persistentVolumeClaimNameVolumeSnapshotClassdeletePolicy含allowVolumeExpansiondeletionPolicy移除allowVolumeExpansion组快照 APIgroupsnapshot.storage.k8s.io/v1beta1v1beta2v1beta1 仍需转换 webhook 支持组快照状态字段status.volumeSnapshotHandlePairListstatus.volumeSnapshotInfoList以 v1 快照清单为例完整示例见 examples/kubernetes/snapshot-v1.yamlapiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshot metadata: name: new-snapshot-demo-v1 spec: volumeSnapshotClassName: csi-hostpath-snapclass-v1 source: persistentVolumeClaimName: hpvc注意source字段的结构化封装这是 v1beta1 清单无法直接通过校验的重灾区。三、最快迁移步骤6 步完成 v1beta1 到 v1 升级步骤 1检查环境基线快照 v1 API 需要Kubernetes ≥ 1.24若升级到 external-snapshotter v8.xCEL 校验需要Kubernetes ≥ 1.25步骤 2更新 CRD用新版本 CRD 清单替换旧版。当前仓库内置的 CRD 位于 client/config/crd/ 目录包括snapshot.storage.k8s.io_volumesnapshots.yamlsnapshot.storage.k8s.io_volumesnapshotclasses.yamlsnapshot.storage.k8s.io_volumesnapshotcontents.yaml步骤 3批量替换业务清单全局搜索snapshot.storage.k8s.io/v1beta1统一改为v1并按上表调整source、deletionPolicy字段结构。步骤 4更新 RBAC从 v5.0 起控制器改用 Patch 替代 Update 以减少冲突需要新增 patch 权限见 CHANGELOG/CHANGELOG-5.0.md。Sidecar 与 Controller 的 RBAC 模板分别位于deploy/kubernetes/csi-snapshotter/rbac-csi-snapshotter.yamldeploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml步骤 5滚动升级组件依次部署新版本 csi-snapshotter 与 snapshot-controller部署清单在 deploy/kubernetes/ 下Sidecar 需要随各 CSI 驱动 Pod 一起重启生效。步骤 6验证# 应能正常列出 v1 快照 kubectl get volumesnapshots.snapshot.storage.k8s.io # 确认 readyToUse 为 true、restoreSize 有值 kubectl get volumesnapshot name -o yaml从快照恢复 PVC 的完整示例可参考 examples/kubernetes/restore.yaml。四、必须避开的 5 个升级坑 ️坑 1以为换个 apiVersion 就行v6.0 起 v1beta1 API 已被移除若清单里仍有残留的 v1beta1 对象引用kubectl apply会直接报错。建议升级前用kubectl get all -A -o yaml | grep v1beta1做一次全量扫描。坑 2忽略 source 字段的结构化改造v1beta1 中平铺在 spec 下的persistentVolumeClaimName/volumeSnapshotContentName在 v1 中必须放进spec.source结构体。只改 apiVersion 不改结构CRD 校验会拒绝创建。坑 3忘记补充 RBAC 的 patch 权限v5.0 引入 Patch 机制后若 RBAC 未同步更新Controller 与 Sidecar 会报forbidden: may not ... patch表现为快照长时间停留在 Creating 状态。这是最容易踩、也最难排查的坑。坑 4组快照场景漏部署 Conversion WebhookVolumeGroupSnapshotContent 同时存在 v1beta1 / v1beta2 两个版本跨版本查询依赖独立的snapshot-conversion-webhook入口见 cmd/snapshot-conversion-webhook/main.go。它会将 v1beta1 的volumeSnapshotHandlePairList转换为 v1beta2 的volumeSnapshotInfoList转换逻辑在 pkg/webhook/convert.go。部署要点部署 Deployment/Service参考 deploy/kubernetes/webhook-example/webhook.yaml用 deploy/kubernetes/webhook-example/create-cert.sh 生成 TLS 证书用 deploy/kubernetes/webhook-example/patch-ca-bundle.sh 将 CA 写入 CRD坑 5继续部署旧验证 Webhook或 K8s 版本低于 1.25v8.0 已把 VolumeSnapshot 系列对象的验证逻辑迁移到CRD 内置 CEL 规则测试用例见 client/hack/cel-tests/旧验证 webhook 已被标记弃用下个版本将移除。此时若继续部署旧 webhook属于冗余组件应及时清理若集群 K8s 1.25CEL 规则无法加载v8.x 的 CRD 将安装失败五、升级验证清单与回滚建议 ✅验证项预期结果kubectl get crd volumesnapshots.snapshot.storage.k8s.io只包含 v1 版本创建 v1 VolumeSnapshot数秒内 ReadyToUsetrueSidecar Pod 日志无forbidden、no matches for kind错误组快照跨版本查询如适用webhook 正常响应/convert请求从快照恢复 PVC新 PVC 容量与 restoreSize 一致回滚提醒由于 v6.0 起 v1beta1 不再被服务升级后无法回退到 v1beta1 版本。建议先在测试集群完整走一遍上述 6 步并备份现有清单与 CRD 后再动生产集群。升级 external-snapshotter 到 v1本质是一次一次改动、长期受益的低风险迁移API 更稳定、验证更内置、恢复流程更友好。对照本文的速查表与避坑清单大多数集群可以在一个维护窗口内平滑完成转换。【免费下载链接】external-snapshotterSidecar container that watches Kubernetes Snapshot CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.项目地址: https://gitcode.com/gh_mirrors/ex/external-snapshotter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
