Velero 备份仓库缓存卷(Backup Repository Cache Volume)设计解析
Velero 备份仓库缓存卷(Backup Repository Cache Volume)设计解析
导读
本篇文章围绕 Velero 在统一仓库(Unified Repository)架构下引入的**备份仓库缓存卷(Backup Repository Cache Volume)**机制展开,解决数据移动 Pod(Data Mover Pod)与仓库维护 Pod 将缓存数据写入节点根文件系统、可能打爆系统盘的问题。通过本文,你将掌握缓存卷适用的场景判定、缓存卷大小的计算公式、PVC/PV 的规格约束、node-agent ConfigMap 配置方法,以及从节点代理到 Exposer、再到 Kopia 仓库的完整调用链与源码实现位置,可直接指导你在真实集群中配置并使用该能力。
背景:为什么需要独立的缓存卷
Velero 基于统一仓库设计引入了可选择的备份仓库(Backup Repository),用于承载 fs-backup、卷快照数据移动(Volume Snapshot Data Movement)等多种备份/恢复路径。部分备份仓库在执行仓库操作时需要在客户端侧缓存数据以加速执行,例如 Kopia 仓库在连接远端对象存储时,需要把内容索引、数据块等缓存到本地。
在备份仓库配置中,Velero 已经允许用户通过 cacheLimitMB 配置缓存数据的上限,但缓存数据依然落在:
- 数据移动 Pod(Data Mover Pod)的根文件系统
- 仓库维护 Pod(Repository Maintenance Pod)的根文件系统
即最终落在节点的根文件系统上,这会带来两个突出问题:
- 系统盘容量受限:很多发行版中节点系统盘大小是预定义、不可配置且有上限的(例如 20G 甚至更小),缓存数据容易把系统盘占满。
- 并发数据移动放大风险:Velero 支持在每个节点上并发执行多个数据移动,每个并发数据移动 Pod 都会占用一部分系统盘缓存,很快便会耗尽系统盘,进而引发 Pod 驱逐(pod eviction)、Pod 创建失败、Kubernetes QoS 降级等问题。
因此,需要允许用户准备一个专用的缓存位置(如独立卷),而不是把缓存写死在根文件系统上。
术语速览
| 术语 | 含义 |
|---|---|
| Backup Storage | 存放备份数据的存储,详见统一仓库设计 |
| Backup Repository | 位于数据移动器(Data Mover)与 Backup Storage 之间的备份仓库层,提供备份/恢复相关能力 |
| Velero Generic Data Path (VGDP) | 统一仓库设计引入的模块集合(uploader 与备份仓库),Velero 用其完成 PodVolume 备份/恢复、卷快照数据移动等数据传输 |
| Data Mover Pods | 持有 VGDP 并完成数据传输的中间 Pod,见 VGDP 微服务(卷快照数据移动) 与 VGDP 微服务(fs-backup) |
| Repository Maintenance Pods | 运行仓库维护任务的 Pod,持有 VGDP 执行仓库维护 |
设计目标与非目标
目标(Goals):
- 提供一种机制,让用户能为运行 VGDP 的各种 Pod 配置缓存卷;
- 设计将缓存卷的 Pod 路径指派给备份仓库的工作流;
- 明确缓存卷在什么场景、以什么方式被使用。
非目标(Non-Goals):
- 本方案建立在统一仓库设计、VGDP 微服务(卷快照数据移动)与 VGDP 微服务(fs-backup) 之上,不支持遗留数据路径。例如当 PodVolumeRestore(PVR)运行在遗留 Restic 路径时,即使有缓存数据,缓存依然位于根文件系统。
缓存数据分析:有效负载 vs 仓库元数据
不同备份仓库的缓存数据内容各异,总体上可分为两类:
- Payload 数据(有效负载):与备份数据高度相关,通常占仓库数据的大头,也是缓存数据的主体。
- 仓库元数据(Repository Metadata):与备份仓库的块切分算法、数据块映射方法等相关,其大小与备份数据规模不成正比。
对于某些仓库,极端情况下元数据可能异常庞大。例如 Kopia 的索引是按块(per chunk)建立的,如果仓库中存在海量小文件,Kopia 的索引数据可能与 payload 数据相当甚至更大。但设计文档同时指出:在元数据成为多数的场景下,通常会出现其他瓶颈,数据移动的并发度会被显著约束,因此对缓存卷的需求反而会降低。
基于以上分析,当前方案只为 payload 数据考虑缓存卷需求,把元数据缓存卷留作未来增强。
场景分析:何时需要缓存卷
在 VGDP 运行期间,备份仓库缓存情况因仓库与操作类型而异。设计文档对四类场景做了逐一定性:
| 场景 | 说明 | 是否需要专用缓存卷 |
|---|---|---|
| 数据上传(备份) | 例如 DataUpload、PodVolumeBackup,数据几乎是直接写入仓库,只会有小规模数据短暂驻留本地 | 否 |
| 仓库维护 | 大多数情况下只访问仓库元数据,且单节点上不宜并发运行多个维护任务,缓存数据不大 | 否 |
| 数据下载(恢复) | 例如 DataDownload、PodVolumeRestore,对于把数据存在远端备份存储(如 Kopia 仓库存于远端对象存储)的仓库,会大规模缓存本地数据以加速恢复 | 是 |
| 备份删除 | 仅连接仓库、枚举元数据以定位表示备份数据的仓库快照,最多只缓存元数据 | 否 |
上述分析基于备份仓库的常见行为,未考虑元数据占据缓存数据主要比例的情形。结论:当前只为恢复场景创建专用缓存卷;其他场景按未来需求扩展。设计上,缓存卷的暴露与挂载机制对所有场景通用——例如未来若需覆盖元数据缓存,可直接复用同一套缓存卷供给与挂接机制,扩展到备份与仓库维护场景。
缓存数据生命周期:随 Pod 而生,随 PVC 而灭
缓存卷的生命周期遵循简单而严格的规则:
- 若配置可用,一个缓存卷被专门指派给一个数据移动 Pod;
- 数据移动 Pod 完成时,缓存数据随之销毁,对应的备份仓库实例也随之关闭;
- 缓存数据完全由备份仓库管理,仓库可以在数据移动 Pod 运行期间自行执行缓存 GC;
- 剩余数据在数据移动 Pod 与缓存 PVC 被销毁时自动清除——因为缓存 PVC 的
reclaimPolicy始终为Delete,PVC 销毁后底层卷一并销毁。
因此无需为缓存数据设计额外的 GC 逻辑,生命周期完全由 Pod/PVC 的销毁闭环托管。
数据规模与缓存卷大小计算
数据规模:小备份不值得建卷
缓存卷会占用存储空间与集群资源(PVC、PV),因此只在必要时创建,且卷大小应与缓存数据规模匹配:
- 小备份不值得为其创建缓存卷,应使用驻留缓存位置(根文件系统中的缓存目录);
- 缓存数据有上限,由既有配置
cacheLimitMB控制。例如 1TB 的备份可设cacheLimitMB=1024,意味着最多缓存 1GB 数据,超出部分会被清理。因此把缓存卷设得远大于cacheLimitMB没有意义。
缓存卷大小公式
对恢复(Restore)场景,缓存卷大小由以下因素决定:
- Limit:缓存数据上限,即
cacheLimitMB的取值,默认 5GB; - backupSize:备份大小,作为是否创建缓存卷的参考量(不代表备份数据一定决定缓存大小,仅用于评估备份规模;小规模备份需要小缓存)。若 backupSize 与缓存数据规模无关,则不应设置 ResidentThreshold,直接使用 Limit;backupSize 基本不会缺失,一旦缺失则忽略 ResidentThreshold,直接用 Limit;
- ResidentThreshold:创建缓存卷所需的最小备份大小;
- InflationPercentage:考虑文件系统开销与缓存清理可能的延迟,最终卷大小相对逻辑大小需要有一个膨胀系数,该百分比在代码中硬编码为 20%。
计算公式如下:
cacheVolumeSize = ((backupSize != 0 ? (backupSize > residentThreshold ? limit : 0) : limit) * (100 + inflationPercentage)) / 100
最终 cacheVolumeSize 会向上取整到 GiB,以兼顾用户体验、存储与管理友好性。
源码中的公式实现
在 pkg/exposer/cache_volume.go 中,getCacheVolumeSize 精确实现了上述逻辑:
func getCacheVolumeSize(dataSize int64, info *CacheConfigs) int64 {
if info == nil {
return 0
}
if dataSize != 0 && dataSize < info.ResidentThreshold {
return 0
}
// 20% inflate and round up to GB
volumeSize := (info.Limit*12/10 + (1<<30) - 1) / (1<<30) * (1<<30)
return volumeSize
}
对照设计公式可以验证实现细节:
dataSize != 0 && dataSize < info.ResidentThreshold时直接返回 0,即不创建缓存卷(小备份走根文件系统驻留缓存);- 膨胀 20% 通过
info.Limit * 12 / 10实现; (x + (1<<30) - 1) / (1<<30) * (1<<30)实现向上取整到 GiB。
默认 5GB 的限制也已在 Kopia 后端代码中印证:DefaultCacheLimitMB = 5000(见 pkg/repository/udmrepo/kopialib/backend/common.go)。
PVC/PV 规格约束与前置校验
缓存卷的 PVC 有以下硬性约束:
- 创建于 Velero 命名空间;
- 必须指定 storage class 用于供给缓存 PVC;
accessMode为ReadWriteOnce;volumeMode为FileSystem。
因此所选存储类必须同时支持这两项规格。否则数据移动 Pod 可能一直处于 Pending 状态,直到数据移动超时(如 prepareTimeout)后才最终失败。
由于缓存卷不应在数据移动 Pod 删除后保留,存储类的 reclaimPolicy 必须是 Delete。
前置校验:为了尽早发现问题,node-agent 会对存储类做校验,一旦校验失败,缓存配置将被忽略,数据移动 Pod 以不带缓存卷的方式创建。在 pkg/cmd/cli/nodeagent/server.go 的 validateCachePVCConfig 中可以看到:
func (s *nodeAgentServer) validateCachePVCConfig(config velerotypes.CachePVC) error {
if config.StorageClass == "" {
return errors.New("storage class is absent")
}
sc, err := s.kubeClient.StorageV1().StorageClasses().Get(s.ctx, config.StorageClass, metav1.GetOptions{})
if err != nil {
return errors.Wrapf(err, "error getting storage class %s", config.StorageClass)
}
if sc.ReclaimPolicy != nil && *sc.ReclaimPolicy != corev1api.PersistentVolumeReclaimDelete {
return errors.Errorf("unexpected storage class reclaim policy %v", *sc.ReclaimPolicy)
}
return nil
}
校验逻辑包括两条:存储类必须存在;存储类的 reclaimPolicy 必须为 Delete。校验失败时,node-agent 会记录一条 "Ignore cache config" 的警告日志并继续以无缓存卷方式运行(见 pkg/cmd/cli/nodeagent/server.go),保证不影响恢复结果。
在 pkg/exposer/cache_volume.go 中,createCachePVC 负责实际创建 PVC,其实现与设计完全对应:
pvcObj := &corev1api.PersistentVolumeClaim{
ObjectMeta: metav1.ObjectMeta{
Namespace: ownerObject.Namespace,
Name: cachePVCName,
OwnerReferences: []metav1.OwnerReference{...}, // 以数据移动的 owner 对象为属主
},
Spec: corev1api.PersistentVolumeClaimSpec{
AccessModes: []corev1api.PersistentVolumeAccessMode{corev1api.ReadWriteOnce},
StorageClassName: &sc,
VolumeMode: &volumeMode, // corev1api.PersistentVolumeFilesystem
Resources: corev1api.VolumeResourceRequirements{
Requests: corev1api.ResourceList{
corev1api.ResourceStorage: *resource.NewQuantity(size, resource.BinarySI),
},
},
},
}
值得注意的细节:
- PVC 通过
OwnerReferences绑定到所属对象(数据下载/恢复任务),随着属主对象销毁自动级联清理; - PVC 命名为 owner 对象名 +
-cache后缀(cacheVolumeDirSuffix = "-cache",见 pkg/exposer/cache_volume.go); - 若指定了目标节点,PVC 会带上
kube.KubeAnnSelectedNode注解(volume.kubernetes.io/selected-node),确保调度到执行数据移动的节点。
缓存卷配置项与 ConfigMap 样例
设计中引入两个新配置项:
residentThresholdMB:触发创建缓存卷的最小待处理数据量(MB),即前文的 ResidentThreshold;cacheStorageClass:用于供给缓存 PVC 的存储类名称。
与 cacheLimitMB 不同——cacheLimitMB 作用于备份仓库本身——这两个配置项实际是数据移动器(data mover)侧的配置,决定如何为数据移动 Pod 创建缓存卷,且不需要按仓库区分。因此它们被添加到 node-agent 的 Configuration 中。
在源码中,对应的结构体位于 pkg/types/node_agent.go:
type CachePVC struct {
// StorageClass specifies the storage class for cache PVC
StorageClass string `json:"storageClass,omitempty"`
// ResidentThresholdInMB specifies the minimum size of the backup data to create cache PVC
ResidentThresholdInMB int64 `json:"residentThresholdInMB,omitempty"`
}
并作为 NodeAgentConfigs.CachePVCConfig 挂载在 node-agent 配置根节点下(pkg/types/node_agent.go,JSON 字段名为 cachePVC)。
三种配置样例
以下是 node-agent ConfigMap 的配置示例:
Sample-1(合法):
{
"cacheVolume": {
"storageClass": "sc-1",
"residentThresholdMB": 1024
}
}
恢复任务中备份数据大于 1G 时,将使用存储类 sc-1 分配缓存卷。
Sample-2(合法):
{
"cacheVolume": {
"storageClass": "sc-1"
}
}
数据移动 Pod 始终被分配使用存储类 sc-1 的缓存卷(未设置阈值,任何恢复都建卷)。
Sample-3(不合法):
{
"cacheVolume": {
"residentThresholdMB": 1024
}
}
缺少存储类,不是合法配置,Velero 将放弃创建缓存卷。
需要说明:设计文档示例中使用的键名为 cacheVolume,而当前仓库源码 pkg/types/node_agent.go 中该字段的 JSON 键为 cachePVC(结构体名 CachePVC),使用时请以当前仓库实际生成的 node-agent ConfigMap 结构为准(可先查看集群中已安装的 velero node-agent ConfigMap 确认键名)。
创建 ConfigMap 的命令
将上面的样例保存为 json 文件后,执行:
kubectl create cm <ConfigMap name> -n velero --from-file=<json file name>
由于缓存卷配置由 node-agent server 读取,还需在 velero node-agent 参数中指定:
--node-agent-configmap
详细设计:从 restore 到 Kopia 的调用链
1. 恢复任务携带备份大小:snapshotSize 字段
恢复流程需要知道备份大小以计算缓存卷大小,因此 DataDownload 与 PodVolumeRestore 两个 CRD 新增了 snapshotSize 字段:
spec:
snapshotID:
description: SnapshotID is the ID of the Velero backup snapshot to
be restored from.
type: string
snapshotSize:
description: SnapshotSize is the logical size of the snapshot.
format: int64
type: integer
snapshotSize 表示备份的总大小;恢复期间,该值从 DataUpload/PodVolumeBackup 的 Status.Progress.TotalBytes 传递到 DataDownload/PodVolumeRestore。若 Status.Progress.TotalBytes 缺失(概率极低),按前述公式,residentThresholdMB 被忽略,缓存卷大小直接按对应备份仓库的缓存上限计算。
2. Exposer:计算大小、创建 PVC、挂载并传递路径
缓存卷配置由 node-agent 取出,经 DataDownload/PodVolumeRestore 传递到 GenericRestore exposer / PodVolume exposer。Exposer 负责:
- 计算缓存卷大小;
- 创建缓存 PVC;
- 将 PVC 挂载到 restorePod;
- 若计算出的缓存卷大小为 0,或关键参数缺失(如存储类缺失),Exposer 忽略缓存卷配置,继续创建不带缓存卷的 restorePod,不影响恢复结果(这一点在 pkg/exposer/generic_restore.go 的代码中可以看到:仅在
getCacheVolumeSize返回大于 0 时才创建缓存 PVC,否则记录日志并跳过)。
Exposer 将缓存卷挂载到预定义目录,并通过 --cache-volume-path 参数把目录传给数据移动 Pod(见 pkg/exposer/generic_restore.go:挂载卷名为 cachedir,最终以 fmt.Sprintf("--cache-volume-path=%s", cacheVolumePath) 传入)。
设计文档给出的 Expose 参数新增数据结构如下:
type GenericRestoreExposeParam struct {
// RestoreSize specifies the data size for the volume to be restored
RestoreSize int64
// CacheVolume specifies the info for cache volumes
CacheVolume *CacheVolumeInfo
}
type PodVolumeExposeParam struct {
// RestoreSize specifies the data size for the volume to be restored
RestoreSize int64
// CacheVolume specifies the info for cache volumes
CacheVolume *repocache.CacheConfigs
}
type CacheConfigs struct {
// StorageClass specifies the storage class for cache volumes
StorageClass string
// Limit specifies the maximum size of the cache data
Limit int64
// ResidentThreshold specifies the minimum size of the cache data to create a cache volume
ResidentThreshold int64
}
源码中对应的 CacheConfigs 定义见 pkg/exposer/cache_volume.go,GenericRestoreExposeParam.CacheVolume 字段见 pkg/exposer/generic_restore.go。
控制器组装缓存配置:在 pkg/controller/data_download_controller.go 中,DataDownload 控制器把 node-agent 传入的缓存配置与仓库的客户端缓存上限合并为 exposer.CacheConfigs:
var cacheVolume *exposer.CacheConfigs
if r.cacheVolumeConfigs != nil {
if limit, err := r.repoConfigMgr.ClientSideCacheLimit(velerov1api.BackupRepositoryTypeKopia, r.backupRepoConfigs); err != nil {
log.WithError(err).Warnf("Failed to get client side cache limit ...")
} else {
cacheVolume = &exposer.CacheConfigs{
Limit: limit,
StorageClass: r.cacheVolumeConfigs.StorageClass,
ResidentThreshold: r.cacheVolumeConfigs.ResidentThresholdInMB << 20,
}
}
}
注意 ResidentThresholdInMB << 20 把配置的 MB 值转换为字节单位,Limit 则来自仓库配置管理器按仓库类型(如 Kopia)解析出的客户端缓存上限(即 cacheLimitMB 的语义)。随后 RestoreSize 由 dd.Spec.SnapshotSize 提供(pkg/controller/data_download_controller.go),与 CacheVolume 一起组成 GenericRestoreExposeParam 传给 Exposer。
3. 数据移动 Pod:目录为空则回落根文件系统
数据移动 Pod 从 cache-volume-path 参数取得缓存卷目录,并将其传给 Unified Repository。若目录为空,Unified Repository 使用驻留位置(即根文件系统)作为数据缓存——这保证了即使未配置缓存卷,恢复功能依然可用。
4. Kopia 仓库:定制 CacheDirectory
Kopia 仓库对元数据与数据都支持缓存目录配置。现有 SetupConnectOptions 被修改为按传入的存储选项定制 CacheDirectory:
func SetupConnectOptions(ctx context.Context, repoOptions udmrepo.RepoOptions) repo.ConnectOptions {
...
return repo.ConnectOptions{
CachingOptions: content.CachingOptions{
CacheDirectory: cacheDir,
...
},
...
}
}
当前源码实现位于 pkg/repository/udmrepo/kopialib/backend/common.go,除了缓存目录还揭示了更多工程细节:
cacheLimit := optionalHaveIntWithDefault(ctx, udmrepo.StoreOptionCacheLimit, repoOptions.StorageOptions, DefaultCacheLimitMB) << 20
cacheDir := optionalHaveString(udmrepo.StoreOptionCacheDir, repoOptions.StorageOptions)
// 80% for data cache and 20% for metadata cache and align to KB
dataCacheLimit := (cacheLimit / 5 * 4) >> 10
metadataCacheLimit := (cacheLimit / 5) >> 10
return repo.ConnectOptions{
CachingOptions: content.CachingOptions{
CacheDirectory: cacheDir,
// softLimit 80%
ContentCacheSizeBytes: (dataCacheLimit / 5 * 4) << 10,
MetadataCacheSizeBytes: (metadataCacheLimit / 5 * 4) << 10,
// hardLimit 100%
ContentCacheSizeLimitBytes: dataCacheLimit << 10,
MetadataCacheSizeLimitBytes: metadataCacheLimit << 10,
...
},
...
}
这里把 cacheLimitMB 按 80% 数据缓存 / 20% 元数据缓存拆分,并分别设置软上限(80%)与硬上限(100%),与设计文档中“缓存数据有上限、超出即清理”的描述相互印证。
小结
Backup Repository Cache Volume 机制为 Velero 的 VGDP 数据路径补齐了一块关键拼图:在不改变备份仓库语义的前提下,把恢复场景的大规模本地缓存从节点根文件系统迁移到用户指定的存储类供给的专用卷上。核心要点可归纳为:
- 场景收敛:当前只为恢复(DataDownload/PodVolumeRestore)创建专用缓存卷,备份、维护、删除场景暂不建卷,机制本身对未来扩展通用;
- 大小可控:
cacheLimitMB默认 5GB 作为缓存上限,residentThresholdMB过滤小备份,20% 膨胀后向上取整到 GiB,避免资源浪费与卷被写满; - 生命周期自洽:PVC 以 owner 对象为属主、
reclaimPolicy=Delete,缓存随 Pod/PVC 销毁自动清理,无需额外 GC; - 失败可降级:存储类缺失、校验失败或备份大小不可用等异常情况下,Exposer 会忽略缓存配置,恢复任务依旧以根文件系统缓存正常执行。
如果你正在大规模恢复场景中遇到节点磁盘被 Kopia 等远端仓库缓存打满的问题,可以通过配置 node-agent ConfigMap 中的 cachePVC(或 cacheVolume)配置并指定支持 ReadWriteOnce、FileSystem、reclaimPolicy=Delete 的存储类,为每个数据移动 Pod 挂载专属缓存卷,从而把缓存对节点磁盘的冲击彻底隔离。