VeleroArkark 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.mdark 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等字段——这正是下文命令行参数逐一映射的目标。二、命令参数全解Optionsv0.7.1 文档中ark create restore支持以下参数这里以表格形式完整继承原文档并结合源码补充语义细节。参数类型说明--exclude-namespacesstringArray从恢复中排除的命名空间列表--exclude-resourcesstringArray从恢复中排除的资源格式为resource.group例如storageclasses.storage.k8s.io-h, --help-显示 restore 命令帮助--include-cluster-resourcesoptionalBool[true]是否在恢复中包含集群作用域cluster-scoped资源--include-namespacesstringArray要恢复的命名空间列表使用*表示所有命名空间默认*--include-resourcesstringArray要恢复的资源格式为resource.group例如storageclasses.storage.k8s.io使用*表示所有资源--label-columnsstringArray以逗号分隔的标签列表用于作为输出表格的列显示--labelsmapStringString应用到恢复任务上的标签--namespace-mappingsmapStringString命名空间映射格式为src1:dst1,src2:dst2,...将备份中的命名空间名映射为恢复后的目标命名空间名-o, --outputstring输出显示格式。对于 create 类命令仅显示对象而不发送到服务器。有效格式为table、json和yaml--restore-volumesoptionalBool[true]是否从快照恢复卷-l, --selectorlabelSelector仅恢复匹配该标签选择器的资源默认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,persistentvolumes2.2 可选布尔参数optionalBool的三态语义--include-cluster-resources与--restore-volumes的类型是optionalBool这是 Ark/Velero 的专有标志类型其实现位于 pkg/cmd/util/flag/optional_bool.go值类型为*bool即存在nil未设置、true、false 三种状态不传参数时值为nil服务端按默认策略处理传--restore-volumestrue或--restore-volumesfalse可显式指定由于设置了NoOptDefVal cmd.TRUE见 create.go可以直接写--restore-volumes作为--restore-volumestrue的简写行为与普通布尔标志一致。对应的 API 字段RestorePVs *boolrestore_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.NamespaceMappingrestore_types.go文档注释明确未出现在映射表中的源命名空间将恢复到同名的目标命名空间。2.4 标签选择器与对象筛选-l, --selector允许仅恢复与标签选择器匹配的对象例如只恢复带有appnginx标签的资源。该参数由flag.LabelSelector类型解析见 pkg/cmd/util/flag/labelselector.go最终写入RestoreSpec.LabelSelectorrestore_types.go。2.5 对象元数据与输出控制--labels给 Restore 对象本身打标签对应ObjectMeta.Labels-o, --outputtable/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 patternN 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参数互斥与合法性校验Validatecreate.go会检查--from-backup与--from-schedule必须且只能指定一个--selector与--or-selector不能同时使用卷数据恢复策略、资源策略等枚举值必须合法若指定了备份名会向集群查询该备份是否存在。4.3 Run构造 RestoreSpec 并提交Runcreate.go将 v0.7.1 文档中的每个参数一一映射到api.Restore的Spec字段命令行参数RestoreSpec 字段--include-namespaces/--exclude-namespacesIncludedNamespaces/ExcludedNamespaces--include-resources/--exclude-resourcesIncludedResources/ExcludedResources--namespace-mappingsNamespaceMapping--selectorLabelSelector--restore-volumesRestorePVs--include-cluster-resourcesIncludeClusterResources--labels/--annotationsObjectMeta.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.mdark 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考