Velero 备份删除命令全解析:从 `ark backup delete` 到 `velero backup delete` 的 CLI 与底层实现
Velero 备份删除命令全解析:从 ark backup delete 到 velero backup delete 的 CLI 与底层实现
导读
本文围绕 Velero(及其前身 Heptio Ark)官方 CLI 参考文档 site/content/docs/v0.9.0/cli-reference/ark_backup_delete.md 展开,系统讲解备份删除命令 ark backup delete / velero backup delete 的完整语法、全部参数及其背后的一整套删除工作流。读完本文,你将掌握如何安全地删除单个或多个备份、如何使用 --confirm、--all、--selector 等关键标志,并能从源码层面理解删除请求(DeleteBackupRequest)如何被创建、校验与最终执行,具备排查删除失败问题的实战能力。
一、命令概述与历史沿革
Ark(Heptio Ark)是 Velero 的前身。在 v0.9.0 时代,备份删除命令写作 ark backup delete,其功能定义只有一句话:Delete a backup(删除一个备份)。随着项目从 Ark 更名为 Velero,该命令在后续版本中演变为 velero backup delete,命令语义、参数与底层流程保持一致,当前仓库源码位于 pkg/cmd/cli/backup/delete.go。
从源码看,命令的 Short 描述为 "Delete backups",完整命令定义通过 NewDeleteCommand(f client.Factory, use string) 构造,use 字段被格式化为 %s <a href="https://link.gitcode.com/i/76d2f1c4bfb8212d755aec068d3d8d5e" target="_blank">NAMES],即命令格式支持一次传入一个或多个备份名称。命令还注册了 shell 自动补全函数 cli.CompleteBackupNames(f)(见 [pkg/cmd/cli/backup/delete.go#L40-L71),便于交互式终端输入。
二、命令语法与核心选项
原文档给出的命令原型为:
ark backup delete NAME [flags]
对应现代 Velero 语法:
velero backup delete NAME [flags]
2.1 命令级选项(Options)
原文档列出的命令级选项如下:
--confirm Confirm deletion
-h, --help help for delete
| 选项 | 说明 |
|---|---|
--confirm |
跳过交互式确认,直接提交删除请求。不加该标志时,命令会先提示用户确认 |
-h, --help |
显示 delete 子命令的帮助信息 |
--confirm 标志由通用确认选项机制提供。在源码 pkg/cmd/util/confirm/confirm.go#L12-L28 中,ConfirmOptions 通过 flags.BoolVar(&o.Confirm, "confirm", o.Confirm, o.flagDescription) 绑定该标志,其中标志描述文本 "Confirm deletion" 正是由 NewDeleteOptions 通过 confirm.NewConfirmOptionsWithDescription("Confirm deletion") 注入的(见 pkg/cmd/cli/delete_options.go#L38-L43)。
当未指定 --confirm 时,命令会进入交互式确认流程。GetConfirmation 函数(pkg/cmd/util/confirm/confirm.go#L31-L56)会在终端打印 Are you sure you want to continue (Y/N)?,读取用户输入并循环等待,直到输入 y(返回 true,继续删除)或 n(返回 false,终止删除);如果输入内容不是单个字符或既非 y 也非 n,则重新提示。只有输入非法、读取失败(如 stdin 关闭)时才返回 false 并终止。
2.2 从父命令继承的选项(Options inherited from parent commands)
原文档完整列出了从 ark 父命令继承的全局选项,这些选项在现代 Velero 中同样存在:
--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
--kubecontext string The context to use to talk to the Kubernetes apiserver. If unset defaults to whatever your current-context is (kubectl config current-context)
--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
-n, --namespace string The namespace in which Ark should operate (default "heptio-ark")
--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 pattern=N settings for file-filtered logging
这些选项可归纳为三类:
-
集群连接类
--kubeconfig:指定用于访问 Kubernetes apiserver 的 kubeconfig 文件路径;未设置时依次尝试环境变量KUBECONFIG与集群内配置(in-cluster configuration)。--kubecontext:指定使用的 kubeconfig context,默认使用kubectl config current-context的当前上下文。-n, --namespace:Ark 操作所在的命名空间。v0.9.0 时代默认值为heptio-ark,这也正是当时 Ark 默认部署的命名空间;Velero 更名为后默认值为velero。源码中o.Namespace = f.Namespace()(pkg/cmd/cli/delete_options.go#L46-L54)即从工厂读取该值,后续所有备份查询与删除请求的创建都限定在该命名空间内。
-
日志类:
--alsologtostderr、--logtostderr、--log_dir、--log_backtrace_at、--stderrthreshold、-v/--v、--vmodule,用于控制 glog 风格的日志输出位置、级别与过滤规则。例如-v=4可输出更详细的调试日志,排查删除失败原因时可借助这些参数获取更完整的日志。
2.3 相关子命令
原文档 "SEE ALSO" 指向 ark backup,该父命令聚合了 ark backup create / delete / describe / download / get / logs 等一系列备份管理子命令,功能描述为 "Work with backups"。在现代 Velero 中,这些子命令依然对应存在(velero backup create / delete / describe / download / get / logs 等),分布在 pkg/cmd/cli/backup 目录下。
三、完整用法示例(来自源码 Example)
原文档未提供示例,但当前仓库源码 NewDeleteCommand 中内置了完整的命令示例(pkg/cmd/cli/backup/delete.go#L46-L59),这些示例在现代 Velero 中可直接使用,作为实战参考:
# 删除名为 "backup-1" 的单个备份(会提示确认)
velero backup delete backup-1
# 删除名为 "backup-1" 的备份,跳过确认提示
velero backup delete backup-1 --confirm
# 一次删除多个备份 "backup-1" 和 "backup-2"
velero backup delete backup-1 backup-2
# 删除由 schedule 名为 "schedule-1" 触发的所有备份
velero backup delete --selector velero.io/schedule-name=schedule-1
# 删除全部备份
velero backup delete --all
注意:--selector 与 --all 是源码中 SelectOptions 提供的增强选项,属于原文档发布之后逐步引入的能力。原文档 v0.9.0 版本只列了 --confirm 与 --help,因此使用前请确认你的 Velero 版本支持这些标志。
3.1 名称、选择器与全量的互斥校验
--selector、--all 与按名称删除三者之间是严格互斥的关系。该约束由通用选择选项 SelectOptions 的校验逻辑实现(pkg/cmd/cli/select_option.go#L53-L64):
if !xor(hasNames, hasAll, hasSelector) {
return errors.New("you must specify exactly one of: specific " + o.SingularTypeName + " name(s), the --all flag, or the --selector flag")
}
xor 函数(pkg/cmd/cli/delete_options.go#L73-L78)要求以上三种选择方式中恰好启用一种:要么给出具体的备份名称,要么使用 --all,要么使用 --selector。如果同时使用多种(例如既传名字又加 --all),或一种都没用,命令都会报错并拒绝执行。这一设计可以有效防止因误操作而误删数据。
3.2 选择器与标签
--selector 标志通过 flag.LabelSelector 类型绑定,支持标准的 Kubernetes 标签选择器语法(如 velero.io/schedule-name=schedule-1)。在 Run 函数中,o.Selector.LabelSelector 会被转换为 metav1.LabelSelectorAsSelector 后用于列表过滤(pkg/cmd/cli/backup/delete.go#L98-L116)。
需要说明的是,--all / --selector 标志在 select_option.go 中的通用实现为所有删除类命令(backup、restore、schedule 等)所共用,标志描述文本会根据命令类型动态生成(如 "Delete all backups" / "Delete all backups matching this label selector.")。
四、删除命令的执行流程(源码级解析)
velero backup delete 的执行入口位于 pkg/cmd/cli/backup/delete.go#L60-L71,依次执行 Complete → Validate → Run 三步:
- Complete:从客户端工厂填充命名空间与 Kubernetes 客户端(pkg/cmd/cli/delete_options.go#L46-L54)。
- Validate:校验客户端已就绪,并执行上文的名称/
--all/--selector互斥校验。 - Run:执行实际删除逻辑。
Run 函数(pkg/cmd/cli/backup/delete.go#L74-L159)的核心流程如下:
┌────────────────────────────────────────────────────┐
│ 1. 交互式确认(未指定 --confirm 时) │
│ 提示 "Are you sure you want to continue (Y/N)?"│
└───────────────────────┬────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 2. 确定待删除备份集合 │
│ - 按名称:逐个 Get Backup 资源 │
│ - 按 --selector:List 匹配标签的 Backup │
│ - 按 --all:List 全部 Backup │
└───────────────────────┬────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 3. 对每个备份做前置检查 │
│ - 必须设置 Spec.StorageLocation │
│ - 对应 BackupStorageLocation 必须存在 │
│ - 存储位置不得为 read-only 模式 │
└───────────────────────┬────────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ 4. 为每个备份创建 DeleteBackupRequest 对象 │
│ 并打印 "Request to delete backup %q submitted" │
└────────────────────────────────────────────────────┘
4.1 步骤一:交互式确认
if !o.Confirm && !confirm.GetConfirmation() {
// Don't do anything unless we get confirmation
return nil
}
未指定 --confirm 且用户输入不是 y 时,命令直接返回、不执行任何删除操作。
4.2 步骤二:确定待删除备份
- 指定名称时:逐个调用
o.Client.Get获取velerov1api.Backup,单个获取失败只记录错误并继续处理其他名称,不中断整体流程。 - 使用
--all或--selector时:构造labels.Everything()或转换后的标签选择器,调用o.Client.List获取备份列表;默认--selector为空时选择所有备份。 - 若最终待删除集合为空,打印
No backups found并正常退出(返回 nil,不视为错误)。
4.3 步骤三:删除前置条件检查
这是防止误删的重要防线,对应源码 pkg/cmd/cli/backup/delete.go#L124-L145:
- 备份必须关联存储位置:
b.Spec.StorageLocation为空时报错cannot delete backup %q because it does not have a backup storage location set,跳过该备份。 - 存储位置必须存在:按名称获取
BackupStorageLocation,失败则记录错误。 - 存储位置不得为只读:若
location.Spec.AccessMode == BackupStorageLocationAccessModeReadOnly,报错cannot delete backup %q because backup storage location %q is currently in read-only mode。这是对只读 BSL 的硬性保护——只读模式下对象存储上的数据不允许任何修改,因此删除请求会被直接拒绝。
存储位置查询使用了一个按名称缓存的 bslCache map,避免对多个备份重复查询同一个 BSL。
4.4 步骤四:创建 DeleteBackupRequest
前置检查通过后,命令并不直接删除任何数据,而是为每个备份创建一个 DeleteBackupRequest 定制资源对象(pkg/cmd/cli/backup/delete.go#L147-L156):
deleteRequest := builder.ForDeleteBackupRequest(o.Namespace, "").
BackupName(b.Name).
ObjectMeta(builder.WithLabels(
velerov1api.BackupNameLabel, label.GetValidName(b.Name),
velerov1api.BackupUIDLabel, string(b.UID),
), builder.WithGenerateName(b.Name+"-")).Result()
if err := client.CreateRetryGenerateName(o.Client, context.TODO(), deleteRequest); err != nil {
errs = append(errs, err)
continue
}
fmt.Printf("Request to delete backup %q submitted successfully.\nThe backup will be fully deleted after all associated data (disk snapshots, backup files, restores) are removed.\n", b.Name)
关键设计点:
- 删除是异步的:CLI 只负责提交删除请求并打印
Request to delete backup %q submitted successfully.,真正的数据清理(磁盘快照、备份文件、相关 restore 等)由服务端的备份删除控制器异步完成。因此输出中特别说明 "The backup will be fully deleted after all associated data (disk snapshots, backup files, restores) are removed." - 名称生成:请求对象使用
WithGenerateName(b.Name + "-"),让 Kubernetes apiserver 自动生成唯一名称;CreateRetryGenerateName会在名称冲突时自动重试。 - 标签绑定:请求上打有
velero.io/backup-name与velero.io/backup-uid两个标签(BackupNameLabel/BackupUIDLabel),用于精确关联目标备份。
五、服务端如何真正执行删除(备份删除控制器)
CLI 提交的 DeleteBackupRequest 由备份删除控制器消费,其实现位于 pkg/controller/backup_deletion_controller.go。控制器通过 For(&velerov1api.DeleteBackupRequest{}) 监听该资源,并周期性地(每小时一次)重新入队检查(pkg/controller/backup_deletion_controller.go#L109-L113)。
Reconcile 主流程(pkg/controller/backup_deletion_controller.go#L122 起)与 CLI 侧形成"双重校验":
- 请求清理:已处于
Processed或InProgress状态的请求若超过deleteBackupRequestMaxAge(24 小时)会被自动删除,避免请求对象无限堆积(pkg/controller/backup_deletion_controller.go#L140-L146)。 - 参数校验:
spec.backupName为空则标记错误。 - 备份状态检查:备份仍在进行中(in progress)时拒绝删除并报错
backup is still in progress,避免删除正在创建的备份。 - 备份存在性检查:备份不存在时报错
backup not found。 - 存储位置检查:BSL 不存在、处于只读(read-only)模式或
Unavailable状态时均拒绝删除——与 CLI 侧的只读检查互为补充,形成服务端兜底保护。 - 执行删除:通过后将请求状态置为
InProgress(DeleteBackupRequestPhaseInProgress),然后从备份存储中删除备份文件、磁盘快照与相关 restore 数据,完成后将请求状态置为Processed。
因此,当你看到 CLI 返回 "submitted successfully" 后,需要通过 velero backup get 观察备份最终状态,或通过 kubectl get deletebackuprequest -n velero 查看删除请求的 Phase,才能确认数据是否真正清理完毕。
六、测试用例验证(源码依据)
仓库为删除命令提供了完备的单元测试,可作为行为契约的权威依据:
- pkg/cmd/cli/backup/delete_test.go#L38-L85(
TestDeleteCommand):在 fake client 中预置backup-name-1(默认命名空间)与backup-name-2(命名空间default),验证--confirm标志解析、Complete/Validate/Run全链路可正常执行;同时验证不存在命名空间的备份会得到 "not found" 提示。 - pkg/cmd/cli/backup/delete_test.go#L87-L115(
TestDeleteCommandReadOnlyBSL):创建AccessMode为只读的 BSL,验证删除被拒绝并返回 "cannot delete backup ... because backup storage location ... is currently in read-only mode" 错误,且最终没有任何DeleteBackupRequest被创建——从测试层面确认了只读 BSL 的硬保护逻辑。
七、实战注意事项
- 确认机制:生产环境中建议始终显式传入
--confirm并结合脚本/CI 审计,避免交互式终端在自动化场景下挂起;手工操作时则故意省略--confirm,给自己多一次确认机会。 - 删除是异步的:
velero backup delete只提交请求,实际清理由服务端控制器完成。删除大备份可能耗时较长,应通过velero backup get或DeleteBackupRequest的 Phase 确认最终结果。 - 只读 BSL 保护:如果备份的存储位置被配置为
ReadOnly访问模式,无论 CLI 还是控制器都会拒绝删除。这是有意为之的数据保护设计——需要删除时请先将 BSL 访问模式改回读写。 - 范围互斥:名称、
--all、--selector三者只能取其一;--all会删除命名空间内全部备份,使用前务必确认范围。 - 版本差异:原文档基于 v0.9.0(Ark 时代),默认命名空间为
heptio-ark,命令名为ark;当前 Velero 版本默认命名空间为velero,命令名为velero,且新增了--all、--selector等增强选项,请以实际安装版本为准。
总结
ark backup delete / velero backup delete 是 Velero 备份生命周期管理的核心命令之一。它通过"CLI 提交异步删除请求 + 控制器执行实际清理"的两段式架构,将数据删除的确认、校验与执行分离,配合 --confirm 交互确认、只读 BSL 保护、名称/选择器/全量互斥校验等多重安全机制,在易用性与数据安全之间取得了良好平衡。理解其参数语义与底层 DeleteBackupRequest 工作流,将帮助你在日常备份治理与故障排查中更加从容。