Velero 集群配置指南:Config 自定义资源详解与云厂商参数参考

原创2026-09-16 14:42:171,950 阅读
文章标签:云原生容器编排灾备存储备份恢复CLI运维高可用

Velero 集群配置指南:Config 自定义资源详解与云厂商参数参考

Velero 通过一个名为 Config 的 Kubernetes 自定义资源来集中定义备份存储、云厂商凭证与后台任务调度等核心参数,是集群部署完成后第一个需要创建的配置对象。本文基于仓库中的官方配置定义文档,逐字段解析主配置参数、AWS/GCP/Azure 三家云厂商的专属配置项,并结合当前仓库源码说明各参数在控制器与恢复流程中的实际作用,帮助你写出一份可运行、可排错的生产级 Velero 配置。

Overview:为什么需要一个 Config 自定义资源

在早期版本(Heptio Ark 时代,即 Velero 的前身)中,备份与云厂商相关设置并不分散在各个命令行参数里,而是统一收敛在一个自定义资源对象 Config 上。当 Ark 服务器首次部署完成时,它会一直等待你在这个资源的专属命名空间(heptio-ark)中创建名为 default 的 Config 对象,随后才开始正常工作。

说明:当前仓库中的 Config CRD 定义仍保留在 config/crd/v1 目录下,其核心字段与本文档描述的 Config 一脉相承;在现代版本中,备份存储与 PV 快照厂商相关配置已演进为独立的 BackupStorageLocation(见 backupstoragelocation_types.go)与 VolumeSnapshotLocation 资源,但从 Config 理解这些参数的语义依然是入门 Velero 的最佳路径。

配置生效机制

文档中特别强调了一个底层假设:Ark/Velero 服务器是以 Kubernetes Deployment 形式运行的。这带来两个关键行为:

  • 修改 default Config 后,服务器进程会优雅关闭;
  • 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 文档落地:

  1. 理解配置对象:Config 是 Velero(Heptio Ark)配置体系的起点,后续版本将其拆分为 BackupStorageLocation(备份存储,含 Provider、Config、Bucket 等字段,见 backupstoragelocation_types.go)与 VolumeSnapshotLocation(PV 快照位置,见 volume_snapshot_location_type.go)两个资源,语义一一对应;
  2. 验证默认值:三个同步周期(backupSyncPeriod 60m、gcSyncPeriod 60m、scheduleSyncPeriod 1m)的默认行为均能在当前仓库控制器源码中找到对应常量与实现;
  3. 规划恢复顺序:通过 resourcePriorities 或现代的 --restore-resource-priorities 标志(解析逻辑见 config.go)控制恢复时资源创建的先后顺序;
  4. 合理使用 restoreOnlyMode:灾难恢复场景下先同步备份再以只读模式启动,防止误触发新备份。

总结

Config 自定义资源以一份 YAML 集中承载了 Velero(Ark)的云厂商接入、存储桶、同步周期与恢复策略等核心配置。理解其 persistentVolumeProvider / backupStorageProvider 的双提供方模型、三个 SyncPeriod 的调度语义、resourcePriorities 的恢复顺序以及 restoreOnlyMode 的只读模式,是掌握 Velero 配置体系的关键。结合仓库中 backup_sync_controller.go、gc_controller.go、schedule_controller.go 与 restore.go 的源码实现,你可以在配置出现异常时快速定位是周期设置、存储位置还是恢复顺序策略导致的问题。

登录后查看全文
velero