Velero CLI 备份删除命令完全指南:`velero backup delete` 的用法、参数与源码解析
Velero CLI 备份删除命令完全指南:velero backup delete 的用法、参数与源码解析
导读
本文围绕 Velero(早期名为 Ark)CLI 中的 velero backup delete(旧版本为 ark backup delete)命令展开,系统讲解如何安全、批量地删除 Kubernetes 集群备份及其关联的对象存储数据。读完本文,你将掌握该命令的完整语法、全部可用参数、命名行删除 / 标签选择器批量删除 / 全量删除三种典型用法,以及删除确认机制、只读存储位置保护、异步删除请求(DeleteBackupRequest)等底层实现原理,并能够结合源码定位命令处理链路。
一、命令概览:Delete a backup
velero backup delete 命令的作用是删除一个备份(Delete a backup),它属于 velero backup 命令族的子命令。在历史版本(v0.7.x 时代,项目名为 Ark)中,该命令名为 ark backup delete;当前仓库中命令名已演进为 velero backup delete,但其命令行语义与 v0.7.1 文档保持一致。
从当前仓库的 CLI 定义看,该子命令注册于 pkg/cmd/cli/backup/delete.go,其 Short 描述为 "Delete backups",并内置了多个可直接参考的示例(Example):
# 删除名为 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-1 定时计划触发的所有备份
velero backup delete --selector velero.io/schedule-name=schedule-1
# 删除所有备份
velero backup delete --all
1.1 基本语法
velero backup delete NAME [flags]
即:velero backup delete <备份名称>,后跟若干可选 flag。
二、完整参数说明
2.1 命令自身选项
v0.7.1 文档中,该命令自身的选项只有一个:
-h, --help help for delete
即 -h/--help 用于查看帮助信息。随着命令演进,当前版本的命令还通过 DeleteOptions 绑定了两组对实际删除操作至关重要的 flag:
确认类(继承自 pkg/cmd/util/confirm/confirm.go)
| Flag | 类型 | 说明 |
|---|---|---|
--confirm |
bool | 跳过交互式确认提示,直接执行删除 |
选择类(继承自 pkg/cmd/cli/select_option.go)
| Flag | 缩写 | 类型 | 说明 |
|---|---|---|---|
--all |
无 | bool | 删除所有备份 |
--selector |
-l |
string | 只删除匹配该标签选择器的备份 |
注意:这三类选择方式(指定名称、
--all、--selector)是互斥的,必须且只能指定其中一种,否则命令校验会直接报错(详见下文源码解析)。
2.2 继承自父命令的全局选项
ark backup delete 同样继承 ark 父命令的全部全局参数,用于配置 Kubernetes 连接与日志输出:
--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
-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)。CLI 侧可参考 pkg/client/config.go 的配置解析实现。-n, --namespace:Velero 操作所在的命名空间,默认值为heptio-ark(当前版本默认命名空间为velero)。备份资源与备份存储位置(BackupStorageLocation)都从该命名空间读取。--logtostderr/--log_dir/-v等:标准 glog 风格日志参数,用于控制日志输出位置与详细级别。
三、典型使用场景与操作步骤
3.1 删除单个备份
velero backup delete my-backup
执行后 CLI 会首先通过 confirm.GetConfirmation() 交互式地向终端输出确认提示:
Are you sure you want to continue (Y/N)?
输入 Y 后,命令才会真正发起删除请求;输入 N 则直接中止,不会产生任何副作用。交互逻辑定义在 pkg/cmd/util/confirm/confirm.go,它从标准输入读取单字符并循环校验,只接受 y/Y 与 n/N。
3.2 非交互式删除(脚本中使用)
velero backup delete my-backup --confirm
--confirm 直接跳过确认环节,适用于 CI/CD 流水线或脚本自动化场景。
3.3 批量删除多个备份
velero backup delete backup-1 backup-2
命令依次对每个名称执行查找与删除请求,某个名称不存在不会阻塞其他备份的删除,而是会收集错误并在最终统一返回(详见源码解析)。
3.4 按标签选择器批量删除
velero backup delete --selector velero.io/schedule-name=schedule-1
删除所有由 schedule-1 这个定时计划创建出的备份。Velero 在创建计划触发的备份时,会打上 velero.io/schedule-name 标签,因此可以用该选择器精准圈定删除范围。选择器语法遵循 Kubernetes LabelSelector 规范,相关实现可参考 pkg/cmd/util/flag 下的标签选择器类型。
3.5 删除全部备份
velero backup delete --all
删除当前命名空间下的全部备份。该操作影响范围大,务必在确认后再执行。
四、源码级解析:命令内部到底做了什么
下面结合当前仓库源码,剖析 velero backup delete 的完整执行链路。
4.1 命令组装与执行入口
在 pkg/cmd/cli/backup/delete.go 中,Run 函数被依次调用三个步骤:
cmd.CheckError(o.Complete(f, args))
cmd.CheckError(o.Validate(c, f, args))
cmd.CheckError(Run(o))
Complete:填充命名空间、构造 Kubernetes client,并把命令行参数解析为待删除的备份名称列表,见 pkg/cmd/cli/delete_options.go。Validate:进行互斥校验,见下节。Run:真正的删除逻辑。
4.2 互斥校验规则
Validate 最终落到 pkg/cmd/cli/select_option.go:
if !xor(hasNames, hasAll, hasSelector) {
return errors.New("you must specify exactly one of: specific backup name(s), the --all flag, or the --selector flag")
}
即:指定备份名称、--all、--selector 三选一,多选或全不选都会直接报错。这与 --selector 与 --all 之间的语义冲突保护机制一致——如果既传了名称又传了 --all,命令会拒绝执行,避免产生歧义。
4.3 确认与备份筛选逻辑
Run 的第一步是确认(若未指定 --confirm):
if !o.Confirm && !confirm.GetConfirmation() {
return nil
}
然后根据选择方式筛选目标备份(pkg/cmd/cli/backup/delete.go):
- 有名称列表:逐个
Get备份对象;取不到的错误会被收集到errs中继续处理其他名称。 - 无名称:构造 LabelSelector,
List出所有匹配备份;--all场景下 selector 为空,等价于labels.Everything()。
若筛选结果为空,命令输出 No backups found 并正常返回,不会报错。
4.4 逐备份校验存储位置并创建删除请求
这是删除命令的核心。对每个备份,pkg/cmd/cli/backup/delete.go 会执行以下检查与动作:
- 读取备份的 StorageLocation:若
b.Spec.StorageLocation为空,直接报错 "cannot delete backup ... because it does not have a backup storage location set"。 - 读取对应的 BackupStorageLocation 并缓存(
bslCache),避免重复查询。 - 只读模式保护:若该存储位置处于
ReadOnly访问模式,则拒绝删除并报错。测试用例 pkg/cmd/cli/backup/delete_test.go 专门验证了这一行为:当 BSL 为只读时,删除失败且不会产生任何 DeleteBackupRequest。 - 创建 DeleteBackupRequest:为每个备份生成一个
DeleteBackupRequest对象,标签包含备份名与备份 UID(velero.io/backup-name、velero.io/backup-uid),名称采用备份名-前缀 + 自动生成后缀(WithGenerateName)。 - 提交请求:通过
client.CreateRetryGenerateName发送到 apiserver,成功后输出提示信息,说明备份的完整删除将在所有关联数据(磁盘快照、备份文件、恢复记录)都被清理后完成:
Request to delete backup "my-backup" submitted successfully.
The backup will be fully deleted after all associated data (disk snapshots, backup files, restores) are removed.
这里揭示了 Velero 删除模型的关键设计:
velero backup delete命令不是直接删除对象存储中的数据,而是创建一个 DeleteBackupRequest 自定义资源。后续由 backup_deletion_controller.go 等控制器异步消费该请求,统一协调删除备份 CR 本身、备份文件(对象存储)、磁盘快照(云厂商快照)与关联的恢复记录。这意味着删除是"异步、渐进、幂等"的,命令返回不代表数据即刻消失。
4.5 错误聚合
多个备份删除过程中收集到的错误在最后通过 kubeerrs.NewAggregate(errs) 统一返回,便于用户一次看到所有失败项,而不是遇到一个错误就中断全部操作。
五、与删除相关的其他资源
- 父命令与兄弟命令:查看 ark_backup.md,
ark backup下还有create、describe、download、get、logs等子命令,覆盖备份的完整生命周期。删除前建议先用ark backup get(见 ark_backup_get.md)确认目标备份名称。 - 删除请求 CRD 定义:DeleteBackupRequest 的 API 类型定义于 pkg/apis/velero/v1,可通过
kubectl get deletebackuprequests -n velero查看命令提交的删除请求状态。 - 底层删除动作:对象存储与快照的物理清理逻辑可参考 pkg/backup/delete_helpers.go 以及 delete 相关的 item action 实现。
六、注意事项与最佳实践
- 删除是不可逆操作:一旦备份的关联数据(磁盘快照、备份文件)被清除,将无法恢复该备份。执行前建议先用
velero backup describe或get确认目标。 - 确认机制保护:交互式环境下命令默认要求
Y/N确认,自动化场景务必显式添加--confirm,否则命令会阻塞等待标准输入。 - 只读存储位置是硬性保护:当备份所在 BackupStorageLocation 被设置为只读访问模式时,删除命令会拒绝执行并报错——这是防止误删只读归档数据的最后一道防线,测试见 pkg/cmd/cli/backup/delete_test.go。
- 三选一约束:备份名称、
--all、--selector不能混用,否则命令校验失败。 - 删除是异步的:命令成功仅代表 DeleteBackupRequest 已提交;真正清理对象存储与快照由后台控制器完成,可通过监控 DeleteBackupRequest 的状态确认最终完成情况。