Velero `ark delete` 命令详解:删除备份、恢复与调度任务的操作指南

原创2026-09-16 20:28:401,367 阅读
文章标签:云原生容器编排灾备存储备份恢复CLI运维高可用

Velero ark delete 命令详解:删除备份、恢复与调度任务的操作指南

本文基于 Velero(原 Heptio Ark)v0.8.1 版本的 CLI 参考文档编写。ark delete 是 Ark 中负责删除集群备份相关资源的命令族,本文完整覆盖其全部子命令(backup、restore、schedule)的语法、参数与运行机制,并结合当前仓库源码(pkg/cmd/cli/delete/delete.go 等)说明命令的实际执行流程与注意事项。读完本文,你将能够熟练使用 ark delete 系列命令安全地清理集群中的备份、恢复记录与定时调度,并理解其删除确认机制、finalizer 工作原理及删除失败的排查思路。

一、命令概览:ark delete 是什么

ark delete 是 Ark 命令行工具中负责"删除 Ark 资源"的命令族(parent command),其定位与功能可从 v0.8.1 官方 CLI 文档中直接确认:

  • Synopsis(命令摘要):Delete ark resources,即"删除 Ark 资源"。
  • 自身参数:ark delete 本身仅接受一个全局 help 参数 -h, --help,不直接执行任何删除动作,真正的删除逻辑全部由它的子命令承担。

从当前仓库源码结构看,Ark(即 Velero 前身)的删除命令体系在 pkg/cmd/cli/delete/delete.go 中定义。NewCommand(f client.Factory) 函数注册了以下子命令(参见 delete.go):

子命令 实现来源 别名(Aliases)
ark delete backup backup.NewDeleteCommand(f, "backup") backups
ark delete backup-location backuplocation.NewDeleteCommand(f, "backup-location") backup-locations
ark delete restore restore.NewDeleteCommand(f, "restore") restores
ark delete schedule schedule.NewDeleteCommand(f, "schedule") schedules

说明:v0.8.1 文档中的 ark delete 页面仅列出 backup、restore、schedule 三个 SEE ALSO 链接,而 backup-location 是在后续版本中新增的能力。当前仓库源码(v1.x 时代)已包含 backup-location 删除,本文以 v0.8.1 文档为准重点讲解前三个,同时依据源码补充说明完整子命令族。

二、三个删除子命令的完整语法与参数

2.1 ark delete backup NAME [flags] — 删除备份

文档中的完整定义:

ark delete backup NAME [flags]
参数/选项 类型 说明
NAME 位置参数 要删除的备份名称
--confirm 布尔 跳过交互式确认提示,直接执行删除
-h, --help 布尔 查看该子命令帮助

2.2 ark delete restore NAME [flags] — 删除恢复记录

ark delete restore NAME [flags]

该子命令仅接受位置参数 NAME(恢复记录名称)与 -h, --help,无额外专属选项。删除的是恢复操作在集群中留下的记录(Restore 对象本身),不会影响已经恢复出来的应用资源。

2.3 ark delete schedule NAME [flags] — 删除定时调度

ark delete schedule NAME [flags]

同样仅接受位置参数 NAME(调度名称)与 -h, --help。删除 schedule 后,该调度将不再触发新的备份,但已由它产生的历史备份不会被自动删除——如需清理历史备份,需要另行执行 ark delete backup(参见 ark_delete_backup.md)。

2.4 父命令继承的全局参数(三命令通用)

三个子命令均继承 ark delete 父命令的全局参数,完整列表如下(出自 ark_delete.md):

参数 类型 默认值 说明
--alsologtostderr 布尔 false 同时将日志输出到标准错误与日志文件
--kubeconfig string 字符串 无 kubeconfig 文件路径,用于连接 Kubernetes apiserver;未设置时依次尝试环境变量 KUBECONFIG 与集群内配置(in-cluster configuration)
--kubecontext string 字符串 当前 context 指定 kubectl context;默认使用 kubectl config current-context 的当前上下文
--log_backtrace_at traceLocation 字符串 :0 当日志命中 file:N 行时输出堆栈跟踪
--log_dir string 字符串 空 非空时在该目录写入日志文件
--logtostderr 布尔 false 日志输出到标准错误而非文件
-n, --namespace string 字符串 heptio-ark Ark 操作的命名空间(注意:这是 Ark 早期版本的默认命名空间,后续 Velero 版本已改为 velero)
--stderrthreshold severity 字符串 2(ERROR) 达到或超过该严重级别的日志同时输出到 stderr
-v, --v Level 整数 0 V 日志的详细级别
--vmodule moduleSpec 字符串 空 按 pattern=N 逗号分隔列表,对特定文件过滤日志级别

三、命令执行流程与确认机制(源码级)

v0.8.1 文档只给出了命令语法,这里结合当前仓库源码补充其底层执行逻辑,帮助你理解 --confirm 与 -n 参数的实际作用。

3.1 统一的 DeleteOptions 骨架

ark delete 家族的三个子命令共享同一套参数结构 DeleteOptions(定义于 delete_options.go):

type DeleteOptions struct {
    *SelectOptions          // 支持按名称/标签选择器/--all 批量选择
    confirm.ConfirmOptions  // 提供 --confirm 参数与交互确认逻辑
    Client    controllerclient.Client
    Namespace string        // 由 -n/--namespace 指定
}

Complete 阶段会将 -n 指定的命名空间写入 o.Namespace,并通过 f.KubebuilderClient() 初始化 controller-runtime 客户端,后续所有删除操作都在该命名空间内进行。

3.2 删除前的交互确认

以 ark delete backup 的 Run 函数(pkg/cmd/cli/backup/delete.go)为例,删除动作的第一步是确认:

if !o.Confirm && !confirm.GetConfirmation() {
    // Don't do anything unless we get confirmation
    return nil
}

也就是说:除非显式传入 --confirm,否则命令会先在终端弹出交互式确认(提示输入 y/yes 确认),用户不确认则直接返回、不执行任何删除。这一设计是为了防止误删备份数据。

3.3 备份删除的对象选择与批量能力

虽然 v0.8.1 文档只写了 ark delete backup NAME 的单备份用法,但从当前源码(pkg/cmd/cli/backup/delete.go)可以看出,命令内部实际支持三种选择方式:

  • 显式指定一个或多个名称:ark delete backup backup-1 backup-2
  • 按标签选择器:ark delete backup --selector velero.io/schedule-name=schedule-1(删除某调度产生的全部备份)
  • 全部删除:ark delete backup --all

源码中对应的执行逻辑是:当 len(o.Names) > 0 时逐个 Client.Get 指定备份;否则按选择器 Client.List 拉取备份列表。

3.4 删除前的安全校验:备份存储位置必须可写

源码 pkg/cmd/cli/backup/delete.go 在发起删除请求前还会做一项重要校验:获取备份所属的 BackupStorageLocation,若其 AccessMode 为 ReadOnly,则拒绝删除该备份并报错:

cannot delete backup "xxx" because backup storage location "yyy" is currently in read-only mode

同时,若备份未设置 Spec.StorageLocation,同样会拒绝删除。这是为了防止在只读归档场景下误删数据。

3.5 备份删除是异步的:DeleteBackupRequest 机制

值得强调的是,ark delete backup 并不是立即删除备份对象本身,而是提交一个"删除请求"。源码 pkg/cmd/cli/backup/delete.go 通过 builder.ForDeleteBackupRequest 创建一个 DeleteBackupRequest 对象(带上备份名称、UID 标签,并使用 GenerateName 命名),随后打印提示:

Request to delete backup "xxx" submitted successfully.
The backup will be fully deleted after all associated data (disk snapshots, backup files, restores) are removed.

这意味着:真正的删除(包括云端快照、对象存储中的备份文件等关联数据)由 Ark 服务端的 backup deletion controller 异步完成。DeleteBackupRequest 的类型定义可在 pkg/apis/velero/v1/delete_backup_request_types.go 中查看,其生命周期阶段包括 New → InProgress → Processed。

四、备份删除的底层原理:finalizer 与常见故障排查

v0.8.1 文档配套的 debugging-deletes.md 详细解释了删除备份的实现原理与一个典型故障,这里完整保留并整理:

4.1 为什么删除备份会"卡住":finalizer 机制

Ark 通过为每个备份对象添加 finalizer 来实现删除能力。Kubernetes 的删除语义如下:

  • 当对象带有 finalizer 时,请求删除只会为对象打上 deletionTimestamp(标记删除),不会立即删除;
  • 只有当对象的 finalizer 全部被移除后,对象才会被真正删除;
  • 因此必须由某个组件——在 Ark 中即 Ark server——处理该备份并移除 Ark 的 finalizer,删除才算完成。

4.2 已知问题:删除 heptio-ark 命名空间导致备份卡死(v0.7.0)

v0.7.0 引入了备份删除能力,但存在一个已知问题:如果直接删除 heptio-ark 命名空间,该命名空间可能卡在 terminating(终止中)状态,且备份无法删除。原因在于:

  • v0.7.1 之前的版本,Ark server Pod 与备份、恢复、调度、配置对象位于同一个命名空间;
  • kubectl delete namespace/heptio-ark 时,对象删除顺序是任意的,Ark server Pod 可能在备份之前被删除;
  • 备份的 finalizer 失去处理者,于是备份永远卡在 deleting 状态。

4.3 修复方法:手动移除 finalizer

遇到该问题时,可按如下步骤修复(需要先安装 jq):

bash <(kubectl -n heptio-ark get backup -o json | jq -c -r $'.items[] | "kubectl -n heptio-ark patch backup/" + .metadata.name + " -p \'" + (({metadata: {finalizers: ( (.metadata.finalizers // []) - ["gc.ark.heptio.com"]), resourceVersion: .metadata.resourceVersion}}) | tostring) + "\' --type=merge"')

该命令会先列出所有备份,然后为每个备份生成并执行类似如下的 patch 命令,从 metadata.finalizers 中移除 gc.ark.heptio.com:

kubectl -n heptio-ark patch backup/my-backup -p '{"metadata":{"finalizers":[],"resourceVersion":"461343"}}' --type=merge
kubectl -n heptio-ark patch backup/some-other-backup -p '{"metadata":{"finalizers":[],"resourceVersion":"461718"}}' --type=merge

如果 patch 时报错"patching backups is not allowed",则说明 Ark 的 CustomResourceDefinitions(CRDs)可能已被删除,需要先用 examples/common/00-prereqs.yaml 重建 CRD,再执行上述步骤。

4.4 规避建议(v0.7.1 及以后)

v0.7.1 起,Ark 默认配置将 Ark server 运行在与备份、调度、恢复、配置对象不同的命名空间。官方文档强烈建议保持这一配置,这有助于避免删除操作引发的上述问题。

五、当前仓库中的演进:从 ark 到 velero

作为补充背景,当前仓库中 Ark 命令体系已演进为 Velero(velero 命令),删除命令族对应关系如下:

v0.8.1(Ark) 当前仓库(Velero)
ark delete backup velero backup delete
ark delete restore velero restore delete
ark delete schedule velero schedule delete
ark delete backup-location(v0.9+) velero backup-location delete

当前仓库 pkg/cmd/cli/delete/delete.go 即 Velero 版删除命令族定义。velero backup delete 的完整用法示例(pkg/cmd/cli/backup/delete.go)包括:

# 删除名为 backup-1 的备份
velero backup delete backup-1

# 跳过交互确认直接删除
velero backup delete backup-1 --confirm

# 一次删除多个备份
velero backup delete backup-1 backup-2

# 删除 schedule-1 触发的所有备份
velero backup delete --selector velero.io/schedule-name=schedule-1

# 删除全部备份
velero backup delete --all

velero restore delete、velero schedule delete 的用法与之类似,同样支持 --confirm、--selector、--all 等选项。

六、常见问题速查(FAQ)

Q1:ark delete backup 执行后备份立即消失吗? 不会。命令只是提交了 DeleteBackupRequest,实际删除由服务端 controller 异步完成,删除内容包括磁盘快照、备份文件与关联的恢复记录。

Q2:删除 schedule 会自动删除它产生的备份吗? 不会。删除 schedule 只停止未来触发的备份,历史备份需另行使用 ark delete backup 清理。

Q3:为什么删除备份前需要确认? 命令默认启用交互式确认,仅当传入 --confirm 时才跳过(源码见 pkg/cmd/cli/backup/delete.go)。这是防止误删的保护机制。

Q4:备份删除卡在 terminating 怎么办? 参照本文第四章:先确认 Ark server 是否仍在运行;若 CRD 仍在,可通过 kubectl patch 移除备份对象的 gc.ark.heptio.com finalizer 强制完成删除。

Q5:--namespace 默认值是什么? v0.8.1 中默认 heptio-ark;在后续 Velero 版本中默认值已改为 velero,请以实际使用的版本为准。

七、总结

ark delete 是 Ark/Velero 中负责清理备份、恢复与调度资源的核心命令族。本文完整覆盖了 v0.8.1 文档中的三个子命令(backup、restore、schedule)及其全部参数,并结合当前仓库源码补充了删除确认机制、只读存储位置校验、DeleteBackupRequest 异步删除模型以及 finalizer 引发的删除卡死问题与修复方案。掌握这些内容后,你可以在实际集群中安全、可控地完成 Ark/Velero 资源的删除操作,并在异常场景下快速定位问题。

参考资料(仓库内)

登录后查看全文
velero