Velero（Ark）`ark create restore` 命令详解：从备份创建 Kubernetes 恢复任务

Velero（Ark）ark create restore命令详解：从备份创建 Kubernetes 恢复任务

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

本文是一份面向 Ark/Velero 用户与开发者的命令参考指南，以仓库中 v0.7.1 时代的官方 CLI 参考文档 ark_create_restore.md 为骨架，逐一拆解ark create restore的语法、全部参数、全局继承参数及其在源码中的真实实现。读完本文，你将能够熟练使用该命令创建恢复任务，理解每个过滤、映射与卷恢复参数的语义边界，并掌握命令背后从 CLI 参数到Restore自定义资源（CRD）对象的完整落盘链路。

背景说明：Ark 是 Velero 的前身项目名称，v0.7.1 时期 CLI 使用ark前缀，默认命名空间为heptio-ark。在当前的仓库主干中，同一命令已演变为velero restore create，本文在完整保留 v0.7.1 文档原貌的基础上，结合主干源码 pkg/cmd/cli/restore/create.go 与 API 类型定义 restore_types.go 进行对照解读，帮助读者同时理解历史命令与当代实现的对应关系。

一、命令概览：创建一个恢复（Restore）任务

v0.7.1 参考文档给出的命令声明（Synopsis）非常简单直白：

ark create restore BACKUP [flags]

它表示：基于指定的备份（BACKUP）创建一个恢复任务。恢复任务在 Ark/Velero 中对应一个名为Restore的自定义资源对象，命令本身只是把用户的意图序列化为该对象并提交给 Kubernetes API Server，真正的恢复工作由 Velero 服务端（restore controller）异步执行。

在 v0.7.1 的文档体系中，与恢复相关的命令还有两条路径：

• ark create restore（本命令，位于 site/content/docs/v0.7.1/cli-reference/ark_create_restore.md）；
• ark restore create（同目录下的另一份参考文档 ark_restore_create.md，属于ark restore子命令树，见 ark_restore.md 中的 SEE ALSO 列表）。

两者语义相同，只是命令组织形式不同；在当代主干中统一为velero restore create。无论哪种写法，底层最终都会构造一个api.Restore对象，其Spec结构在 restore_types.go 中定义，包括BackupName、ScheduleName、IncludedNamespaces、ExcludedNamespaces、NamespaceMapping、LabelSelector、RestorePVs等字段——这正是下文命令行参数逐一映射的目标。

二、命令参数全解（Options）

v0.7.1 文档中ark create restore支持以下参数，这里以表格形式完整继承原文档，并结合源码补充语义细节。

参数	类型	说明
--exclude-namespaces	stringArray	从恢复中排除的命名空间列表
--exclude-resources	stringArray	从恢复中排除的资源，格式为resource.group，例如storageclasses.storage.k8s.io
-h, --help	-	显示 restore 命令帮助
--include-cluster-resources	optionalBool[=true]	是否在恢复中包含集群作用域（cluster-scoped）资源
--include-namespaces	stringArray	要恢复的命名空间列表（使用'*'表示所有命名空间），默认*
--include-resources	stringArray	要恢复的资源，格式为resource.group，例如storageclasses.storage.k8s.io（使用'*'表示所有资源）
--label-columns	stringArray	以逗号分隔的标签列表，用于作为输出表格的列显示
--labels	mapStringString	应用到恢复任务上的标签
--namespace-mappings	mapStringString	命名空间映射，格式为src1:dst1,src2:dst2,...，将备份中的命名空间名映射为恢复后的目标命名空间名
-o, --output	string	输出显示格式。对于 create 类命令，仅显示对象而不发送到服务器。有效格式为table、json和yaml
--restore-volumes	optionalBool[=true]	是否从快照恢复卷
-l, --selector	labelSelector	仅恢复匹配该标签选择器的资源，默认<none>
--show-labels	-	在最后一列显示标签

2.1 过滤类参数：命名空间与资源

四个过滤参数（--include-namespaces/--exclude-namespaces/--include-resources/--exclude-resources）分别对应RestoreSpec中的同名切片字段（见 restore_types.go）。默认--include-namespaces '*'表示恢复备份中的所有命名空间；若想只恢复default与app两个命名空间，可以写：

ark create restore daily-backup-20260915 --include-namespaces default,app

资源过滤采用 Kubernetes 的resource.group格式，例如要只恢复存储类与持久卷声明：

ark create restore backup-2 --include-resources persistentvolumeclaims,persistentvolumes

2.2 可选布尔参数（optionalBool）的三态语义

--include-cluster-resources与--restore-volumes的类型是optionalBool，这是 Ark/Velero 的专有标志类型，其实现位于 pkg/cmd/util/flag/optional_bool.go：

• 值类型为*bool，即存在nil（未设置）、true、false 三种状态；
• 不传参数时值为nil，服务端按默认策略处理；
• 传--restore-volumes=true或--restore-volumes=false可显式指定；
• 由于设置了NoOptDefVal = cmd.TRUE（见 create.go），可以直接写--restore-volumes作为--restore-volumes=true的简写，行为与普通布尔标志一致。

对应的 API 字段RestorePVs *bool（restore_types.go）同样为指针类型，保留了“未设置”这一中间状态，这正是三态设计的根本原因。

2.3 命名空间映射：迁移与改名

--namespace-mappings支持把备份中的命名空间恢复到不同的目标命名空间，格式为src1:dst1,src2:dst2,...。在源码中它由flag.Map类型承载，并显式配置了键值分隔符:与条目分隔符,（见 create.go 与 create.go）。例如将prod命名空间恢复到dr命名空间：

ark create restore --from-backup backup-1 --namespace-mappings prod:dr

在 API 层面对应RestoreSpec.NamespaceMapping（restore_types.go），文档注释明确：未出现在映射表中的源命名空间将恢复到同名的目标命名空间。

2.4 标签选择器与对象筛选

-l, --selector允许仅恢复与标签选择器匹配的对象，例如只恢复带有app=nginx标签的资源。该参数由flag.LabelSelector类型解析（见 pkg/cmd/util/flag/labelselector.go），最终写入RestoreSpec.LabelSelector（restore_types.go）。

2.5 对象元数据与输出控制

• --labels：给 Restore 对象本身打标签，对应ObjectMeta.Labels；
• -o, --output：table/json/yaml三种格式。值得强调的是文档中的关键行为说明——“对于 create 类命令，仅显示对象而不发送到服务器”，即输出模式下的 create 命令相当于一次“干跑（dry-run）”，可用于在提交前检查即将生成的 Restore 对象内容。在主干实现中，这一逻辑由 create.go 的output.PrintWithFormat完成：一旦成功打印（printed == true），命令直接返回，不再调用client.Create。
• --label-columns与--show-labels仅影响表格输出样式。

三、继承自父命令的全局参数

v0.7.1 文档中还列出了所有子命令都会继承的父命令参数，其中与连接配置和日志行为相关，完整继承如下：

--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

关键点说明：

• -n, --namespace（默认heptio-ark）：指定 Ark 运行所在的命名空间，也是 Restore 对象将被创建到的命名空间。注意这是 v0.7.1 时代的默认值，当代 Velero 默认命名空间已改为velero。
• --kubeconfig：指定访问 Kubernetes API Server 的 kubeconfig 路径；若未设置，会尝试环境变量KUBECONFIG及集群内（in-cluster）配置。
• 其余为 glog 风格日志参数：--alsologtostderr、--log_dir、--logtostderr、--stderrthreshold、--v、--vmodule、--log_backtrace_at。

四、从命令行到 Restore 对象的源码链路

在当代主干中，ark create restore的直系继承者是velero restore create，其入口为 NewCreateCommand，执行流程遵循 Cobra 的三段式：Complete → Validate → Run（见 create.go）。这三步恰好可以帮我们理解 v0.7.1 文档中每个参数的作用时机。

4.1 Complete：自动生成恢复名称

若命令行未显式指定恢复名称，Complete会根据数据源自动生成<sourceName>-<时间戳>格式的名称（create.go），例如backup-1-20260916150405。因此 v0.7.1 文档语法中的位置参数BACKUP在当代实现中对应--from-backup或--from-schedule。

4.2 Validate：参数互斥与合法性校验

Validate（create.go）会检查：

• --from-backup与--from-schedule必须且只能指定一个；
• --selector与--or-selector不能同时使用；
• 卷数据恢复策略、资源策略等枚举值必须合法；
• 若指定了备份名，会向集群查询该备份是否存在。

4.3 Run：构造 RestoreSpec 并提交

Run（create.go）将 v0.7.1 文档中的每个参数一一映射到api.Restore的Spec字段：

命令行参数	RestoreSpec 字段
--include-namespaces/--exclude-namespaces	IncludedNamespaces/ExcludedNamespaces
--include-resources/--exclude-resources	IncludedResources/ExcludedResources
--namespace-mappings	NamespaceMapping
--selector	LabelSelector
--restore-volumes	RestorePVs
--include-cluster-resources	IncludeClusterResources
--labels/--annotations	ObjectMeta.Labels/ObjectMeta.Annotations

创建成功后命令输出Restore request "xxx" submitted successfully.，并提示可用velero restore describe与velero restore logs查看详情（create.go）——这与 v0.7.1 文档 SEE ALSO 中提供的ark restore get/describe/logs/delete命令树一脉相承。

4.4 当代演进：新增能力一览

对比 v0.7.1 文档，主干版本在保持原有过滤/映射/卷恢复语义不变的基础上，新增了若干实用参数（全部可在 create.go 中查证）：

• --from-backup/--from-schedule：取代位置参数，支持从定时计划（Schedule）的最新成功备份恢复；
• --allow-partially-failed：配合--from-schedule，允许选择“部分失败（PartiallyFailed）”的最近备份作为数据源，其核心逻辑由 mostRecentBackup 按Status.StartTimestamp降序筛选完成，并有对应单测 TestMostRecentBackup 验证；
• -w, --wait：提交后阻塞等待恢复进入终态（Completed / PartiallyFailed / Failed / FailedValidation），并支持 ctrl-c 安全中断（恢复在后台继续）；
• --preserve-nodeports：是否保留 Service 的原 NodePort；
• --or-selector：多个标签选择器取“或”关系；
• --existing-resource-policy/--existing-volume-data-policy：控制目标集群已存在资源与卷数据时的处理策略；
• --item-operation-timeout、--resource-modifier-configmap、--resource-policies-configmap、--write-sparse-files、--parallel-files-download、--delete-extra-files等异步插件操作与文件系统恢复调优参数。

这些参数同样会被写入RestoreSpec（新增字段见 restore_types.go 附近），其枚举值校验（如existing-resource-policy仅接受none/update）也在 create.go 中强制约束。

五、与其他 restore 命令的配合使用

创建恢复任务只是第一步。v0.7.1 文档 SEE ALSO 指向ark create命令树，而同一版本目录下还提供了完整的恢复生命周期命令族，读者可结合以下文档深入：

• ark_restore.md：恢复命令树总览，列出 create / delete / describe / get / logs 五个子命令；
• ark_restore_create.md：ark restore create的等价参考；
• ark_restore_get.md：查看恢复任务列表与状态；
• ark_restore_describe.md：查看单个恢复任务的详细描述；
• ark_restore_logs.md：获取恢复过程日志，用于排查失败原因；
• ark_restore_delete.md：删除恢复任务。

典型的使用闭环是：ark create restore backup-1→ark restore get观察状态 →ark restore describe查看明细 →ark restore logs排查问题。

六、测试与验证依据

主干代码为上述命令行为提供了充分的测试佐证：

• create_test.go 中的TestCreateCommand用真实 pflag 依次解析了--from-backup、--restore-volumes、--labels、--namespace-mappings、--selector、--include-cluster-resources、--write-sparse-files等全量参数并断言生成的 Restore 对象字段，是理解“参数 → Spec 字段”映射最直接的活文档；
• TestMostRecentBackup 构造了 Completed、PartiallyFailed、Deleting 三种状态的备份，验证“从计划恢复时优先选择最近的成功或部分失败备份”的选择逻辑；
• optional_bool.go 的单测覆盖了三态布尔在空串、true、false 下的解析行为，印证--include-cluster-resources等参数可以省略值直接使用。

总而言之，ark create restore是 Ark/Velero 恢复能力的最核心入口：它用一组简洁的参数完成了命名空间/资源过滤、命名空间映射、标签筛选、集群资源开关与快照卷恢复等全部关键决策，并在当代实现中演进为功能更丰富的velero restore create。掌握本文参数表与源码映射关系，即可在实战中精准构造恢复请求，也能在阅读、调试 Velero 源码时快速定位参数落点。

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