Velero(Ark)Config 自定义资源详解:backupStorageProvider 与 persistentVolumeProvider 配置指南

原创2026-09-16 10:09:271,877 阅读
文章标签:云原生灾备

Velero(Ark)Config 自定义资源详解:backupStorageProvider 与 persistentVolumeProvider 配置指南

本篇技术指南以早期 Ark(Velero 前身)版本的 Config 自定义资源为核心,系统讲解其设计定位、完整 YAML 示例、全部主配置参数,以及 AWS / GCP / Azure 三大云厂商的专有配置项,并结合当前 Velero 仓库源码说明该配置体系向 BackupStorageLocation / VolumeSnapshotLocation 演进的历史脉络。读完本文,你将掌握 Ark 时代如何用一份名为 default 的 Config 声明备份存储与 PV 快照提供方,并理解其在现代 Velero 中对应的替代方案。

背景:为什么需要 Config 自定义资源

Heptio Ark(后更名为 Velero)在早期版本中定义了自己的 Config 对象——一个 Kubernetes 自定义资源(Custom Resource),用于集中指定 Ark 的备份与云提供方(Cloud Provider)设置。其设计要点如下:

  • 资源定位:Ark server 首次部署后,会一直等待用户在其所在命名空间中创建名为 default 的 Config 资源,否则服务不会真正开始工作;
  • 命名空间约定:Config 必须创建在 heptio-ark 命名空间中(见 config-definition.md);
  • 热更新行为:这里有一个隐含前提——Ark server 是以 Kubernetes Deployment 形式运行的。若 default Config 被修改,server 会优雅地关闭;待 kubelet 重启 Ark server Pod 后,server 才会使用更新后的配置值。也就是说,修改 Config 不是"即时生效",而是通过 Pod 重启完成配置刷新。

一份完整的 Config 示例

以下是官方文档给出的标准 YAML 示例(完整复刻,可直接作为编写模板):

apiVersion: ark.heptio.com/v1
kind: Config
metadata:
  namespace: heptio-ark
  name: default
persistentVolumeProvider:
  name: aws
  config:
    region: us-west-2
backupStorageProvider:
  name: aws
  bucket: ark
  config:
    region: us-west-2
backupSyncPeriod: 60m
gcSyncPeriod: 60m
scheduleSyncPeriod: 1m
restoreOnlyMode: false

从结构上可以清晰看到 Config 的两大核心职责:

  1. persistentVolumeProvider:声明集群持久卷(PV)快照所使用的云提供方(仅当需要做 PV 快照时配置);
  2. backupStorageProvider:声明备份数据实际存放的云对象存储位置(必填)。

外加三个周期类参数(backupSyncPeriod、gcSyncPeriod、scheduleSyncPeriod)和两个行为开关(restoreOnlyMode、resourcePriorities),共同构成 Ark 服务端的运行配置全集。

主配置参数参考

下表完整列出 Config 的所有主配置参数,含类型、默认值与语义说明(信息以 config-definition.md 为准):

Key Type Default Meaning
persistentVolumeProvider CloudProviderConfig None(可选) 集群用于持久卷快照的云提供方规格。若未指定,则请求 PV 快照/恢复的 Backup 与 Restore 被视为无效。注意:使用 Azure 时,Kubernetes 集群需为 1.7.2+ 版本才能支持托管磁盘(managed disks)的 PV 快照。
persistentVolumeProvider/name String(Ark 原生支持 aws、gcp、azure,其他提供方可经外部插件扩展) None(可选) 集群持久卷所用云提供方的名称。
persistentVolumeProvider/config map[string]string(详见 AWS/GCP/Azure 专有配置或对应提供方文档) None(可选) 传递给云提供方处理持久卷的配置键值对。
backupStorageProvider CloudProviderConfig 必填字段 实际用于存储备份数据的云提供方规格。
backupStorageProvider/name String(Ark 原生支持 aws、gcp、azure,其他提供方可经外部插件扩展) 必填字段 实际存储备份数据的云提供方名称。
backupStorageProvider/bucket String 必填字段 备份数据要上传到的存储桶(bucket)。
backupStorageProvider/config map[string]string(详见 AWS/GCP/Azure 专有配置或对应提供方文档) None(可选) 传递给云提供方处理备份存储的配置键值对。
backupSyncPeriod metav1.Duration 60m0s Ark 查询对象存储以确保为已有备份文件创建了对应 Backup 资源的频率。
gcSyncPeriod metav1.Duration 60m0s Ark 查询对象存储以删除已超过 TTL 的备份文件的频率。
scheduleSyncPeriod metav1.Duration 1m0s Ark 检查 Schedule 资源对象以判断是否需要发起新备份的频率。
resourcePriorities []string [namespaces, persistentvolumes, persistentvolumeclaims, secrets, configmaps] 描述 Kubernetes 资源对象恢复顺序的有序列表(支持 <RESOURCE>.<GROUP> 格式)。不在列表中的资源会在所有优先资源之后恢复。
restoreOnlyMode bool false 开启 RestoreOnly 模式后,备份、调度与过期备份删除功能将被关闭,仅从对象存储中已有备份文件执行恢复。

关键参数深度解析

backupSyncPeriod 与 gcSyncPeriod 的差异:两者都面向对象存储,但职责相反——前者是把对象存储中已存在的备份文件"同步"为集群内的 Backup 资源(常用于多集群共享存储桶或手工导入场景);后者则是按 TTL 清理过期备份数据。两者默认均为 60m,实际调优时可依据对象存储 API 调用成本与一致性需求权衡。

scheduleSyncPeriod 的节奏:默认 1m,是三个周期中最短的一个,因为它决定 Cron 式定时备份的触发精度。

resourcePriorities 的顺序逻辑:默认顺序把 namespaces 放在首位(依赖关系先建立),随后依次为 persistentvolumes、persistentvolumeclaims、secrets、configmaps——secrets 与 configmaps 优先于 Pod/控制器恢复,以保证应用启动时挂载的配置与凭据已就绪。这一"依赖优先"思想在现代 Velero 中依然延续:当前 pkg/cmd/server/config/config.go 中仍保留 restore-resource-priorities 标志,其注释明确说明优先级列表可用 - 元素划分为高优先级段与低优先级段,未列入的资源将按字母序排在高低两段之间。

restoreOnlyMode 的安全语义:此开关在需要"灾备站点只读挂载"(即目标集群只从对象存储拉取数据恢复、绝不产生新的备份写入)时非常关键。当前仓库 config.go 中对应标志被标记为 DEPRECATED,官方建议改用只读(ReadOnly)的 BackupStorageLocation 替代,但 v0.6.0 时代它是最直接的防误写手段。

云厂商专有配置

AWS(以及其他 S3 兼容存储)

backupStorageProvider/config

Key Type Default Meaning
region string 必填字段 示例:"us-east-1"。完整区域列表见 AWS 官方文档。
s3ForcePathStyle bool false 使用 Minio 等本地存储服务时需设为 true。
s3Url string 非 AWS 托管存储的必填字段 示例:http://minio:9000。可显式指定 AWS S3 URL(Ark 也可由 region 与 bucket 自动推导),该字段主要用于 Minio 等本地存储服务。
kmsKeyId string 空 示例:"502b409c-4da1-419f-a16e-eif453b3i49f" 或 "alias/<KMS-Key-Alias-Name>"。指定 AWS KMS key ID 或别名可为存入 S3 的备份开启加密,仅适用于 AWS S3,且可能需要显式授予密钥使用权限。

persistentVolumeProvider/config(仅 AWS)

Key Type Default Meaning
region string 必填字段 示例:"us-east-1"。完整区域列表见 AWS 官方文档。

Minio 本地存储实践:s3ForcePathStyle: true 与 s3Url 的组合是 Ark/Velero 本地开发与测试的核心手段。当前仓库在 examples/minio/00-minio-deployment.yaml 中提供了完整的 Minio 部署清单,可配合 s3Url: http://minio:9000 在本机搭建一套完整的备份演练环境。path style(路径风格)访问是 S3 兼容存储对接本地服务的通用前提,因为这类服务通常不提供虚拟主机风格的桶寻址。

GCP

backupStorageProvider/config

无需任何参数。

persistentVolumeProvider/config

Key Type Default Meaning
project string 必填字段 示例:"project-example-3jsn23"。即 GCP 项目 ID(Project ID),而非项目名称。

Azure

backupStorageProvider/config

无需任何参数。

persistentVolumeProvider/config

Key Type Default Meaning
location string 必填字段 示例:"Canada East"。即 Azure 区域(官方文档中称为 "Regions")。
apiTimeout metav1.Duration 2m0s 等待 Azure API 请求完成前的最长超时时间。

源码级纵深:从 Config 到 BackupStorageLocation 的演进

理解 v0.6.0 的 Config 定义,最好的锚点是它在当前 Velero 仓库中的"后代"——BackupStorageLocation。仓库文档 locations.md 明确指出:自 v0.10.0 起,Config 自定义资源被移除,由两个新 CRD 取代:

  • BackupStorageLocation(BSL):直接取代 Config.backupStorageProvider 段;
  • VolumeSnapshotLocation(VSL):直接取代 Config.persistentVolumeProvider 段。

这一演进的核心动机在 locations.md 中列得很清楚:原 Config 设计无法支持"单个备份内对多种 PV 类型做快照""同一集群备份到不同区域的桶""部分快照存本地、部分存云端"等场景,也无法为未来的备份复制(replication)提供多位置支持。

从当前类型定义 backupstoragelocation_types.go 可以看到现代 BSL 的 Spec 结构:provider(提供方名称,如 aws/azure/gcp/minio)、config(map[string]string 提供方专有配置)、bucket 与 prefix(桶内路径前缀)、credential(凭据引用)、accessMode(ReadOnly/ReadWrite)以及 backupSyncPeriod。对照可知:

  • 原 backupStorageProvider.name → 现 spec.provider;
  • 原 backupStorageProvider.bucket → 现 spec.objectStorage.bucket;
  • 原 backupStorageProvider.config → 现 spec.config(继续承载 region、s3ForcePathStyle、s3Url、kmsKeyId 等键);
  • 原全局的 backupSyncPeriod 在此演化为 BSL 级别的可选项(*metav1.Duration,值为 0 时禁用同步),并可配合 validationFrequency 控制存储位置校验节奏。

API 文档 backupstoragelocation.md 中同样标注:"BackupStorageLocation takes the place of the Config.backupStorageProvider key as of v0.10.0",与 locations.md 相互印证。

新旧对照速查

Ark v0.6 Config 字段 Velero v0.10+ 对应位置 说明
backupStorageProvider.name BackupStorageLocation.spec.provider 备份存储提供方
backupStorageProvider.bucket BackupStorageLocation.spec.objectStorage.bucket 存储桶
backupStorageProvider.config BackupStorageLocation.spec.config 提供方专有键值
persistentVolumeProvider.name VolumeSnapshotLocation.spec.provider 快照提供方
persistentVolumeProvider.config VolumeSnapshotLocation.spec.config 快照提供方专有键值
backupSyncPeriod BackupStorageLocation.spec.backupSyncPeriod 由全局配置细化为位置级配置
restoreOnlyMode backup storage location accessMode: ReadOnly 以只读位置替代全局开关

实践建议与注意事项

  1. 命名与命名空间不可更改:Config 资源必须命名为 default 并创建于 heptio-ark 命名空间,否则 Ark server 会一直等待;
  2. 配置变更依赖 Pod 重启:修改 Config 后 Ark server 会优雅退出,由 kubelet 重启后加载新值,升级配置请预留短暂的不可用窗口;
  3. PV 快照能力是可选项:集群没有可快照 PV 或无需快照时,可省略 persistentVolumeProvider;但一旦 Backup/Restore 请求了快照而 Config 未配置该段,相关请求会被判定为无效;
  4. Azure 快照有版本门槛:Azure 托管磁盘快照要求集群 Kubernetes 1.7.2+,低于该版本需先升级集群;
  5. 本地存储注意 path-style:对接 Minio 等 S3 兼容本地存储时,务必同时配置 s3ForcePathStyle: true 与 s3Url;
  6. 现代替代方案:若你使用的是 v0.10.0 及以后的 Velero,请直接使用 BackupStorageLocation / VolumeSnapshotLocation CRD 完成同样的存储配置,并借助 accessMode: ReadOnly 实现原 restoreOnlyMode 的只读灾备场景。
登录后查看全文
velero