Velero(Ark)Config 自定义资源详解:backupStorageProvider 与 persistentVolumeProvider 配置指南
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 形式运行的。若
defaultConfig 被修改,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 的两大核心职责:
- persistentVolumeProvider:声明集群持久卷(PV)快照所使用的云提供方(仅当需要做 PV 快照时配置);
- 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 |
以只读位置替代全局开关 |
实践建议与注意事项
- 命名与命名空间不可更改:Config 资源必须命名为
default并创建于heptio-ark命名空间,否则 Ark server 会一直等待; - 配置变更依赖 Pod 重启:修改 Config 后 Ark server 会优雅退出,由 kubelet 重启后加载新值,升级配置请预留短暂的不可用窗口;
- PV 快照能力是可选项:集群没有可快照 PV 或无需快照时,可省略
persistentVolumeProvider;但一旦 Backup/Restore 请求了快照而 Config 未配置该段,相关请求会被判定为无效; - Azure 快照有版本门槛:Azure 托管磁盘快照要求集群 Kubernetes 1.7.2+,低于该版本需先升级集群;
- 本地存储注意 path-style:对接 Minio 等 S3 兼容本地存储时,务必同时配置
s3ForcePathStyle: true与s3Url; - 现代替代方案:若你使用的是 v0.10.0 及以后的 Velero,请直接使用
BackupStorageLocation/VolumeSnapshotLocationCRD 完成同样的存储配置,并借助accessMode: ReadOnly实现原restoreOnlyMode的只读灾备场景。