企业官网建设流程全解析

Velero restore create 命令详解：从备份创建 Kubernetes 应用恢复任务

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

导读

velero restore create（其前身为 Ark 时代的ark restore create）是 Velero 中用于将已备份的 Kubernetes 应用与持久化数据恢复到目标集群的核心入口命令。本文以仓库中 site/content/docs/v0.8.0/cli-reference/ark_restore_create.md 为骨架，结合当前源码深入讲解命令语法、全部参数含义、命名规则、校验逻辑与底层实现。读完本文，你将能够熟练运用命名空间/资源筛选、标签选择器、命名空间映射、集群级资源开关等能力，构造出符合各种容灾与迁移场景的恢复请求，并理解 CLI 如何转化为 Restore CR 提交给 Velero 服务端。

命令概述：从 Ark 到 Velero 的演变

本文关联的参考文档位于仓库的 v0.8.0 文档目录（site/content/docs/v0.8.0/cli-reference/ark_restore_create.md），该版本时期项目还叫Ark，CLI 前缀为ark，默认操作命名空间为heptio-ark。项目随后更名为 Velero，CLI 变为velero，默认命名空间变为velero，但命令结构与绝大多数参数语义一脉相承。

从当前源码看，restore 子命令族的组织方式与文档一致：pkg/cmd/cli/restore/restore.go 中的NewCommand挂载了五个子命令：

c.AddCommand( NewCreateCommand(f, "create"), NewGetCommand(f, "get"), NewLogsCommand(f), NewDescribeCommand(f, "describe"), NewDeleteCommand(f, "delete"), )

其中create正是本文的主角，对应 pkg/cmd/cli/restore/create.go 中的NewCreateCommand。它的命令用法定义为：

Use: use + " [RESTORE_NAME] [--from-backup BACKUP_NAME | --from-schedule SCHEDULE_NAME]"

即：要么通过--from-backup指定备份，要么通过--from-schedule指定调度（Schedule），二选一，最多接收一个 RESTORE_NAME 位置参数。

命令语法与典型示例

原文档给出的 Synopsis 为：

ark restore create [RESTORE_NAME] --from-backup BACKUP_NAME [flags]

对应的 Velero 时代写法为：

velero restore create [RESTORE_NAME] --from-backup BACKUP_NAME [flags]

原文档中的两个经典示例：

# 创建名为 "restore-1" 的恢复任务，数据来自备份 "backup-1" velero restore create restore-1 --from-backup backup-1 # 不指定名字，使用默认名（"backup-1-<timestamp>"）创建恢复任务 velero restore create --from-backup backup-1

当前源码进一步扩展了使用场景，在 create.go 的 Example 中还包含以下写法：

# 从调度 schedule-1 触发的最近一次成功备份创建恢复 velero restore create --from-schedule schedule-1 # 从调度触发的最近一次"成功或部分失败"备份创建恢复 velero restore create --from-schedule schedule-1 --allow-partially-failed # 只恢复备份中的 persistentvolumeclaims 和 persistentvolumes velero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes

命名规则（源码级）

当不传RESTORE_NAME时，名字由 Complete 方法自动生成：

if len(args) == 1 { o.RestoreName = args[0] } else { sourceName := o.BackupName if o.ScheduleName != "" { sourceName = o.ScheduleName } o.RestoreName = fmt.Sprintf("%s-%s", sourceName, time.Now().Format("20060102150405")) }

即默认名形如backup-1-20260916041814（来源名 +yyyyMMddHHmmss时间戳），这正是原文档中 "backup-1-<timestamp>" 的准确含义。

完整参数详解

原文档列出了 create 命令的全部选项，下面逐项结合当前源码（BindFlags）与RestoreSpec定义（pkg/apis/velero/v1/restore_types.go）展开说明。

核心来源参数

校验逻辑在 Validate 中：--from-backup与--from-schedule不能同时给出，也不能都为空（源码报错信息为either a backup or schedule must be specified, but not both）。若指定--from-backup，会先查询该 Backup 对象确认存在；若指定--from-schedule，会按velero.io/schedule-name标签列出该调度产生的备份，若一个都没有则报错No backups found for the schedule %s。

命名空间筛选

在 NewCreateOptions 中，IncludeNamespaces初始化为flag.NewStringArray("*")，对应RestoreSpec.IncludedNamespaces；ExcludedNamespaces对应RestoreSpec.ExcludedNamespaces。注意：include 与 exclude 是"先包含后排除"的关系，排除规则拥有更高优先级。

资源类型筛选

这两项分别映射到RestoreSpec.IncludedResources与RestoreSpec.ExcludedResources。原文档的示例格式storageclasses.storage.k8s.io即"资源名.API 组"的标准写法；对于核心组资源可直接写资源名（如persistentvolumeclaims）。CLI 中的stringArray类型支持多次传参，例如：

velero restore create --from-backup backup-2 \ --include-resources persistentvolumeclaims,persistentvolumes,statefulsets.apps

集群级资源控制

这是一个optionalBool类型参数：它不像普通 bool 那样只能true/false，而是允许三态（true / false / 未设置），因为该字段语义上需要"由 Velero 服务端根据目标集群情况自动决定"。源码中该标志通过f.NoOptDefVal = cmd.TRUE注册（create.go），因此用户可以直接写--include-cluster-resources表示=true。三态实现可查看 pkg/cmd/util/flag/optional_bool.go 中的OptionalBool类型，nil值最终对应RestoreSpec.IncludeClusterResources为 nil，交由服务端决策。

标签选择器与标签列

--selector映射到RestoreSpec.LabelSelector（metav1.LabelSelector），支持 Kubernetes 标准标签选择器语法，例如--selector app=nginx,env!=prod。--label-columns与--show-labels属于输出展示层面的选项，在 pkg/cmd/util/output 相关的表格打印逻辑中生效，不影响实际恢复内容。

命名空间映射

该参数在 NewCreateOptions 中被初始化为带自定义分隔符的 Map：

NamespaceMappings: flag.NewMap().WithEntryDelimiter(',').WithKeyValueDelimiter(':'),

即条目之间用逗号分隔、键值之间用冒号分隔。它映射到RestoreSpec.NamespaceMapping，是跨集群迁移时最常用的能力之一——例如把prod命名空间整体恢复到dev命名空间。未出现在映射中的源命名空间将恢复到同名命名空间。

卷恢复控制

该标志同样以NoOptDefVal = cmd.TRUE方式注册（create.go），支持直接写--restore-volumes作为=true的简写。对应RestoreSpec.RestorePVs：为true时，备份中包含快照的 PV 将按快照恢复；为false时只恢复资源定义不恢复卷数据；为 nil 时由服务端依据备份中是否存在卷快照来决定。

元数据标签

映射到Restore的ObjectMeta.Labels，可用于后续用velero restore get -l team=ops筛选，或与服务端准入/审计逻辑联动。

输出格式

这是output.BindFlags注入的通用输出标志（见 create.go）。当指定-o json或-o yaml时，命令会打印将要创建的 Restore 对象清单并提前返回，不向 Kubernetes API 发送创建请求。该行为在 Run 中体现：

if printed, err := output.PrintWithFormat(c, restore); printed || err != nil { return err }

这在 CI/CD 流水线中非常实用——可以先预览最终生成的 Restore 定义（含全部筛选参数展开后的 spec），确认无误后再真正提交。

继承自父命令的全局参数

原文档还列出以下继承参数，它们在所有ark/velero子命令中通用：

--alsologtostderr 同时写入 stderr 与日志文件 --kubeconfig string kubeconfig 文件路径；未设置时依次尝试 KUBECONFIG 环境变量与集群内配置 --kubecontext string 指定 kubeconfig 中的 context；默认使用当前 context --log_backtrace_at traceLocation 当日志命中 file:N 时输出堆栈（默认 :0） --log_dir string 非空时在此目录写日志文件 --logtostderr 日志写入 stderr 而非文件 -n, --namespace string 操作命名空间（v0.8.0 默认 "heptio-ark"，Velero 时代默认 "velero"） --stderrthreshold severity 达到该级别的日志同时输出到 stderr（默认 2） -v, --v Level V 日志级别 --vmodule moduleSpec 按文件过滤的 pattern=N 日志级别配置

其中--kubeconfig与--kubecontext直接决定命令连接哪个集群、以哪个上下文身份创建 Restore，多集群场景下务必显式指定。

服务端校验与创建流程

CLI 的执行流程严格遵循 Cobra 三阶段模式（create.go）：

cmd.CheckError(o.Complete(args, f)) cmd.CheckError(o.Validate(c, args, f)) cmd.CheckError(o.Run(c, f))

1. Complete：解析位置参数生成默认名称，并建立与集群的 controller-runtime watch client。
2. Validate：执行本地前置校验，包括：
   • --from-backup与--from-schedule互斥且必须存在其一；
   • --selector与--or-selector（当前版本的 OR 语义选择器）不能同时指定；
   • --existing-resource-policy仅接受none/update；
   • --existing-volume-data-policy仅接受none/full/incremental；
   • --parallel-files-download不能为负数；
   • 备份/调度存在性检查。
3. Run：组装api.Restore对象并调用o.client.Create提交。

从调度恢复的"最近一次"语义

当使用--from-schedule且指定--allow-partially-failed时，Run 会先列出该调度的全部备份，调用 mostRecentBackup 找出StartTimestamp最新的、且状态属于Completed或PartiallyFailed的备份，然后改用它进行恢复；找不到时则原样提交，由服务端兜底校验。测试用例 pkg/cmd/cli/restore/create_test.go 验证了这一排序与过滤逻辑：在包含 Deleting/Completed/PartiallyFailed 三种状态的备份列表中，函数正确挑选出最新且状态合格者。

创建成功后的输出

创建请求提交成功后，命令默认输出：

Restore request "restore-1" submitted successfully. Run `velero restore describe restore-1` or `velero restore logs restore-1` for more details.

当前版本还支持-w/--wait标志：提交后通过 informer 监听该 Restore 的状态变化，直到进入终态（Completed/PartiallyFailed/Failed/FailedValidation），期间可安全按 Ctrl-C 停止等待，恢复任务仍会在后台继续执行。

CLI 参数与 Restore CR 的映射关系

CLI 本质上只是一个"参数收集器"，最终所有参数都会被序列化进一个api.Restore自定义资源（见 pkg/apis/velero/v1/restore_types.go），由服务端的 restore controller 消费。核心映射如下：

了解这一映射后，你也可以绕过 CLI，直接用kubectl创建等价的 Restore 对象，这为 GitOps 方式声明恢复任务提供了可能。

后续查看与清理：与 create 配套的命令

创建恢复后，通常配合以下命令跟踪与清理（参见 site/content/docs/v0.8.0/cli-reference/ark_restore.md）：

Restore 的生命周期状态定义在 restore_types.go：从New开始，经过InProgress、WaitingForPluginOperations、Finalizing，最终进入Completed、PartiallyFailed或Failed等终态；若未通过校验则直接进入FailedValidation。

总结与最佳实践

结合原文档与源码实现，使用velero restore create时有几点值得牢记：

1. 来源二选一：必须且只能指定--from-backup或--from-schedule之一；调度场景可用--allow-partially-failed放宽对"最近一次成功备份"的限定。
2. 筛选四件套：--include/--exclude-namespaces与--include/--exclude-resources组合使用即可实现精细的"只恢复我想要的那部分"；排除优先于包含。
3. 跨命名空间迁移：--namespace-mappings prod:dev是灾备演练与多环境复制的利器。
4. 三态布尔：--restore-volumes、--include-cluster-resources不传、传=true、传=false三种写法语义不同，涉及服务端决策时保持"不传"让 Velero 自动判断通常最稳妥。
5. 先预览再提交：利用-o yaml/json查看将要生成的 Restore 定义，确认筛选条件无误后再真正创建。
6. 创建后跟踪：使用get、describe、logs三个配套命令持续观察恢复进度与错误明细。

关于更多 CLI 与插件细节，可继续阅读 v0.8.0 文档集中的 ark_restore.md 及 output-file-format.md，并结合仓库源码 pkg/cmd/cli/restore 目录下的实现与测试深入验证。

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