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

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该版本时期项目还叫ArkCLI 前缀为ark默认操作命名空间为heptio-ark。项目随后更名为 VeleroCLI 变为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展开说明。核心来源参数参数类型说明--from-backup stringstring指定要恢复的备份名称与--from-schedule互斥且必须二选一--from-schedule stringstring指定调度名称Velero 将恢复该调度触发的最近一次成功备份校验逻辑在 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。命名空间筛选参数默认值说明--include-namespaces stringArray*要包含的命名空间列表*表示全部命名空间--exclude-namespaces stringArray空要从恢复中排除的命名空间列表在 NewCreateOptions 中IncludeNamespaces初始化为flag.NewStringArray(*)对应RestoreSpec.IncludedNamespacesExcludedNamespaces对应RestoreSpec.ExcludedNamespaces。注意include 与 exclude 是先包含后排除的关系排除规则拥有更高优先级。资源类型筛选参数默认值说明--include-resources stringArray*全部资源要包含的资源类型列表格式为resource.group例如storageclasses.storage.k8s.io--exclude-resources stringArray空要排除的资源类型列表格式同上这两项分别映射到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集群级资源控制参数默认值说明--include-cluster-resources optionalBool[true]未指定由服务端决定是否在恢复中包含集群作用域cluster-scoped资源这是一个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交由服务端决策。标签选择器与标签列参数默认值说明-l, --selector labelSelectornone仅恢复匹配该标签选择器的资源--label-columns stringArray空逗号分隔的标签列表作为表格输出中的附加列展示--show-labelsfalse在输出表格最后一列显示标签--selector映射到RestoreSpec.LabelSelectormetav1.LabelSelector支持 Kubernetes 标准标签选择器语法例如--selector appnginx,env!prod。--label-columns与--show-labels属于输出展示层面的选项在 pkg/cmd/util/output 相关的表格打印逻辑中生效不影响实际恢复内容。命名空间映射参数说明--namespace-mappings mapStringString命名空间映射格式src1:dst1,src2:dst2,...将备份中的源命名空间恢复到目标命名空间该参数在 NewCreateOptions 中被初始化为带自定义分隔符的 MapNamespaceMappings: flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:),即条目之间用逗号分隔、键值之间用冒号分隔。它映射到RestoreSpec.NamespaceMapping是跨集群迁移时最常用的能力之一——例如把prod命名空间整体恢复到dev命名空间。未出现在映射中的源命名空间将恢复到同名命名空间。卷恢复控制参数默认值说明--restore-volumes optionalBool[true]未指定是否从快照恢复卷数据该标志同样以NoOptDefVal cmd.TRUE方式注册create.go支持直接写--restore-volumes作为true的简写。对应RestoreSpec.RestorePVs为true时备份中包含快照的 PV 将按快照恢复为false时只恢复资源定义不恢复卷数据为 nil 时由服务端依据备份中是否存在卷快照来决定。元数据标签参数类型说明--labels mapStringStringmap应用到 Restore 对象上的标签键值对以逗号分隔如teamops,envdr映射到Restore的ObjectMeta.Labels可用于后续用velero restore get -l teamops筛选或与服务端准入/审计逻辑联动。输出格式参数默认值说明-o, --output string表格输出显示格式。对于 create 命令仅展示对象而不真正提交到服务器。合法值table、json、yaml这是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-arkVelero 时代默认 velero --stderrthreshold severity 达到该级别的日志同时输出到 stderr默认 2 -v, --v Level V 日志级别 --vmodule moduleSpec 按文件过滤的 patternN 日志级别配置其中--kubeconfig与--kubecontext直接决定命令连接哪个集群、以哪个上下文身份创建 Restore多集群场景下务必显式指定。服务端校验与创建流程CLI 的执行流程严格遵循 Cobra 三阶段模式create.gocmd.CheckError(o.Complete(args, f)) cmd.CheckError(o.Validate(c, args, f)) cmd.CheckError(o.Run(c, f))Complete解析位置参数生成默认名称并建立与集群的 controller-runtime watch client。Validate执行本地前置校验包括--from-backup与--from-schedule互斥且必须存在其一--selector与--or-selector当前版本的 OR 语义选择器不能同时指定--existing-resource-policy仅接受none/update--existing-volume-data-policy仅接受none/full/incremental--parallel-files-download不能为负数备份/调度存在性检查。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 参数RestoreSpec 字段--from-backupbackupName--from-schedulescheduleName--include-namespacesincludedNamespaces--exclude-namespacesexcludedNamespaces--include-resourcesincludedResources--exclude-resourcesexcludedResources--namespace-mappingsnamespaceMapping--selectorlabelSelector--restore-volumesrestorePVs--include-cluster-resourcesincludeClusterResources--labelsmetadata.labels了解这一映射后你也可以绕过 CLI直接用kubectl创建等价的 Restore 对象这为 GitOps 方式声明恢复任务提供了可能。后续查看与清理与 create 配套的命令创建恢复后通常配合以下命令跟踪与清理参见 site/content/docs/v0.8.0/cli-reference/ark_restore.md命令用途velero restore get列出 Restore 及其状态文档velero restore describe [NAME]查看单个恢复的详细描述与统计文档velero restore logs [NAME]获取恢复过程的详细日志velero restore delete [NAME]删除恢复任务Restore 的生命周期状态定义在 restore_types.go从New开始经过InProgress、WaitingForPluginOperations、Finalizing最终进入Completed、PartiallyFailed或Failed等终态若未通过校验则直接进入FailedValidation。总结与最佳实践结合原文档与源码实现使用velero restore create时有几点值得牢记来源二选一必须且只能指定--from-backup或--from-schedule之一调度场景可用--allow-partially-failed放宽对最近一次成功备份的限定。筛选四件套--include/--exclude-namespaces与--include/--exclude-resources组合使用即可实现精细的只恢复我想要的那部分排除优先于包含。跨命名空间迁移--namespace-mappings prod:dev是灾备演练与多环境复制的利器。三态布尔--restore-volumes、--include-cluster-resources不传、传true、传false三种写法语义不同涉及服务端决策时保持不传让 Velero 自动判断通常最稳妥。先预览再提交利用-o yaml/json查看将要生成的 Restore 定义确认筛选条件无误后再真正创建。创建后跟踪使用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考