企业官网建设流程全解析

Velero（Heptio Ark）ark schedule命令完全指南：创建、查询与删除定时备份

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

导读

本文以 Velero 早期版本（v0.4.0，当时名为 Heptio Ark）的官方 CLI 参考文档 ark_schedule.md 为核心，系统讲解ark schedule子命令组——包括create、get、delete的完整用法、全部命令行参数、继承自父命令的全局选项，并结合当前仓库源码（pkg/cmd/cli/schedule/、pkg/controller/schedule_controller.go）深入剖析其底层工作原理。读完本文，你将掌握如何用 cron 表达式或@every语法编排周期性的 Kubernetes 集群备份任务，并理解 Schedule 背后的 CRD 与控制器实现机制。

一、ark schedule命令概述

1.1 命令作用

ark schedule是 Ark 客户端中用于**管理工作定时备份（Schedules）**的子命令组。其用途描述为 “Work with schedules”（管理调度计划）。在 v0.4.0 中，ark schedule下挂载了三个子命令：

ark schedule是顶层命令ark的五个子命令之一。根据 ark.md 的 "SEE ALSO" 一节，顶层ark命令包含backup、restore、schedule、server、version五个分支，其中ark schedule的定位正是 "Work with schedules"。

说明：v0.4.0 时期该项目名为 Heptio Ark，CLI 前缀为ark；后来项目更名为 Velero，CLI 前缀变为velero。当前仓库中的实现代码已统一使用velero命令名（见 pkg/cmd/cli/schedule/schedule.go），且新增了describe、pause、unpause等子命令，但 v0.4.0 文档所定义的核心用法一脉相承。

1.2 基本语法

ark schedule本身在 v0.4.0 中不接受位置参数，只提供帮助选项：

ark schedule

命令级唯一选项是：

-h, --help help for schedule

1.3 为什么需要 Schedule

在 Ark 的概念模型（concepts.md）中，Schedule 是三大操作类型之一。与一次性手动ark backup create不同，Schedule 允许你以固定的时间间隔自动执行备份：

• 首次创建 Schedule 时立即执行一次备份；
• 之后按照指定的间隔周期性地触发备份；
• 间隔由 Cron 表达式指定；
• Schedule 是 Backup 的包装器：被触发时，它在后台自动创建 Backup 对象；
• 由 Schedule 产生的备份命名格式为<SCHEDULE NAME>-<TIMESTAMP>，其中<TIMESTAMP>格式为YYYYMMDDhhmmss（如nginx-backup-20170727200524）。

这意味着 Schedule 非常适合灾备（DR）场景下"持续产生可恢复检查点"的需求，例如每天、每周固定时段备份整个集群或指定命名空间。

二、ark schedule create：创建定时备份计划

2.1 命令语法

ark schedule create NAME [flags]

create是三个子命令中参数最丰富的。下面按类别逐一解析 ark_schedule_create.md 中列出的全部选项。

2.2 定时触发参数

关于 cron 表达式的合法取值，当前仓库 pkg/cmd/cli/schedule/create.go 的Long帮助文本给出了权威的五字段定义（以 UTC 时间为准）：

除标准 cron 外，还支持@every <duration>语法，持续时间可由秒（s）、分（m）、时（h）自由组合，例如@every 2h30m。另外，validate逻辑在 create.go 中强制要求--schedule非空，否则直接报错--schedule is required。

常用示例：

# 每 6 小时备份一次 ark schedule create NAME --schedule="0 */6 * * *" # 使用 @every 语法，每 6 小时备份一次 ark schedule create NAME --schedule="@every 6h" # 每天备份 web 命名空间 ark schedule create NAME --schedule="@every 24h" --include-namespaces web # 每周备份一次，每次备份保留 90 天（2160 小时） ark schedule create NAME --schedule="@every 168h" --ttl 2160h0m0s

2.3 备份内容过滤参数

这部分参数决定"每次触发的备份究竟要打包哪些资源"，与ark backup create完全一致：

提示：--include-resources中的resource.group写法与 Kubernetes API 的资源分组一致。例如 Deployment 的 group 为apps，可写为deployments.apps。

2.4 备份行为参数

其中--ttl与"过期备份删除"机制直接相关：根据 concepts.md 的说明，当 Ark 发现某个 Backup 资源已过期（超过 TTL），会同时删除两样东西——Backup 资源本身以及对象存储中的实际备份文件。

--snapshot-volumes=false可关闭 PV 磁盘快照。当集群未配置云厂商快照能力（例如本地 Minio 演示环境）时，通常需要显式关闭该项。

2.5 输出显示参数

create命令也继承了get一类命令常用的显示控制参数，便于在不真正提交对象前先预览：

2.6 创建命令的底层实现

当前仓库中create的实现位于 pkg/cmd/cli/schedule/create.go。从源码可以看到，CLI 层做的核心工作是：把命令行参数组装成一个velerov1.ScheduleCRD 对象（api.Schedule），然后通过crClient.Create(context.TODO(), schedule)提交给 Kubernetes API Server。

关键的字段映射关系（Run函数）如下：

• schedule.Spec.Schedule←--schedule参数（cron 表达式字符串）；
• schedule.Spec.Template.IncludedNamespaces / ExcludedNamespaces / IncludedResources / ExcludedResources← 对应过滤参数；
• schedule.Spec.Template.LabelSelector←--selector；
• schedule.Spec.Template.SnapshotVolumes←--snapshot-volumes；
• schedule.Spec.Template.TTL←--ttl；
• schedule.Spec.Paused、schedule.Spec.UseOwnerReferencesInBackup← 后续版本新增的--paused、--use-owner-references-in-backup参数。

也就是说，Schedule 并不直接包含备份数据，而是内嵌一份完整的BackupSpec模板（Template字段），每次到点后用该模板去实例化一个真正的 Backup 对象。

三、ark schedule get：查看定时备份计划

3.1 命令语法

ark schedule get [flags]

3.2 命令选项

get命令默认以表格形式输出所有 Schedule，也支持-o json/-o yaml查看完整定义，便于排查 cron 表达式或 TTL 配置是否正确。

3.3 查看 Schedule 的生命周期阶段

从源码 pkg/apis/velero/v1/schedule_types.go 可以看到，每个 Schedule 都有独立的Phase字段，取值如下：

因此，用ark schedule get查询输出中的状态列，是确认"定时计划是否真正生效（Enabled）"或"是否因 cron 表达式非法而失败（FailedValidation）"的最直接手段。

四、ark schedule delete：删除定时备份计划

4.1 命令语法

ark schedule delete NAME [flags]

4.2 命令选项

delete在 v0.4.0 中仅有一个-h, --help选项。删除时需显式指定要删除的 Schedule 名称（即create时给定的NAME）。

删除 Schedule 后，其对应的周期性备份触发机制随即停止。需要说明的是：已经由该 Schedule 生成的、尚未过期的 Backup 对象不会自动随之删除（除非配置了 owner references 等后续机制），这与"备份数据以对象存储为唯一事实来源"的设计一致——已落盘的备份文件仍可通过ark restore使用。

五、所有子命令继承的全局选项

ark schedule的每个子命令都会从顶层ark命令继承一组全局选项（"Options inherited from parent commands"）。它们来自 Cobra 命令行框架与 glog 日志体系，在任何子命令后均可使用：

其中--kubeconfig的解析顺序，与 cli-reference/README.md 中描述的 Ark 客户端查找集群凭据的顺序一致：

1. --kubeconfig命令行标志；
2. $KUBECONFIG环境变量；
3. 集群内配置（仅当 Ark 以 Pod 形式运行在集群内时有效）。

建议在 bash 中使用官方推荐的容器化别名来运行ark，省去手工传递 kubeconfig 的麻烦（详见 cli-reference/README.md 中的alias ark='docker run --rm -u $(id -u) -v $(dirname $KUBECONFIG):/kubeconfig -e KUBECONFIG=/kubeconfig/$(basename $KUBECONFIG) gcr.io/heptio-images/ark:latest'）。

六、Schedule 的底层运行机制（源码视角）

6.1 Schedule 是 CRD + 控制器模式

在 v0.4.0 的架构说明（site/content/docs/v0.4.0/_index.md 的 Architecture 一节）中明确指出：Backups、Schedules、Restores 都是基于 CRD 定义的自定义资源，由各自的自定义控制器（custom controllers）负责处理。Ark 分为两种运行模式：

• Ark 客户端（CLI）：负责查询、创建、删除这些自定义资源；
• Ark 服务端：持续运行全部控制器，每个控制器监听对应的自定义资源、执行校验，并处理绝大部分云 API 逻辑（对接对象存储与 PV 快照）。

具体到ark schedule create NAME --schedule="..."，完整链路是：

1. CLI 构造ScheduleCRD 对象并提交到 Kubernetes API Server（存入 etcd）；
2. ScheduleController（pkg/controller/schedule_controller.go）监听到新 Schedule 并执行校验，用parseCronSchedule解析 cron 表达式；
3. 校验失败则把Status.Phase置为FailedValidation并记录ValidationErrors；
4. 校验通过则置为Enabled，控制器用ifDue判断是否到达触发时间，到点时调用submitBackup自动创建 Backup 对象；
5. 生成的备份按<SCHEDULE NAME>-<TIMESTAMP>命名，最终由BackupController完成资源打包上传与 PV 快照。

6.2 Schedule 的定义模型

当前仓库中 Schedule 的完整定义位于 pkg/apis/velero/v1/schedule_types.go。核心结构ScheduleSpec包含：

• Template BackupSpec：触发时用来创建 Backup 的模板（内嵌完整的备份规格）；
• Schedule string：cron 表达式，定义何时触发；
• UseOwnerReferencesInBackup *bool：是否给该 Schedule 创建的 Backup 添加 owner reference（启用后，删除 Schedule 会连带删除其产生的 Backup）；
• Paused bool：是否暂停；
• SkipImmediately *bool：是否跳过"新建或取消暂停后立即到期"的立即执行（留空则遵循服务端配置，默认 false）。

此外，ScheduleStatus中记录了Phase（生命周期阶段）与LastBackup（上次执行备份的时间），后者正是控制器判断"是否到点"的依据。

6.3 与一次性 Backup 的关系

总结一句话：Schedule 只是"定时生成 Backup"的触发器，真正的备份执行仍然走 Backup 链路。因此create命令中几乎所有的备份内容过滤、快照、TTL 参数，本质上都会被复制进Spec.Template，在每次触发时实例化为一次独立的 Backup。这也是为什么 ark_schedule_create.md 中这些参数与ark backup create的选项一一对应。

七、常见操作组合与排查建议

7.1 完整工作流示例

# 1. 创建一个每天凌晨 2 点（UTC）备份全部命名空间、保留 7 天的计划 ark schedule create daily-backup \ --schedule="0 2 * * *" \ --include-namespaces="*" \ --ttl 168h0m0s # 2. 查看计划是否创建成功、状态是否为 Enabled ark schedule get # 3. 以 yaml 形式查看某个计划的完整定义（确认 cron/TTL 配置） ark schedule get daily-backup -o yaml # 4. 不再需要时删除计划 ark schedule delete daily-backup

7.2 常见问题排查

• ark schedule get中状态为FailedValidation：说明 cron 表达式不符合五字段格式或取值越界（例如小时字段写成了 25），请对照 create.go 中的字段取值表检查表达式，然后删除并重新创建。
• 备份没有按预期触发：检查 Schedule 是否处于Enabled状态；同时注意 cron 表达式按UTC 时间计算，与本地时区可能有偏移。
• 首次创建后没有立即产生备份：正常行为下首次创建会立即执行一次备份，确认ark backup get中是否有daily-backup-<TIMESTAMP>形式的备份对象。
• 需要临时停止而非删除：当前仓库版本已提供velero schedule pause/unpause子命令（见 pkg/cmd/cli/schedule/pause.go、pkg/cmd/cli/schedule/unpause.go），其对应 v0.4.0 中的Paused字段语义，可以替代删除操作，保留计划配置以备将来复用。

八、延伸阅读

• 命令总览：ark.md、cli-reference/README.md
• Schedule 概念说明：concepts.md（"2. Schedules" 一节）
• 架构与 Quickstart：site/content/docs/v0.4.0/_index.md
• 当前实现源码：pkg/cmd/cli/schedule/schedule.go、pkg/cmd/cli/schedule/create.go、pkg/controller/schedule_controller.go、pkg/apis/velero/v1/schedule_types.go

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero