Velero v1.4 版本详解：CSI Beta 快照、自定义 CA 证书与备份进度报告

Velero v1.4 版本详解：CSI Beta 快照、自定义 CA 证书与备份进度报告

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

本篇文章以 Velero 官方 changelogs/CHANGELOG-1.4.md 为主体，结合当前仓库源码，系统解读 Velero v1.4 系列版本（v1.4.0 / v1.4.1 / v1.4.2）的核心能力：beta 级 CSI 卷快照支持、对象存储自定义 CA 证书校验、备份进度上报、以及备份 tarball 格式升级到 1.1.0 后对多版本资源（EnableAPIGroupVersions）的支持。读完本文，你将掌握这些特性的启用方式（feature flag 与 CLI 参数）、底层实现原理（涉及哪些源码文件）、以及升级到 v1.4 时的注意事项与已知问题。

版本发布概览

Velero v1.4 主线版本为v1.4.0（2020-05-26），随后发布两个补丁版本：

重要提醒：v1.4.1 这个 tag 是在代码中创建的，但没有对应的 Docker 镜像，原因是在构建基础设施配置错误。v1.4.2 修复了这一问题并补上了镜像发布。因此在实际生产环境中部署或升级时，请直接使用velero/velero:v1.4.2及后续版本，不要使用 v1.4.1。

v1.4.0 四大 Highlights

v1.4.0 的官方亮点（Highlights）共有四项：

1. beta 级 CSI 支持：通过 CSI 快照 API 备份恢复 CSI 卷；
2. 自定义 CA 证书支持：在验证对象存储 TLS 连接时使用自定义 CA bundle；
3. 备份进度报告：备份执行期间实时上报已备份/预估总数；
4. 备份 tarball 格式变更：支持备份同一资源的全部 API 版本（格式升级到 1.1.0）。

下面逐一深入展开。

Beta 级 CSI 快照支持（EnableCSI）

特性定位与设计意图

在 v1.4 之前，Velero 的持久卷快照依赖各云厂商编写专属的VolumeSnapshotter插件，覆盖面有限。而 Kubernetes CSI 提供了通用的VolumeSnapshot/VolumeSnapshotContent/VolumeSnapshotClass快照 API，任何遵循 CSI 规范的驱动都可以实现，从而让 Velero 无需为每家存储厂商单独写插件即可支持其卷快照。仓库内的设计文档 design/Implemented/csi-snapshots.md 明确指出该特性的目标：

• Goal：让 Velero 通过 Kubernetes CSI CRD API 备份与恢复 CSI 卷；
• Non-Goal：不替代现有VolumeSnapshotter插件 API，也不替代 restic 支持。

启用方式

CSI 支持默认关闭，需要显式开启EnableCSIfeature flag。在 pkg/apis/velero/v1/constants.go 中定义：

// CSIFeatureFlag is the feature flag string that defines whether or not CSI features are being used. CSIFeatureFlag = "EnableCSI"

启用方式为在velero install时通过--features传入（v1.4 起 install CLI 支持透传 feature flags，见 [#2503]）：

velero install \ --provider <provider> \ --bucket <bucket> \ --features=EnableCSI

--features参数在 pkg/cmd/cli/install/install.go 中定义为：

Comma separated list of Velero feature flags to be set on the Velero deployment

功能开关的底层实现位于 pkg/features/feature_flags.go，它维护一个进程级 flag 集合，并提供IsEnabled(name)、Enable(names...)、Serialize()等接口，服务端与插件侧均通过它判断是否启用 CSI 路径。

实现原理（源码级）

CSI 快照路径主要由一组插件与状态跟踪字段构成，设计文档 design/Implemented/csi-snapshots.md 描述的核心插件包括：

• velero.io/csi-pvc（BackupItemAction，作用于 PVC）：检查关联 PV 是否设置了PersistentVolume.Spec.PersistentVolumeSource.CSI；若为 nil、或Backup.Spec.SnapshotVolumes为 false、或该卷已由 restic 备份（通过backup.velero.io/backup-volumes注解判断），则直接返回不动作。否则创建VolumeSnapshot对象，打上velero.io/backup-name标签并设置 ownerRef（这样删除 Backup 时会级联删除关联 VolumeSnapshot）。VolumeSnapshot、VolumeSnapshotContent、VolumeSnapshotClass会作为 additional items 一并备份。需要注意，插件不会等待VolumeSnapshot.Status.readyToUse=true，只要CreationTime被设置应用即可继续，从而保持应用 quiesce/resume 的短暂中断。
• velero.io/csi-vsc（RestoreItemAction，作用于 VolumeSnapshotContent）：恢复时清理 VSC 对象，使其能与目标集群新分配的 ID 重新关联；只处理带velero.io/backup-name标签的对象。
• velero.io/csi-vs（RestoreItemAction，作用于 VolumeSnapshot）：处理 VolumeSnapshot 的恢复关联。

在服务端，EnableCSI还影响快照机制的选路。在 pkg/backup/item_backupper.go 中，如果未启用EnableCSI，来自 CSI 插件的 action 会被跳过并打日志；同时该文件在takePVSnapshot中做了防重复快照处理（#4758引入，见该文件L615-L616：启用 CSI 特性且 PV 为 CSI 卷时不再走 Velero-native 快照，避免重复快照）。

在velero backup describe --details中，启用EnableCSI后（velero 客户端需同样传入该 flag，见 [#2448]），会展示与备份关联的 CSIVolumeSnapshotContent明细。备份的status上也新增了统计字段（定义见 pkg/apis/velero/v1/backup_types.go）：

// CSIVolumeSnapshotsAttempted is the total number of attempted // CSI VolumeSnapshots for this backup. CSIVolumeSnapshotsAttempted int `json:"csiVolumeSnapshotsAttempted,omitempty"` // CSIVolumeSnapshotsCompleted is the total number of successfully // completed CSI VolumeSnapshots for this backup. CSIVolumeSnapshotsCompleted int `json:"csiVolumeSnapshotsCompleted,omitempty"`

备份删除路径上，v1.4 也补齐了 CSI 对象的清理逻辑：删除备份时同步删除该备份创建的 CSIVolumeSnapshot（#2411）以及关联VolumeSnapshot对象已不存在的VolumeSnapshotContent（#2480）；backup sync controller 会同步备份的 CSI API 对象进集群（#2496）。

注意点

• CSI 是 beta 级能力，启用前请确认集群 CSI 快照 API 可用且已部署 CSI 驱动；
• 客户端执行velero backup describe查看 CSI 明细时，同样需要给 velero 客户端加EnableCSI；
• 插件服务端会忽略未知 flag（#2479），旧插件不识别--features时不会收到该参数，避免兼容性问题。

自定义 CA 证书支持（对象存储 TLS 校验）

v1.4 全面支持为对象存储的自签/私有 CA 场景配置自定义 CA bundle，涉及三个层面：

1. 在 BackupStorageLocation 上配置 CA

通过 BSL 上的 CA 证书字段，Velero 服务器在访问对象存储时使用自定义 CA 校验 TLS 连接（#2353）。可用velero backup-location create/set相关命令维护，仓库中对应的 CA 参数解析逻辑位于 pkg/cmd/util/cacert/bsl_cacert.go 及 pkg/cmd/cli/backuplocation/create.go、pkg/cmd/cli/backuplocation/set.go。

2. install 命令的 --cacert 参数

velero install \ --provider <provider> \ --bucket <bucket> \ --cacert <path-to-ca-bundle>

该参数用于在安装 Velero 时提供 CA bundle，供验证对象存储 TLS 连接使用（#2368）。定义见 pkg/cmd/cli/install/install.go：

File containing a certificate bundle to use when verifying TLS connections to the object store. Optional.

3. velero 客户端命令的 --cacert 与客户端配置文件

velero backup describe、velero backup download、velero backup logs、velero restore describe、velero restore logs等命令均新增了--cacert参数，用于传递验证对象存储 TLS 连接的证书路径（#2364）。相关实现可参见 pkg/cmd/cli/backup/describe.go、pkg/cmd/cli/backup/download.go、pkg/cmd/cli/backup/logs.go 等文件。

同时，客户端配置文件（~/.config/velero/config.json之类的 VeleroConfig）新增cacert键作为默认值：当命令行未显式传--cacert时使用该配置。相关实现见 pkg/client/config.go：

ConfigKeyCACert = "cacert"

以及CACertFile()方法（pkg/client/config.go），用于从客户端配置中取出 CA bundle 路径作为默认值。

组合使用场景

典型的私有对象存储（如自建 MinIO + 自签证书）场景：

# 1) 服务端：安装时注入 CA bundle velero install --provider aws --bucket velero \ --secret-file ./credentials-velero \ --cacert ./ca-bundle.pem # 2) 客户端：写入配置文件作为默认 CA # config.json: { "cacert": "/path/to/ca-bundle.pem" } # 3) 或临时指定 velero backup describe <backup-name> --cacert ./ca-bundle.pem

备份进度报告

v1.4 引入备份进度上报（#2440）：备份执行期间，Velero 会把“已备份条目数 / 预估总条目数”写入日志，并更新 Backup 自定义资源的status.progress字段。

字段定义

BackupProgress 定义了两个字段：

// BackupProgress stores information about the progress of a Backup's execution. type BackupProgress struct { // TotalItems is the total number of items to be backed up. This number may change // throughout the execution of the backup due to plugins that return additional related // items to back up, the velero.io/exclude-from-backup label, and various other // filters that happen as items are processed. TotalItems int `json:"totalItems,omitempty"` // ItemsBackedUp is the number of items that have actually been written to the // backup tarball so far. ItemsBackedUp int `json:"itemsBackedUp,omitempty"` }

注意注释中的关键语义：TotalItems 是预估总数，在执行过程中会动态变化——因为插件可能返回额外的相关条目、velero.io/exclude-from-backup标签过滤、以及其他处理期过滤都会改变总数。

实现位置

进度上报的运行时逻辑位于 pkg/backup/backup.go。核心机制：

• backedUpGroupResources与itemsMap记录待备份条目；
• 启动一个 goroutine 监听 worker pool 返回的ItemBlockReturn，每次处理完一个 ItemBlock 就调用BackedUpAndTotalLen()计算已备份数与总数，并通过updatechannel 上报；
• 更新时同步写backupRequest.Status.Progress（见 pkg/backup/backup.go），并打印日志：Backed up %d items out of an estimated total of %d (estimate will change throughout the backup)。

使用方式

备份执行期间直接查看 Backup CR 或日志即可：

kubectl -n velero get backup <backup-name> -o jsonpath='{.status.progress}' # 示例输出：{"totalItems":42,"itemsBackedUp":17}

也可以实时观察 velero 服务端日志中的progress字段。官方提醒该信息是 best-effort 的——如果备份过程中 Velero 更新失败，progress可能不准确或过期（见 backup_types.go 注释）。

备份 tarball 格式 1.1.0 与多版本资源支持（EnableAPIGroupVersions）

背景：为什么要改格式

在 v1.4 之前，Velero 备份 tarball 中每种资源默认只保存首选版本（preferred version）。当集群升级导致 CRD 首选版本变化时，旧备份中缺少的历史版本资源可能导致恢复内容不完整或与目标集群版本不匹配。v1.4 将 tarball 格式升级到1.1.0（#2373），改为保存某个资源的所有 API 版本。

格式版本常量

当前仓库 pkg/backup/backup.go 中的常量即为 v1.4 引入的格式版本：

// BackupFormatVersion is the current backup version for Velero, including major, minor, and patch. const BackupFormatVersion = "1.1.0"

该版本号会被写入备份包的metadata/version文件（pkg/backup/backup.go），恢复时据此判断格式兼容性。

启用方式

默认仍只备份首选版本；保存全部版本需要启用EnableAPIGroupVersionsfeature flag：

velero install ... --features=EnableAPIGroupVersions

flag 字符串常量定义于 pkg/apis/velero/v1/constants.go：

// APIGroupVersionsFeatureFlag is the feature flag string that defines whether or not to handle multiple API Group Versions APIGroupVersionsFeatureFlag = "EnableAPIGroupVersions"

源码中的多版本处理

开启该 flag 后，同一资源可能对应多个待备份版本，代码中专门做了处理：

• pkg/backup/backup.go：itemsMap的值设计为切片，注释明确说明“如果启用了 EnableAPIGroupVersions，同一个 item 可能有多个资源需要备份”；
• pkg/backup/backup.go：构建 ItemBlock 时，“如果启用了 EnableAPIGroupVersions，该 item 可能有多个版本，把所有这些版本放进同一个 ItemBlock”；
• pkg/itemblock/itemblock.go：FindItem注释说明“如果启用 EnableAPIGroupVersions 可能返回多个 item，匹配 preferredGVR 的 item 排在最前”。

tarball 中非首选版本资源的目录以-preferredversion后缀区分，常量见 pkg/apis/velero/v1/constants.go：

// PreferredVersionDir is the suffix name of the directory containing the preferred version of the API group // resource within a Velero backup. PreferredVersionDir = "-preferredversion"

同时，恢复代码也做了配套重构（#2248）：改为通过 discovery惰性解析资源，消除了为恢复 CRD 实例而进行的第二次恢复循环，保证多版本资源能按目标集群实际支持的能力恢复。

配套变更

• CRD 备份时，如果某个 CRD 是通过 v1beta1 endpoint 创建的，则从 v1beta1 endpoint 获取而非仅改 APIVersion（#2478）；
• 备份 CRD 之前先记录其版本，供remap_crd_versionbackup item action 使用（#2683，v1.4.2）；
• 为 Backup CRD 增加记录 k8s major/minor/git 版本的注解（#2346）。

v1.4.2 补丁内容详解

v1.4.2（2020-07-13）除修复 v1.4.1 的镜像构建问题外，还包含以下变更：

1. 插件返回额外条目找不到时的降级处理（#2595）

此前如果插件返回的 additional item 在 Kubernetes API 中找不到，备份会报错；v1.4.2 改为记录warning 而不是 error。这是因为插件声明的额外条目可能已经被并发删除或被过滤，直接报错会让整个备份失败，降级为告警更合理。

2. restic 默认超时与资源请求调整（#2696）

• PodVolumeBackup 默认超时从原来的较短值调整为4 小时，避免大卷备份因超时被误杀；
• restic 相关 Pod 的基础资源请求调整为500m CPU / 512Mi 内存，作为更贴合真实使用的基础值。

如需自定义，可在安装时通过相应参数覆盖（默认值以上述调整为基准）。

3. 记录 CRD 版本再执行 remap 动作（#2683）

在调用remap_crd_versionbackup item action 之前，先捕获 CRD 的版本（见上文“配套变更”），确保多版本场景下 remap 操作基于准确的版本信息执行。

v1.4.0 其余变更速览

除四大亮点外，v1.4.0 还包含一批值得关注的修复与增强：

bug fix 类

• CRD restore 插件不再使用runtime.DefaultUnstructuredConverter.FromUnstructured(...)，规避 float64 字段含整数值时的转换问题（#2484）；
• include/exclude 资源列表中出现无法解析的条目时，不再将其从列表中移除，避免列表意外退化成“匹配所有资源”（#2462）；
• 空卷也保存 PodVolumeBackup 清单到对象存储，使恢复时能按需动态重建 PV（#2390）；
• 为备份错误日志补上 namespace 字段（#2438）；
• error location 日志 hook 中，若error键下的对象未实现error接口，不再返回错误（#2487）；
• restic volume snapshot 计数在 PVB 成功创建后再递增（#2542）。

增强与重构

• 新增 PVC 的 restoreItemAction，用于恢复时更新selected-node注解（#2377）；
• Azure：支持直接从环境变量获取 restic 用的 storage account key（#2455）；
• --snapshot-volumes=false的备份可跳过 VSL（VolumeSnapshotLocation）校验（#2450）；
• 升级到 Go 1.14，并从dep迁移到 go modules（#2214）；
• Kubernetes 依赖模块升级到 v0.17.4，获取上游 bug fix（#2407）；
• 基础镜像从ubuntu:bionic升级到ubuntu:focal（#2471）；
• 重构：所有 informer cache 同步完成后再启动 controller（#2299）；
• 恢复 describe 中 namespace 的措辞澄清（#2214 相关）。

升级到 v1.4 的注意事项

综合 changelog 与源码，升级到 v1.4 需关注以下几点：

1. 容器镜像：请使用velero/velero:v1.4.2或更高版本，跳过没有镜像的 v1.4.1；
2. 备份格式版本：v1.4 起备份 tarball 格式为 1.1.0。若已启用EnableAPIGroupVersions，新备份将包含资源全部版本，旧版本 Velero 可能无法完整读取这类备份，升级前请确认恢复端版本；
3. feature flags 统一透传：velero install已支持--features，服务端与客户端在查看 CSI 明细时需保持一致的 flag 配置；
4. restic 参数变化：默认超时变为 4 小时、基础资源请求变为 500m CPU / 512Mi，生产环境建议结合实际卷规模评估是否需要覆盖默认值；
5. 构建链变化：Go 版本升级到 1.14 且改用 go modules，社区贡献者重新编译时需同步升级工具链。

延伸阅读

• 发布说明全文：changelogs/CHANGELOG-1.4.md
• CSI 快照支持设计文档：design/Implemented/csi-snapshots.md
• 功能开关实现：pkg/features/feature_flags.go
• 备份进度字段定义：pkg/apis/velero/v1/backup_types.go
• 备份格式版本与进度上报逻辑：pkg/backup/backup.go
• 客户端 CA 配置：pkg/client/config.go
• 安装命令参数定义：pkg/cmd/cli/install/install.go

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