Velero `ark schedule create` 命令详解：从 v0.5.0 参考手册到周期备份 Schedule 的构建原理

Veleroark schedule create命令详解从 v0.5.0 参考手册到周期备份 Schedule 的构建原理【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文以 Velero 仓库中 v0.5.0 时期的 CLI 参考文档ark schedule create为主体完整还原该命令的用法与全部参数并结合当前仓库中的 命令实现、Schedule API 类型 与 Schedule 控制器 源码讲清一条周期备份从命令行参数、CR 构建到由控制器自动触发 Backup 的完整链路。读完本文你将掌握 Schedule 命令的每个 flag 的语义、cron 表达式规范以及 Velero 服务端判定“是否到点执行备份”的底层逻辑。命令定位v0.5.0 时期的 ark 前缀时代该参考文档位于仓库的 v0.5.0 CLI 参考目录 中文件为 ark_schedule_create.md。注意文档中的命令前缀是ark而非velerov0.5.0 时期项目仍以 Ark 命名CLI 参考按当时的命令树组织ark schedule是 Schedule 相关命令的父级见 ark_schedule.md。原文档给出的命令语法为ark schedule create NAME [flags]功能一句话概括创建一个 Schedule周期备份计划。Schedule 是 Velero 的一种资源用于按 cron 表达式或固定间隔周期性触发 Backup。在当前仓库中对应的命令实现位于 pkg/cmd/cli/schedule/create.go注册于 schedule 命令组子命令形式为create NAME --schedule ...。--schedule 参数cron 表达式与 every 语法--schedule是这条命令的灵魂参数指定备份的重复执行周期。原文档将其描述为--schedule string a cron expression specifying a recurring schedule for this backup to run当前源码在命令的长描述中进一步给出了 cron 表达式的完整规范pkg/cmd/cli/schedule/create.go使用 UTC 时间字符位置含义可接受取值1分钟 (Minute)0-59, *2小时 (Hour)0-23, *3日 (Day of Month)1-31, *4月 (Month)1-12, *5星期 (Day of Week)0-6, *除了标准 cron 表达式还可以使用every duration语法duration 支持秒s、分钟m、小时h的组合例如every 2h30m。从源码结构看控制器端用github.com/netresearch/go-cron的ParseStandard解析表达式pkg/controller/schedule_controller.go解析失败不会导致命令报错而是将 Schedule 的 phase 置为FailedValidation并记录validationErrors——也就是说cron 表达式的合法性校验发生在服务端控制器侧而非 CLI 侧创建命令本身只检查--schedule非空pkg/cmd/cli/schedule/create.go。v0.5.0 文档中的完整参数表原样继承以下为原文档列出的全部命令选项按原文组织--exclude-namespaces stringArray namespaces to exclude from the backup --exclude-resources stringArray resources to exclude from the backup, formatted as resource.group, such as storageclasses.storage.k8s.io -h, --help help for create --include-cluster-resources optionalBool[true] include cluster-scoped resources in the backup --include-namespaces stringArray namespaces to include in the backup (use * for all namespaces) (default *) --include-resources stringArray resources to include in the backup, formatted as resource.group, such as storageclasses.storage.k8s.io (use * for all resources) --label-columns stringArray a comma-separated list of labels to be displayed as columns --labels mapStringString labels to apply to the backup -o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are table, json, and yaml. --schedule string a cron expression specifying a recurring schedule for this backup to run -l, --selector labelSelector only back up resources matching this label selector (default none) --show-labels show labels in the last column --snapshot-volumes optionalBool[true] take snapshots of PersistentVolumes as part of the backup --ttl duration how long before the backup can be garbage collected (default 24h0m0s)几个关键参数的语义说明--include-namespaces/--exclude-namespaces命名空间级的备份范围控制前者默认为*全部命名空间两者不能同时使用否则备份范围为空。--include-resources/--exclude-resources资源类型级控制格式为resource.group例如storageclasses.storage.k8s.io。--include-cluster-resources可选布尔值默认为 true控制是否包含集群级非命名空间级资源。--snapshot-volumes可选布尔值默认为 true决定备份时是否为 PersistentVolume 做快照。--ttl每份由该 Schedule 生成的 Backup 保留多久后被垃圾回收v0.5.0 文档中默认值为24h0m0s。--labels为备份打上标签方便后续velero get backups -l ...检索。-o/--output以table、json、yaml格式只打印对象而不提交到服务端是“dry-run 式”查看将要创建的对象的实用参数。在当前源码中该能力由output.PrintWithFormat实现pkg/cmd/cli/schedule/create.go一旦-o生效对象打印后直接返回不会执行crClient.Create。从父命令继承的选项原文档还列出了继承自父命令ark根命令的全局选项主要是日志与连接配置--alsologtostderr log to standard error as well as files --kubeconfig string Path to the kubeconfig file to use to talk to the Kubernetes apiserver. If unset, try the environment variable KUBECONFIG, as well as in-cluster configuration --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) --log_dir string If non-empty, write log files in this directory --logtostderr log to standard error instead of files --stderrthreshold severity logs at or above this threshold go to stderr (default 2) -v, --v Level log level for V logs --vmodule moduleSpec comma-separated list of patternN settings for file-filtered logging其中--kubeconfig决定了 CLI 与哪个集群通信未设置时回退到KUBECONFIG环境变量与 in-cluster 配置日志类选项则用于调低/调高 Velero 客户端的日志详细程度。现代实现命令如何把参数组装成 Schedule CR当前仓库中的 pkg/cmd/cli/schedule/create.go 展示了这条命令的完整实现其选项结构体为type CreateOptions struct { BackupOptions *backup.CreateOptions SkipOptions *SkipOptions Schedule string UseOwnerReferencesInBackup bool Paused bool }两个值得注意的设计点复用 Backup 的全部选项CreateOptions内嵌backup.CreateOptions因此 Schedule 天然继承了backup create的所有备份范围类参数include/exclude 命名空间与资源、selector、TTL、snapshot-volumes、storage-location、CSI 快照超时等。Run方法pkg/cmd/cli/schedule/create.go将BackupOptions中的各字段逐一映射进ScheduleSpec.Template即一个BackupSpec再叠加Schedule、UseOwnerReferencesInBackup、Paused、SkipImmediately四个 Schedule 专属字段。v0.5.0 之后新增的参数当前命令比 v0.5.0 文档多出--paused创建即暂停、--use-owner-references-in-backup为 Schedule 生成的 Backup 设置 OwnerReference删除 Schedule 时关联 Backup 一并级联删除等 flag且当--resource-policy指定 ConfigMap 时会在Template.ResourcePolicy中写入引用--uploader parallel-files-upload则写入Template.UploaderConfig。执行流程严格遵循 Complete → Validate → Run 三段式pkg/cmd/cli/schedule/create.goValidate 强制--schedule非空Run 中通过 kubebuilder client 创建 CR成功后输出Schedule %q created successfully.。Schedule CR 的结构与生命周期Schedule 资源的 Go 类型定义在 pkg/apis/velero/v1/schedule_types.gotype ScheduleSpec struct { Template BackupSpec json:template // 每次触发的 Backup 模板 Schedule string json:schedule // Cron 表达式 UseOwnerReferencesInBackup *bool json:useOwnerReferencesInBackup,omitempty Paused bool json:paused,omitempty SkipImmediately *bool json:skipImmediately,omitempty }Template是BackupSpec即一次备份的完整定义Paused为 true 时控制器直接跳过该 ScheduleSkipImmediately控制“新创建或刚被 un-pause且恰好已到点”时是否先跳过一次、等下一个周期再跑为空时跟随服务端配置默认 false。状态侧有三个 phasepkg/apis/velero/v1/schedule_types.goPhase含义New已创建但尚未被 ScheduleController 处理Enabled校验通过按 schedule 触发备份FailedValidationcron 表达式等校验失败不会触发备份ScheduleStatus还包含LastBackup最近一次触发时间、LastSkipped与ValidationErrorsCRD 的 printcolumns 会在kubectl get schedules中直接展示 Status、Schedule、LastBackup、Age、Paused 列短名为sched见 pkg/apis/velero/v1/schedule_types.go。由 Schedule 生成的 Backup 名称由TimestampedName方法生成格式为schedule-name-YYYYMMDDHHmmsspkg/apis/velero/v1/schedule_types.go。服务端触发机制一分钟一拍的控制器Schedule 控制器 是理解“备份到底什么时候跑”的关键源码中可以看到以下行为周期性入队控制器以scheduleSyncPeriod time.Minute的间隔对全量 Schedule 做周期性 reconcilepkg/controller/schedule_controller.go并在入队谓词中过滤掉Spec.Paused true的 Schedulepkg/controller/schedule_controller.go。每次 reconcile 都重新校验 cron 表达式parseCronSchedule用cron.ParseStandard解析空表达式或解析 panic 都会产生校验错误phase 置为FailedValidation并写入status.validationErrorspkg/controller/schedule_controller.go。校验通过则为Enabled并计算相邻两次触发的期望间隔用于指标。到点判定基于 LastBackup/LastSkippedgetNextRunTime取status.lastBackup若无则取创建时间与status.lastSkipped中较晚者调用cronSchedule.Next(lastBackupTime)得到下一次触发时间当“当前时间晚于该时间”即判定到点pkg/controller/schedule_controller.go。避免重叠运行触发前checkIfBackupInNewOrProgress会列出该 Schedule 名下的 Backup按schedule-name标签选择只要还有处于New或InProgress阶段的备份就跳过本次创建防止同一 Schedule 的备份互相重叠pkg/controller/schedule_controller.go。不补跑错过周期源码注释明确说明不会“catch up”——错过或失败的周期不会补做只在到点时触发一次新的 Backuppkg/controller/schedule_controller.gosubmitBackup创建 Backup 后把当前时间 patch 回status.lastBackup。skipImmediately 逻辑若spec.skipImmediately为 true 且当前已到期reconcile 会将其置回 false 并记录status.lastSkipped等效于“本次跳过下个周期再跑”pkg/controller/schedule_controller.go。实操示例综合原文档的参数语义与当前 create.go 中的官方示例常用创建命令如下# 每 6 小时备份一次 velero schedule create my-schedule --schedule0 */6 * * * # 用 every 语法表示每 6 小时 velero schedule create my-schedule --scheduleevery 6h # 每天只备份 web 命名空间 velero schedule create my-schedule --scheduleevery 24h --include-namespaces web # 每周备份一次每份备份保留 90 天2160 小时 velero schedule create my-schedule --scheduleevery 168h --ttl 2160h0m0s创建后可以用velero schedule get查看 phase、schedule 表达式与最近一次备份时间对应 CRD printcolumns 的 Status / Schedule / LastBackup / Paused 列也可以先加-o yaml预览将要提交的 Schedule 对象而不实际创建。小结与延伸阅读ark schedule create现velero schedule create的参数面在 v0.5.0 时代已经覆盖了命名空间/资源范围、标签、快照开关、TTL 与输出格式核心是--schedule这一 cron/every 表达式现代实现在此基础上把全部backup create选项通过CreateOptions内嵌继承并新增--paused、--use-owner-references-in-backup、skipImmediately等能力。Schedule 的校验、到点判定、防重叠与不补跑策略则完全由 Schedule 控制器 在服务端闭环完成。进一步阅读可参考 Schedule API 类型定义、schedule 命令组注册 以及 v0.5.0 CLI 参考中的 ark schedule 总览 与 delete/get 子命令。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考