Ark（Velero 前身）ark schedule命令全解析：定时备份的创建、查询与运维
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
导读
ark schedule是 Ark（Velero 的前身项目）CLI 中管理定时备份（Schedule）的入口命令。本文以 v0.9.0 文档为骨架，完整梳理ark schedule及其create/get/describe/delete四个子命令的语法、参数与使用场景，并结合当前仓库中 pkg/cmd/cli/schedule 的 CLI 实现、schedule_controller.go 的控制器逻辑与 schedule_types.go 的 API 类型定义，深入讲解 Cron 表达式的校验规则、调度的执行时机判定与备份命名规则。读完本文，你将能独立完成"按周期自动备份 Kubernetes 集群资源"的完整配置与日常运维。
说明：v0.9.0 时代的命令行工具名为
ark，对应项目即今天广泛使用的 Velero；当前仓库中命令已演进为velero schedule ...，其语义与 v0.9.0 文档保持一致，文中会同步说明两者差异。
命令概览：ark schedule的职责边界
ark schedule本身是一个命令分组（group command），对应源码 pkg/cmd/cli/schedule/schedule.go 中Use: "schedule"、Short: "Work with schedules"的定义，其作用是聚合以下四个子命令：
| 子命令 | 作用 | 对应文档 |
|---|---|---|
ark schedule create | 创建定时备份计划 | ark_schedule_create.md |
ark schedule get | 列出已存在的调度计划 | ark_schedule_get.md |
ark schedule describe | 查看单个/多个调度的详细信息 | ark_schedule_describe.md |
ark schedule delete | 删除调度计划 | ark_schedule_delete.md |
直接运行ark schedule或ark schedule -h只会打印帮助信息：
ark schedule [command] Available Commands: create Create a schedule delete Delete a schedule describe Describe schedules get Get schedules Flags: -h, --help help for schedule在现在的 Velero 版本中，该分组命令对应为velero schedule，子命令为velero schedule create/get/describe/delete/pause/unpause，其中pause（暂停）与unpause（恢复）是后续版本新增的能力，见源码 pkg/cmd/cli/schedule/pause.go 与 pkg/cmd/cli/schedule/unpause.go。
全局继承参数：每个子命令都会携带的选项
ark schedule的所有子命令都会自动继承父命令的全局选项，这些选项主要控制 kubeconfig 连接方式、日志输出与命名空间。由于它们对所有 ark 命令通用，理解一次即可：
| 参数 | 说明 |
|---|---|
--alsologtostderr | 除了写入日志文件外，同时将日志输出到标准错误 |
--kubeconfig string | 连接 Kubernetes apiserver 使用的 kubeconfig 路径；未设置时依次尝试环境变量KUBECONFIG与集群内配置 |
--kubecontext string | 指定 kubeconfig 中的 context；默认使用kubectl config current-context对应的当前上下文 |
--log_backtrace_at traceLocation | 当日志命中file:N时输出堆栈信息（默认:0） |
--log_dir string | 非空时指定日志文件写入目录 |
--logtostderr | 将日志输出到标准错误而非文件 |
-n, --namespace string | Ark 操作的命名空间，v0.9.0 默认heptio-ark（当前 Velero 版本默认velero） |
--stderrthreshold severity | 达到该级别及以上的日志输出到 stderr（默认 2，即 ERROR） |
-v, --v Level | V 级别日志（verbose）的日志等级 |
--vmodule moduleSpec | 逗号分隔的pattern=N形式的文件过滤日志配置 |
其中--namespace是最常用的参数：Ark 的 Schedule、Backup 等自定义资源都存放在该命名空间下，因此查询调度时务必保证-n与安装 Ark 时使用的命名空间一致。
创建定时备份：ark schedule create
命令语法与核心机制
ark schedule create NAME --schedule [flags]--schedule是必填参数，要求使用 Cron 表达式，且按UTC 时间计算（源码 pkg/cmd/cli/schedule/create.go 第 44 行明确指出 "using UTC time"）。v0.9.0 文档给出了标准五段式 Cron 的位置与取值范围：
| 字符位置 | 字符含义 | 可接受值 |
|---|---|---|
| 1 | 分钟（Minute） | 0-59, * |
| 2 | 小时（Hour） | 0-23, * |
| 3 | 每月第几天（Day of Month） | 1-31, * |
| 4 | 月份（Month） | 1-12, * |
| 5 | 每周第几天（Day of Week） | 0-7, * |
官方示例：
ark create schedule NAME --schedule="0 */6 * * *"该示例表示每 6 小时触发一次备份（在每小时的第 0 分钟执行）。v0.9.0 文档同时保留了ark create schedule这一等价的命令别名写法。
从源码角度看，create子命令通过flags.StringVar(&o.Schedule, "schedule", o.Schedule, "A cron expression specifying a recurring schedule for this backup to run")（create.go）接收表达式，并在创建Schedule对象时将其写入spec.schedule字段（见 schedule_types.go 中ScheduleSpec.Schedule的定义："A Cron expression defining when to run the Backup"）。
create 专用选项详解
| 参数 | 默认值 | 说明 |
|---|---|---|
--exclude-namespaces stringArray | 空 | 从备份中排除的命名空间列表 |
--exclude-resources stringArray | 空 | 从备份中排除的资源，格式为resource.group，例如storageclasses.storage.k8s.io |
--include-cluster-resources optionalBool[=true] | true | 是否在备份中包含集群级（cluster-scoped）资源 |
--include-namespaces stringArray | * | 需要包含的命名空间，*表示全部 |
--include-resources stringArray | 空 | 需要包含的资源，格式为resource.group，*表示全部资源 |
--label-columns stringArray | 空 | 在get输出中作为附加列展示的标签列表 |
--labels mapStringString | 空 | 应用到备份对象上的标签 |
-o, --output string | 空 | 输出格式，create 命令下仅展示对象而不提交到服务端，可选table、json、yaml |
--schedule string | 必填 | 指定备份运行周期的 Cron 表达式 |
-l, --selector labelSelector | <none> | 只备份匹配该标签选择器的资源 |
--show-labels | false | 在输出中显示标签列 |
--snapshot-volumes optionalBool[=true] | true | 是否在备份中对 PersistentVolume 做快照 |
--ttl duration | 720h0m0s（30 天） | 备份在可以被垃圾回收前保留的时长 |
其中--ttl默认 30 天，即每个由该调度生成的备份在创建 720 小时后才允许被 GC 清理；--snapshot-volumes控制是否同时快照持久卷（CSI 卷与云提供商原生快照均受此开关约束）；-o json/yaml可以预先检视将要创建的 Schedule 对象定义，非常适合在 CI 中做 dry-run 验证。
一个完整的创建示例
ark schedule create daily-backup \ --schedule="0 2 * * *" \ --include-namespaces=default,app1 \ --include-cluster-resources=true \ --ttl=168h \ --snapshot-volumes=true \ -n heptio-ark该命令在 UTC 每日 02:00 触发备份，仅包含default与app1两个命名空间，快照持久卷，保留 7 天（168 小时）。通过-o yaml可预览最终提交的对象，例如ark schedule create dry-run --schedule="0 2 * * *" -o yaml。
查询与展示：get与describe
ark schedule get：列表视图
ark schedule get [flags]| 参数 | 说明 |
|---|---|
-h, --help | 帮助信息 |
--label-columns stringArray | 需要作为附加列显示的标签 |
-o, --output string | 输出格式，默认table，可选json、yaml |
-l, --selector string | 只显示匹配该标签选择器的调度 |
--show-labels | 在最后一列显示标签 |
默认表格输出会展示调度的名称、阶段（Phase）、调度表达式、上次备份时间与年龄。从 API 定义看，这些列由 CRD 的 printcolumn 注解生成：Status取自.status.phase、Schedule取自.spec.schedule、LastBackup取自.status.lastBackup、Paused取自.spec.paused（见 schedule_types.go）。-o json/-o yaml则导出完整对象，便于审计或二次处理。
ark schedule describe：单对象详情
ark schedule describe [NAME1] [NAME2] [NAME...] [flags]| 参数 | 说明 |
|---|---|
-h, --help | 帮助信息 |
-l, --selector string | 只显示匹配该标签选择器的调度 |
与get不同，describe可同时传入多个名称（[NAME1] [NAME2] ...），并展示更详细的状态信息，包括调度的 Phase、LastBackup 时间、LastSkipped 时间以及校验错误（ValidationErrors）等字段。
关于 Phase 状态的理解
查询调度时你看到的 Phase 对应 schedule_types.go 中定义的三种枚举值：
New：调度已创建但尚未被 ScheduleController 处理；Enabled：调度已通过校验，将按spec.schedule触发备份；FailedValidation：调度未通过控制器校验（如 Cron 表达式非法），不会触发任何备份。
当调度处于FailedValidation时，应通过describe查看ValidationErrors字段定位具体原因（例如 "invalid schedule: ..."）。
删除调度：ark schedule delete
ark schedule delete NAME [flags]delete子命令通过名称删除指定的 Schedule 对象，除-h, --help外无额外专属参数，全局参数仍全部可用（如-n指定命名空间）。
需要特别注意：删除 Schedule 不会自动删除它已经生成的 Backup 对象。从 schedule_controller.go 的submitBackup逻辑可见，调度创建备份时只是通过c.Create(ctx, backup)提交独立的 Backup 资源，二者生命周期相互独立。若需清理历史备份，请另行使用ark backup delete（对应 ark_backup_delete.md）。
源码视角：调度控制器如何"到点触发"备份
理解 CLI 参数如何落地，关键在于 ScheduleController 的实现（pkg/controller/schedule_controller.go）。其核心流程如下：
解析并校验 Cron 表达式：控制器通过
parseCronSchedule调用cron.ParseStandard解析spec.schedule。源码对空字符串做了防御：先检查长度，再用recover()包裹cron.Parse（因为其对空串会 panic）。解析失败时，调度进入FailedValidation阶段并记录错误信息（第 185-223 行）。判定是否到期：
ifDue→getNextRunTime计算逻辑为：取status.lastBackup（无则为创建时间）与status.lastSkipped中较晚的时间作为基准，调用cronSchedule.Next(lastBackupTime)得到下一次运行时刻，若当前时间晚于该时刻则认为到期（第 286-300 行）。避免重叠执行：
checkIfBackupInNewOrProgress会检查是否存在由该调度创建、且仍处于New或InProgress阶段的备份；存在则跳过本次触发，避免备份任务重叠堆积（第 225-249 行）。创建备份并记录时间：到期后调用
submitBackup，通过getBackup生成备份对象并创建，随后更新status.lastBackup。备份名称由TimestampedName生成，格式为{scheduleName}-{YYYYMMDDHHMMSS}（见 schedule_types.go），这也是你看到定时备份名称形如daily-backup-20260916020000的原因。
此外，控制器注释明确指出 "Don't attempt to 'catch up' if there are any missed or failed runs"（第 269-270 行），即错过或失败的运行不会补跑，只会等待下一个调度时间点。
与当前 Velero 版本的衔接
v0.9.0 文档中的ark命令在当前仓库中已演变为velero命令，但schedule子命令集的语义基本未变：
velero schedule create NAME --schedule="0 */6 * * *"创建定时备份；velero schedule get/velero schedule describe/velero schedule delete对应查询与删除；- 新增的
velero schedule pause/velero schedule unpause可临时暂停/恢复调度，对应ScheduleSpec.Paused字段（schedule_types.go）。
对应 CLI 源码位于 pkg/cmd/cli/schedule 目录，Schedule CRD 的类型定义与校验约束（含+kubebuilder:validation:Enum与 printcolumn 注解）位于 schedule_types.go，控制器完整逻辑可继续阅读 schedule_controller.go 及其测试 schedule_controller_test.go。若要进一步理解备份本身的创建与恢复流程，可参考 ark_backup_create 与 ark_restore_create 文档。
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
