Velero 1.9 版本详解：CSI 快照、Kubebuilder 重构、恢复策略升级与新增指标

Velero 1.9 版本详解：CSI 快照、Kubebuilder 重构、恢复策略升级与新增指标

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

导读：本文围绕 Velero 1.9.0 版本的核心变更展开，从 CSI 快照 v1 API 升级、控制器 Kubebuilder v3 重构，到 Restore 新增的existingResourcePolicy与可选择性 status 恢复能力，再到 Restic 安全升级与新增监控指标，系统梳理本次发版的关键能力，并结合当前仓库源码印证各特性的底层实现，帮助读者明确 v1.9 的能力边界、升级前提与实战用法。

一、版本概览：v1.9.0

v1.9.0 的发布围绕四条主线：CSI 快照正式走向 GA 前的能力补齐、控制器框架现代化（Kubebuilder v3 重构持续推进）、恢复流程的精细化控制（新增两个 Restore API 字段）、底层依赖的安全与稳定性加固。以下逐项展开。

二、CSI 快照改进：迈向 v1 API 与正式支持 AKS/EKS

2.1 三大核心改进

本版本对 CSI 插件做了三方面显著提升（详见 changelogs/CHANGELOG-1.9.md）：

1. 升级到 CSI volume snapshot v1 API：快照相关 CRD 全面使用snapshot.storage.k8s.io/v1（VolumeSnapshot、VolumeSnapshotContent、VolumeSnapshotClass），替代旧的 v1beta1 版本。
2. 不再在源命名空间遗留 VolumeSnapshot：备份完成后会清理备份期间创建的 VolumeSnapshot，避免源工作负载命名空间被无用的快照对象污染（对应 PR #4858 "Remove VolumeSnapshots created during backup when CSI feature is enabled"）。
3. 为 CSI 快照新增监控指标：参见下文"新增指标"章节。

2.2 破坏性变更与版本前提

⚠️Breaking change：由于快照 API 提升到 v1，CSI 插件 v0.3.0 仅支持 Kubernetes v1.20 及以上版本。若集群低于 v1.20，则不能使用该版本的 CSI 插件。

这意味着，当你在 v1.9 上启用--features=EnableCSI（或使用 CSI 快照时），需要提前确认目标集群 Kubernetes 版本满足 v1.20+ 的前提条件。

2.3 源码层面的印证

在仓库中，v1.9 对 CSI 快照的指标支持已沉淀到 pkg/metrics/metrics.go：

csiSnapshotAttemptTotal = "csi_snapshot_attempt_total" csiSnapshotSuccessTotal = "csi_snapshot_success_total" csiSnapshotFailureTotal = "csi_snapshot_failure_total"

对应 Prometheus 描述为 "Total number of CSI attempted volume snapshots" 等，并由RegisterCSISnapshotAttempts、RegisterCSISnapshotSuccesses、RegisterCSISnapshotFailures等方法上报。这些指标让用户可以在 Prometheus 中直接观测 CSI 快照的成功率与失败原因，是 v1.9 可观测性提升的直接证据。

与 CSI 相关的其他 PR 也验证了该特性的完整链路：

• #4797：启用 CSI 特性时，不再为 PV 额外拍摄原生快照，避免重复快照；
• #4887/#4832：backup sync 控制器删除孤儿 CSI 快照，并让同步创建的 VolumeSnapshotClass 可被删除；
• #4889：等待 VolumeSnapshot 就绪的过程改为并行处理，缩短大批量卷快照的整体耗时。

三、控制器框架现代化：Kubebuilder v3 重构持续推进

v1.9 延续了 Velero 的代码现代化工作，将一批控制器重写为 Kubebuilder v3 框架（原为手写 informer/watch 的 controller 模式）。本版本涉及：

• PodVolumeBackup 控制器（#4436）
• Pod Volume Restore 资源/控制器（#4655）
• Schedule 控制器（#4748）
• Restic Repository 资源/控制器（#4859）
• Backup Deletion 控制器（#4855）
• BSL 控制器（引入 periodical enqueue source，定期入队机制，#4894）

同时配套的工程化改进包括：

• 使用controller-gen生成对象 deep copy 方法（#4838）；
• 在 CRD 中禁用 status 作为 subresource（#4972）。

说明：这项工作在 v1.9 是"进行中"状态，官方明确表示会在后续版本持续推进。从当前仓库 pkg/controller 目录可见，大量控制器已同时具备 Kubebuilder 风格的路由/注册代码，但仍有部分控制器处于新旧并存的过渡状态，可据此推断 v1.9 之后仍有后续重构。

四、Restore API 增强：按需恢复 status 与 ExistingResourcePolicy

这是 v1.9 对用户最直观的功能增强，均体现在 Restore 的 spec 上，类型定义见 pkg/apis/velero/v1/restore_types.go。

4.1 可选择性恢复资源 status（#4785）

以往恢复会直接还原对象status字段，但 status 往往携带集群运行期信息（如服务 IP、副本数、Conditions），直接还原可能引入陈旧数据。v1.9 新增RestoreStatusSpec：

restoreStatus: includedResources: # 要恢复 status 的资源列表；为空表示应用到所有资源 - storageclasses.storage.k8s.io excludedResources: # 不恢复 status 的资源列表 - services

语义：

• RestoreStatus为nil时，默认不恢复任何对象的 status；
• IncludedResources为空时，作用于全部资源；
• ExcludedResources优先于IncludedResources。

CLI 对应参数为--status-include-resources与--status-exclude-resources（定义于 pkg/cmd/cli/restore/create.go），格式为resource.group，例如storageclasses.storage.k8s.io。

底层实现：在 pkg/restore/restore.go 中，determineRestoreStatus()函数会先根据 spec 的IncludesExcludes判断是否恢复某类资源的 status；同时它还支持对象级注解覆盖（ObjectStatusRestoreAnnotationKey，取值为true/false），即单个对象上的注解可以覆盖 spec 级设置——注解优先级高于 spec 级配置。对应测试TestDetermineRestoreStatus位于 pkg/restore/restore_test.go。

4.2 ExistingResourcePolicy：覆盖或补丁现有资源（#4628）

恢复目标集群中已存在同名资源时，v1.9 允许用户通过existingResourcePolicy显式声明处理策略：

CLI 参数为--existing-resource-policy，取值校验逻辑见 pkg/cmd/cli/restore/create.go：

flags.StringVar(&o.ExistingResourcePolicy, "existing-resource-policy", "", "Restore Policy to be used during the restore workflow for Kubernetes resources, can be - none or update")

校验失败时返回错误：existing-resource-policy has invalid value, it accepts only none, update as value。

底层实现：在 pkg/restore/restore.go 的恢复主流程中：

• 当资源已存在且发生变更时，若策略为none，记录 warning 并将该对象标记为ItemRestoreResultSkipped；
• 若策略为update，调用processUpdateResourcePolicy()先尝试对 in-cluster 对象与备份对象的差异执行 patch；patch 失败时，会移除旧恢复标签，仅补丁备份/恢复标签，保证资源归属信息仍然最新；
• 对 ServiceAccount 等有特殊合并逻辑的资源，在 update 策略下同样会走updateBackupRestoreLabels()的标签修补路径；
• 资源未发生变更时，update 策略下也会刷新对象上的 backup/restore 标签（#2025 起）。

类型定义中ResourcePolicyType两个取值在 pkg/apis/velero/v1/restore_types.go：

ResourcePolicyTypeNone ResourcePolicyType = "none" // 不覆盖，无论是否变更 ResourcePolicyTypeUpdate ResourcePolicyType = "update" // 尝试对变更的资源做 patch

CLI 侧测试 pkg/cmd/cli/restore/create_test.go 也验证了--existing-resource-policy的解析与传递链路。

五、Restic 升级与 skip TLS 校验支持（#4839）

v1.9 完成了两项与 Restic 相关的加固：

1. 升级集成的 Restic 版本：解决部分已公开的 CVE 漏洞；
2. 新增insecureSkipTLSVerify支持：在 Restic 备份/恢复命令中可跳过 TLS 校验，方便使用自签名证书的对象存储场景。

此外还修复了 restic prune 频率不可配置的问题（#4518），并在 restic 备份/恢复失败时补充了更详细的路径/快照错误信息（#4988）。安全层面，容器基础镜像也从 distroless 升级到base-debian11（#4898）。

六、新增指标与可观测性

v1.9 新增两个备份维度指标（#4296）：

• backup_items_total：本次备份处理的总条目数；
• backup_items_errors：备份过程中出错的条目数。

两个指标在 pkg/metrics/metrics.go 中定义为 Gauge 类型（backupItemsTotalGauge、backupItemsErrorsGauge）。配合上文提到的csi_snapshot_*系列指标，用户可以构建"备份成功率 + CSI 快照成功率"的完整监控面板。

另外，v1.9 对 BSL（BackupStorageLocation）状态模型做了改进（#4719）：BSL 在获取到任何错误时被标记为Unavailable，并在 status 中新增Message字段记录具体错误信息，便于运维定位对象存储故障。

七、其他值得关注的变更

以下变更从不同维度增强了 v1.9 的易用性与健壮性：

备份侧

• 备份时跳过未挂载卷（#4497）与非运行中 Pod 的卷（#4584），减少无效备份与失败面；
• 为 Backup 的 PodAction / Restore 的 PodAction 插件在 AdditionalItems 中增加 PriorityClass（#4740）；
• 启用 CSI 时不再对 PV 重复快照（#4797）；
• 支持 GKE 的 regional PV（#4680）；
• 修复--default-backup-ttl不生效问题（#4831）；
• 支持 Backup/Restore API 的多 label selector（#4650），CLI 侧对应--or-selector。

恢复侧

• 恢复排除 PV/PVC 时跳过创建 PodVolumeRestore（#4769）；
• 恢复 hook 依据命名空间映射应用到新命名空间（#4779）；
• 将所有恢复错误与警告写入恢复日志（#4743）；
• ClusterClasses 加入恢复优先级列表（#4866）。

控制器与生命周期

• 对 in-progress 状态的备份/恢复做 reconcile 时标记为失败，避免长期悬挂（#4833）；Restic 控制器重启时同样将 in-progress 的 PVB/PVR 标记失败（#4893）；
• GC 控制器为因BSLNotFound、BSLCannotGet、BSLReadOnly等原因删除失败的备份打上标签（#4757）；
• 过期备份的垃圾回收改为可配置（#4897）；
• 修复 Schedule 中 OrderedResources 的问题（#4550）；
• 清理 restic 完成后的.velero临时目录（#4872）。

CLI 与工程化

• velero install新增--pod-labels参数（#4694）；
• map 类型 flag 增强，支持解析含条目分隔符的输入（#4920）；
• zsh completion 输出可直接被source使用（#4914）；
• 发布流水线同时推送镜像到 GCR，缓解部分环境（如 vSphere）对 Docker Hub 的限流（#4623）。

八、升级建议与兼容性注意事项

综合 v1.9 的变更，升级前请重点核对：

1. Kubernetes 版本：若使用 CSI 插件 v0.3.0，集群必须为v1.20+（API 升级带来的硬性前提）；
2. CRD 更新：snapshot.storage.k8s.io/v1系列 CRD、以及 status 不再作为 subresource 的 Velero CRD 需要随升级一并应用（可参考 config/crd/v1 下的 CRD 定义）；
3. Restic 镜像/基础镜像变更：base-debian11基础镜像与新的 Restic 版本会随 v1.9 镜像一起发布，无需额外操作，但涉及安全扫描策略的团队应注意到基础镜像已更换；
4. 新字段为可选：restoreStatus、existingResourcePolicy均为可选字段，不设置时行为与 v1.8 保持一致，可平滑过渡。

九、小结

Velero v1.9.0 是一个"承上启下"的版本：它在 CSI 快照能力上补齐了 v1 API、清理与可观测性三块拼图，使 AKS/EKS 上基于 CSI 插件的快照备份获得官方支持；在恢复侧引入了restoreStatus与existingResourcePolicy两个精细控制字段，让恢复行为可配置、可预期；同时持续推进控制器框架的 Kubebuilder v3 现代化，并为后续版本的进一步演进（如后续对 status 恢复、资源策略的扩展）打下基础。对使用者而言，v1.9 最值得立即采用的能力是恢复时选择性保留 status与update 策略下的资源覆盖，两者都能显著降低迁移/灾备场景下的手工干预成本。

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero