Velero 恢复创建命令全解析ark restore create/velero restore create参数、源码实现与实战指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文以仓库中 v0.7.1 版本的 CLI 参考文档 ark restore create 为核心骨架完整讲解恢复Restore创建命令的全部参数含义、过滤与映射机制、源码级实现原理及生命周期阶段。读者学完后将能熟练使用ark restore create现代版本中对应velero restore create从指定备份或定时备份计划创建恢复理解每个标志位背后的 Restore 对象字段与校验逻辑并掌握如何用标签选择器、命名空间映射和资源策略精确控制恢复范围。一、命令概览从 Ark 到 Velero 的演进v0.7.1 文档中该命令由 ArkHeptio ArkVelero 的前身提供用于从已存在的备份中恢复 Kubernetes 资源。命令格式为ark restore create BACKUP [flags]其中BACKUP是位置参数指定要从中恢复的备份名称。命令的简洁描述为 Create a restore创建一个恢复。随着项目演进当前仓库中该命令已更名为velero restore create其用法见 create.go 命令定义扩展为支持显式指定恢复名称与三种来源velero restore create [RESTORE_NAME] [--from-backup BACKUP_NAME | --from-schedule SCHEDULE_NAME]RESTORE_NAME可选的恢复对象名称若不指定CLI 会自动生成来源名称-时间戳形式的名称。--from-backup从指定备份恢复对应早期版本的BACKUP位置参数。--from-schedule从指定定时备份计划Schedule恢复Velero 会自动选择该计划下最近一次成功的备份。注意两个时期的环境差异v0.7.1 文档中默认命名空间为heptio-ark而当前仓库默认命名空间为velero定义见 constants.go。二、命令参数全表v0.7.1 版本完整继承以下参数表完整继承自原文档的 Options 段落是恢复创建命令的核心控制面参数类型默认值说明--exclude-namespacesstringArray—从恢复中排除的命名空间列表--exclude-resourcesstringArray—从恢复中排除的资源格式为resource.group如storageclasses.storage.k8s.io-h, --help——显示 create 子命令帮助--include-cluster-resourcesoptionalBooltrue是否在恢复中包含集群级cluster-scoped资源--include-namespacesstringArray*要包含在恢复中的命名空间*表示全部命名空间--include-resourcesstringArray—要包含在恢复中的资源格式为resource.group*表示全部资源--label-columnsstringArray—以逗号分隔的标签列表用于在输出中作为附加列展示--labelsmapStringString—应用于恢复对象上的标签格式如key1value1,key2value2--namespace-mappingsmapStringString—命名空间映射格式src1:dst1,src2:dst2,...将备份中的源命名空间恢复到目标命名空间-o, --outputstring—输出显示格式对 create 命令而言仅展示对象但不提交到服务器。合法值为table、json、yaml--restore-volumesoptionalBooltrue是否从快照恢复卷Volume数据-l, --selectorlabelSelectornone仅恢复匹配该标签选择器的资源--show-labels——在输出的最后一列显示标签参数组合的核心语义包含/排除的优先级--include-namespaces与--exclude-namespaces、--include-resources与--exclude-resources成对出现。从源码的RestoreSpec字段定义restore_types.go可以看出排除列表的优先级高于包含列表即先选定范围、再剔除对象的经典 Velero 过滤模型。optionalBool三态特性--include-cluster-resources与--restore-volumes属于可选布尔optionalBool支持true/false/不指定三种状态。不指定时遵循服务端默认逻辑例如includeClusterResources为 null 时默认按 true 处理直接写--restore-volumes等价于--restore-volumestrue这一点在现代源码的 BindFlags 实现 中通过f.NoOptDefVal cmd.TRUE明确体现。资源名称格式资源统一使用resource.group格式书写如persistentvolumeclaims、persistentvolumes、storageclasses.storage.k8s.io这与kubectl的资源命名习惯一致。三、从父命令继承的全局参数ark restore create还继承了父命令ark的全局参数原文档 Options inherited from parent commands 段落完整内容参数默认值说明--alsologtostderr—同时将日志输出到标准错误和日志文件--kubeconfig string—连接 Kubernetes apiserver 使用的 kubeconfig 文件路径未设置时依次尝试环境变量KUBECONFIG与集群内配置--log_backtrace_at traceLocation:0当日志命中file:N时输出堆栈跟踪--log_dir string—非空时指定日志文件写入目录--logtostderr—将日志输出到标准错误而非文件-n, --namespace stringheptio-ark当前版本为veleroArk/Velero 操作所在的命名空间--stderrthreshold severity2达到或超过该级别的日志同时写入 stderr-v, --v Level—V 日志的日志级别--vmodule moduleSpec—逗号分隔的patternN列表用于按文件过滤日志其中-n/--namespace是最常用的参数之一它决定了从哪个命名空间查找备份、并向哪个命名空间提交恢复对象必须与部署 Velero 服务端时的命名空间一致。四、实战用法示例尽管 v0.7.1 文档正文未给出示例现代源码的命令定义中提供了可直接套用的实战模板create.go 示例完整列举如下# 创建名为 restore-1 的恢复数据源为备份 backup-1 velero restore create restore-1 --from-backup backup-1 # 不指定名称自动生成 backup-1-时间戳 形式的恢复 velero restore create --from-backup backup-1 # 从计划 schedule-1 触发的最新一次成功备份创建恢复 velero restore create --from-schedule schedule-1 # 允许从计划下的 PartiallyFailed部分失败备份恢复 velero restore create --from-schedule schedule-1 --allow-partially-failed # 只恢复备份中的 persistentvolumeclaims 和 persistentvolumes 两类资源 velero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes进阶组合示例结合参数表与源码字段可将多个过滤维度叠加使用# 将备份中的 namespace-a 恢复到 namespace-b只恢复 app 命名空间、排除 ConfigMap且恢复卷数据 ark restore create backup-1 \ --namespace-mappings namespace-a:namespace-b \ --include-namespaces app \ --exclude-resources configmaps \ --restore-volumestrue# 仅恢复带 appnginx 标签的对象并给恢复对象打上 ownerops 标签 ark restore create backup-2 \ --selector appnginx \ --labels ownerops# 以 YAML 形式预览将要创建的恢复对象不会真正提交到服务器 ark restore create backup-3 -o yaml-o/--output的仅展示不提交特性非常适合在脚本中先生成清单、评审后再执行或在 CI 中对恢复配置做静态检查。五、源码实现深度解析5.1 参数对象与命令构建命令的核心由 CreateOptions 结构体 承载每个标志位在 BindFlags 中绑定。值得关注的默认值初始化NewCreateOptionsIncludeNamespaces默认初始化为*即默认恢复全部命名空间NamespaceMappings使用flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:)从而支持src1:dst1,src2:dst2的逗号/冒号分隔语法RestoreVolumes、PreserveNodePorts、IncludeClusterResources等均为三态 optionalBool初始为 nil不指定交由服务端决定。5.2 名称自动生成逻辑在 Complete 方法 中若用户未提供恢复名称则以备份名或计划名为前缀、拼接当前时间戳生成名称例如backup-1-20260916150405。5.3 校验规则ValidateValidate 方法 定义了以下硬性约束违反任一条件命令即报错--from-backup与--from-schedule必须且只能指定一个同时指定或都不指定都会报错 either a backup or schedule must be specified, but not both--selector与--or-selector不能同时使用--existing-resource-policy仅接受none、update--existing-volume-data-policy仅接受none、full、incremental--parallel-files-download不能为负数指定--from-backup时会先通过 API 读取该备份若不存在直接返回backups.velero.io xxx not found指定--from-schedule时会按velero.io/schedule-name标签列出该计划产生的备份若一个都没有则报错 No backups found for the schedule。以上校验逻辑在 create_test.go 中有完整覆盖例如测试断言不存在的备份会得到backups.velero.io not-exist not found。5.4 最近备份选择算法使用--from-schedule时mostRecentBackup 函数 负责挑选数据源它将该计划的所有备份按Status.StartTimestamp降序排列然后返回第一个阶段属于允许列表默认Completed配合--allow-partially-failed时额外包含PartiallyFailed的备份。对应的单测 TestMostRecentBackup 验证了时间最新且阶段合格的备份被正确选中。5.5 对象提交与等待逻辑Run 方法 完成最终动作将各标志位映射为api.Restore对象如RestorePVs对应--restore-volumes、NamespaceMapping对应--namespace-mappings若指定了-o/--output直接按 table/json/yaml 打印对象并返回不提交服务器通过 client-go 创建 Restore 自定义资源未加--wait时打印提示Run velero restore describe name or velero restore logs name for more details.加了-w/--wait时用 SharedInformer 监听同名 Restore 的状态更新直到进入FailedValidation、Completed、PartiallyFailed或Failed等终态后打印结果。等待期间按Ctrl-C可安全退出恢复会在后台继续执行。六、Restore 对象的底层结构命令提交的是 Velero 自定义资源Restore其SpecRestoreSpec与上述标志位一一对应同时揭示了更细粒度的控制能力BackupName/ScheduleName恢复来源IncludedNamespaces/ExcludedNamespaces/IncludedResources/ExcludedResources范围过滤NamespaceMapping命名空间重映射LabelSelector/OrLabelSelectors按标签过滤对象二者互斥RestorePVs是否从快照恢复卷PreserveNodePorts是否保留 Service 的原 NodePortIncludeClusterResources是否包含集群级资源RestoreStatus指定哪些资源的 status 字段需要被恢复现代版本功能ExistingResourcePolicy已存在 Kubernetes 资源的处理策略none不覆盖或update对发生变更的资源执行 patchExistingVolumeDataPolicy已存在卷数据的处理策略none/full/incrementalItemOperationTimeout异步插件操作超时时间默认 4 小时ResourceModifier恢复前对资源应用的 JSON 补丁引用ResourcePolicy恢复资源过滤策略 ConfigMap 的引用UploaderConfig卷恢复上传配置WriteSparseFiles、ParallelFilesDownload、DeleteExtraFiles。这些策略常量的合法值与语义定义在 restore_types.go与校验规则完全一致。七、恢复生命周期创建后的阶段演进创建命令提交成功后Restore 控制器将驱动对象经历一系列阶段阶段常量定义见 restore_types.goNew已创建尚未被控制器处理FailedValidation未通过控制器校验不会执行InProgress正在执行恢复WaitingForPluginOperations/WaitingForPluginOperationsPartiallyFailedKubernetes 资源已恢复异步插件操作仍在进行Finalizing/FinalizingPartiallyFailed异步操作完成等待收尾任务Completed成功无错误PartiallyFailed执行完成但恢复个别条目时出现错误Failed无法执行失败原因记录在Status.FailureReason。--wait模式正是监听上述终态FailedValidation/Completed/PartiallyFailed/Failed来决定何时返回。恢复完成后可用ark restore describe查看详情、ark restore logs获取日志。八、相关命令导航ark restore create是 restore 子命令族的一员其余兄弟命令见 ark restore 参考文档ark restore create创建恢复本文主题ark restore delete删除恢复ark restore describe查看恢复详情ark restore get列出恢复ark restore logs获取恢复日志。整个命令体系的入口是 ark 主命令它同时管理 backup、schedule、plugin、server 等子命令构成完整的备份-恢复操作面。九、使用建议与注意事项明确数据源--from-backup与--from-schedule二选一二者都省略或都填写都会导致校验失败--from-schedule适合始终恢复到最近成功备份的自动化场景。善用三态布尔--restore-volumes与--include-cluster-resources建议显式声明true/false避免依赖隐式默认值造成预期偏差。命名空间映射的坑--namespace-mappings只影响显式列出的命名空间未映射的命名空间仍恢复到同名命名空间映射语法为src:dst对多个对之间用逗号分隔。先在-o yaml下预览任何复杂恢复建议先加-o yaml查看最终生成的 Restore 对象确认过滤范围与映射无误后再真正提交。结果核验提交后通过ark restore get观察阶段演进终态为PartiallyFailed时用ark restore describe与ark restore logs定位具体失败条目。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考