Velero 集群配置指南:Config 自定义资源详解与云厂商参数参考
Velero 集群配置指南:Config 自定义资源详解与云厂商参数参考
Velero 通过一个名为 Config 的 Kubernetes 自定义资源来集中定义备份存储、云厂商凭证与后台任务调度等核心参数,是集群部署完成后第一个需要创建的配置对象。本文基于仓库中的官方配置定义文档,逐字段解析主配置参数、AWS/GCP/Azure 三家云厂商的专属配置项,并结合当前仓库源码说明各参数在控制器与恢复流程中的实际作用,帮助你写出一份可运行、可排错的生产级 Velero 配置。
Overview:为什么需要一个 Config 自定义资源
在早期版本(Heptio Ark 时代,即 Velero 的前身)中,备份与云厂商相关设置并不分散在各个命令行参数里,而是统一收敛在一个自定义资源对象 Config 上。当 Ark 服务器首次部署完成时,它会一直等待你在这个资源的专属命名空间(heptio-ark)中创建名为 default 的 Config 对象,随后才开始正常工作。
说明:当前仓库中的
ConfigCRD 定义仍保留在 config/crd/v1 目录下,其核心字段与本文档描述的Config一脉相承;在现代版本中,备份存储与 PV 快照厂商相关配置已演进为独立的BackupStorageLocation(见 backupstoragelocation_types.go)与VolumeSnapshotLocation资源,但从Config理解这些参数的语义依然是入门 Velero 的最佳路径。
配置生效机制
文档中特别强调了一个底层假设:Ark/Velero 服务器是以 Kubernetes Deployment 形式运行的。这带来两个关键行为:
- 修改
defaultConfig 后,服务器进程会优雅关闭; - kubelet 随后会自动重启 Ark 服务器 Pod,重启后服务器才会读取并使用更新后的配置值。
这意味着 Config 的变更不会热生效,任何改动都必须依赖 Pod 重启周期才能真正生效,排查配置问题时需要等待这一重启过程完成。
Example:一份完整的示例 Config
文档给出了一个可直接套用的 YAML 示例,覆盖了 PV 快照提供方(AWS)、备份存储提供方(AWS)、以及三个后台同步周期参数:
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
几个值得注意的字段约定:
apiVersion使用ark.heptio.com/v1(Heptio Ark 时代的 API 组),命名空间必须是heptio-ark,名称必须是default;persistentVolumeProvider声明集群用于创建 PV 快照的云厂商,backupStorageProvider声明实际存放备份文件的存储后端,两者可以相同(如示例均为 aws),也可以不同;- 三个
*SyncPeriod字段均使用 Go 的metav1.Duration字符串格式(如60m、1m)。
Parameter Reference:主配置参数详解
文档将 Config 的顶层参数划分为"主配置"与"云厂商专属配置"两类。主配置参数如下:
| Key | Type | Default | Meaning |
|---|---|---|---|
persistentVolumeProvider |
CloudProviderConfig | None (Optional) | 集群持久卷(待快照)所使用的云厂商规格。若未指定,则请求 PV 快照与恢复的 Backup/Restore 会被判定为无效。 注意:对于 Azure,集群需要 1.7.2+ 版本才能支持托管磁盘(managed disks)的 PV 快照。 |
persistentVolumeProvider/name |
String(Ark 原生支持 aws、gcp、azure,其他厂商可通过外部插件提供) |
None (Optional) | 集群持久卷所使用的云厂商名称(如有)。 |
persistentVolumeProvider/config |
map[string]string(见下方 AWS/GCP/Azure 专属配置或厂商文档) | None (Optional) | 传递给云厂商用于持久卷的配置键值对。 |
backupStorageProvider |
CloudProviderConfig | Required Field | 实际存储备份文件的云厂商规格。 |
backupStorageProvider/name |
String(Ark 原生支持 aws、gcp、azure,其他厂商可通过外部插件提供) |
Required Field | 实际存储备份文件的云厂商名称。 |
backupStorageProvider/bucket |
String | Required Field | 备份文件上传的存储桶。 |
backupStorageProvider/config |
map[string]string(见下方 AWS/GCP/Azure 专属配置或厂商文档) | None (Optional) | 传递给云厂商用于备份存储的配置键值对。 |
backupSyncPeriod |
metav1.Duration | 60m0s | 服务器多久查询一次对象存储,以确保为已有备份文件创建了对应的 Backup 资源。 |
gcSyncPeriod |
metav1.Duration | 60m0s | 服务器多久查询一次对象存储,删除已超过 TTL 的备份文件。 |
scheduleSyncPeriod |
metav1.Duration | 1m0s | 服务器多久检查一次 Schedule 资源对象,判断是否需要发起一次备份。 |
resourcePriorities |
[]string | [namespaces, persistentvolumes, persistentvolumeclaims, secrets, configmaps] |
描述 Kubernetes 资源对象恢复顺序的有序列表(也支持 <RESOURCE>.<GROUP> 格式)。不在列表中的资源会在所有优先资源之后恢复。 |
restoreOnlyMode |
bool | false |
开启后,备份、调度以及过期备份删除功能被关闭,仅从对象存储中的现有备份文件执行恢复。 |
参数要点与源码印证
1. backupSyncPeriod:对象存储与集群内 Backup 资源的双向同步
该参数控制 Velero 周期性扫描对象存储、把远端备份文件映射为集群内 Backup 资源对象的频率。当前仓库中该逻辑由 backup_sync_controller.go 实现:
- 控制器以
defaultBackupSyncPeriod为默认周期,但优先读取每个存储位置自己的Spec.BackupSyncPeriod(对应 backupstoragelocation_types.go 中的字段注释:"BackupSyncPeriod defines how frequently to sync backup API objects from object storage. A value of 0 disables sync."); - 当某个位置的同步周期设为
0时,该位置会被跳过同步(locationFilterFunc中直接返回false,见 backup_sync_controller.go); - 周期为负数时回退到默认值,同时依据
Status.LastSyncedTime判断是否已到下一次同步时间点。
2. gcSyncPeriod:过期备份的垃圾回收节奏
该参数控制删除已过 TTL 备份文件的频率,对应当前仓库中的 gc_controller.go。其默认频率常量同样为 60 分钟(defaultGCFrequency = 60 * time.Minute,见 gc_controller.go),且控制器通过 NewPeriodicalEnqueueSource 周期性入队 Backup 对象触发检查,并只在 Create 事件上全量处理,Update 事件被过滤以减少无谓的 reconcile 调用。
3. scheduleSyncPeriod:Schedule 资源的周期检查
该参数控制服务器检查 Schedule 资源、判断是否需要按计划发起备份的频率。当前仓库的 schedule_controller.go 中定义了 scheduleSyncPeriod = time.Minute 的默认常量,并通过 kube.NewPeriodicalEnqueueSource 周期性枚举 Schedule 列表;已被暂停(Spec.Paused)的 Schedule 会被过滤跳过。
4. resourcePriorities:恢复顺序的底层实现
文档提到资源可以 <RESOURCE>.<GROUP> 格式指定。当前仓库将该能力抽象为 types.Priorities(见 priority.go),区分 HighPriorities(先恢复)与 LowPriorities(后恢复)两段。核心排序函数 getOrderedResources 的实现逻辑是:
- 先按顺序输出全部高优先级资源;
- 中间是备份中存在但未列入优先级列表的资源(按字母序排列);
- 最后按顺序输出全部低优先级资源。
对应测试用例见 restore_test.go(TestRestoreResourcePriorities)与 priority_test.go,可据此验证自定义优先级列表的实际行为。
5. restoreOnlyMode:只读恢复模式
开启后服务器关闭备份、调度与过期备份删除能力,仅允许基于对象存储中已有备份文件执行恢复。这在"从异地恢复集群"或"灾难恢复演练"场景中尤为实用——例如先将备份数据推送到目标存储,再以只读模式启动 Velero,避免误触发新的备份任务。
AWS(及其他 S3 兼容存储)专属参数
backupStorageProvider/config
| Key | Type | Default | Meaning |
|---|---|---|---|
region |
string | Required Field | 示例:"us-east-1"。参见 AWS 官方可用区域文档。 |
s3ForcePathStyle |
bool | false |
使用 Minio 等本地存储服务时设为 true。 |
s3Url |
string | 非 AWS 托管存储时必填 | 示例:http://minio:9000。也可显式指定 AWS S3 URL,但 Ark 可以根据 region 与 bucket 自动生成;此字段主要服务于 Minio 等本地存储服务。 |
kmsKeyId |
string | Empty | 示例:"502b409c-4da1-419f-a16e-eif453b3i49f" 或 "alias/<KMS-Key-Alias-Name>"。指定 AWS KMS 密钥 ID 或别名以启用 S3 备份加密。仅适用于 AWS S3,且可能需要显式授予密钥使用权限。 |
配置 Minio 的典型写法(本地开发/测试环境常见):
backupStorageProvider:
name: aws
bucket: ark
config:
region: minio
s3ForcePathStyle: true
s3Url: http://minio:9000
其中 region 在 Minio 场景下可按需填写任意值(Minio 不校验区域真实性),关键是 s3ForcePathStyle: true 与 s3Url 必须指向 Minio 服务的可访问地址。仓库中的 Minio 示例部署可参考 examples/minio/00-minio-deployment.yaml。
persistentVolumeProvider/config(仅 AWS)
| Key | Type | Default | Meaning |
|---|---|---|---|
region |
string | Required Field | 示例:"us-east-1"。参见 AWS 官方可用区域文档。 |
GCP 专属参数
backupStorageProvider/config
无需任何参数。 GCP 对象存储(GCS)的连接信息由环境凭证自动提供,无需在 Config 中额外填写区域或桶路径之外的参数。
persistentVolumeProvider/config
| Key | Type | Default | Meaning |
|---|---|---|---|
project |
string | Required Field | 示例:"project-example-3jsn23"。填写 GCP 项目 ID。 |
Azure 专属参数
backupStorageProvider/config
无需任何参数。 Azure Blob 存储的连接参数由环境凭证提供。
persistentVolumeProvider/config
| Key | Type | Default | Meaning |
|---|---|---|---|
location |
string | Required Field | 示例:"Canada East"。填写 Azure 数据中心位置(官方文档中称为 "Regions")。 |
apiTimeout |
metav1.Duration | 2m0s | Azure API 请求的超时等待时长。 |
注意文档特别提示:若需对 Azure 托管磁盘做 PV 快照,Kubernetes 集群版本必须为 1.7.2+。
实战建议:从 Config 到现代 Velero 的映射
如果你今天直接在 Velero 中实践,可以按以下思路对照 Config 文档落地:
- 理解配置对象:
Config是 Velero(Heptio Ark)配置体系的起点,后续版本将其拆分为BackupStorageLocation(备份存储,含Provider、Config、Bucket等字段,见 backupstoragelocation_types.go)与VolumeSnapshotLocation(PV 快照位置,见 volume_snapshot_location_type.go)两个资源,语义一一对应; - 验证默认值:三个同步周期(
backupSyncPeriod60m、gcSyncPeriod60m、scheduleSyncPeriod1m)的默认行为均能在当前仓库控制器源码中找到对应常量与实现; - 规划恢复顺序:通过
resourcePriorities或现代的--restore-resource-priorities标志(解析逻辑见 config.go)控制恢复时资源创建的先后顺序; - 合理使用
restoreOnlyMode:灾难恢复场景下先同步备份再以只读模式启动,防止误触发新备份。
总结
Config 自定义资源以一份 YAML 集中承载了 Velero(Ark)的云厂商接入、存储桶、同步周期与恢复策略等核心配置。理解其 persistentVolumeProvider / backupStorageProvider 的双提供方模型、三个 SyncPeriod 的调度语义、resourcePriorities 的恢复顺序以及 restoreOnlyMode 的只读模式,是掌握 Velero 配置体系的关键。结合仓库中 backup_sync_controller.go、gc_controller.go、schedule_controller.go 与 restore.go 的源码实现,你可以在配置出现异常时快速定位是周期设置、存储位置还是恢复顺序策略导致的问题。