Velero 备份删除命令全解析:从 `ark backup delete` 到 `velero backup delete` 的 CLI 与底层实现

原创2026-09-16 15:28:291,666 阅读
文章标签:云原生容器编排灾备存储备份恢复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

这些选项可归纳为三类:

  1. 集群连接类

    • --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)即从工厂读取该值,后续所有备份查询与删除请求的创建都限定在该命名空间内。
  2. 日志类:--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 三步:

  1. Complete:从客户端工厂填充命名空间与 Kubernetes 客户端(pkg/cmd/cli/delete_options.go#L46-L54)。
  2. Validate:校验客户端已就绪,并执行上文的名称/--all/--selector 互斥校验。
  3. 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 侧形成"双重校验":

  1. 请求清理:已处于 Processed 或 InProgress 状态的请求若超过 deleteBackupRequestMaxAge(24 小时)会被自动删除,避免请求对象无限堆积(pkg/controller/backup_deletion_controller.go#L140-L146)。
  2. 参数校验:spec.backupName 为空则标记错误。
  3. 备份状态检查:备份仍在进行中(in progress)时拒绝删除并报错 backup is still in progress,避免删除正在创建的备份。
  4. 备份存在性检查:备份不存在时报错 backup not found。
  5. 存储位置检查:BSL 不存在、处于只读(read-only)模式或 Unavailable 状态时均拒绝删除——与 CLI 侧的只读检查互为补充,形成服务端兜底保护。
  6. 执行删除:通过后将请求状态置为 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 的硬保护逻辑。

七、实战注意事项

  1. 确认机制:生产环境中建议始终显式传入 --confirm 并结合脚本/CI 审计,避免交互式终端在自动化场景下挂起;手工操作时则故意省略 --confirm,给自己多一次确认机会。
  2. 删除是异步的:velero backup delete 只提交请求,实际清理由服务端控制器完成。删除大备份可能耗时较长,应通过 velero backup get 或 DeleteBackupRequest 的 Phase 确认最终结果。
  3. 只读 BSL 保护:如果备份的存储位置被配置为 ReadOnly 访问模式,无论 CLI 还是控制器都会拒绝删除。这是有意为之的数据保护设计——需要删除时请先将 BSL 访问模式改回读写。
  4. 范围互斥:名称、--all、--selector 三者只能取其一;--all 会删除命名空间内全部备份,使用前务必确认范围。
  5. 版本差异:原文档基于 v0.9.0(Ark 时代),默认命名空间为 heptio-ark,命令名为 ark;当前 Velero 版本默认命名空间为 velero,命令名为 velero,且新增了 --all、--selector 等增强选项,请以实际安装版本为准。

总结

ark backup delete / velero backup delete 是 Velero 备份生命周期管理的核心命令之一。它通过"CLI 提交异步删除请求 + 控制器执行实际清理"的两段式架构,将数据删除的确认、校验与执行分离,配合 --confirm 交互确认、只读 BSL 保护、名称/选择器/全量互斥校验等多重安全机制,在易用性与数据安全之间取得了良好平衡。理解其参数语义与底层 DeleteBackupRequest 工作流,将帮助你在日常备份治理与故障排查中更加从容。

登录后查看全文
velero