Velero restore create 命令完全指南从 Ark 到 Velero 的恢复创建实战详解【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本篇文章以 Velero 项目早期v0.6.0彼时还叫 Ark的 CLI 参考文档 ark restore create 为骨架系统讲解恢复Restore创建命令的语法、全部参数含义与使用场景并结合当前仓库的 create.go、create_test.go 以及 restore_types.go 源码讲清楚每一个参数背后对应的RestoreSpec字段与校验逻辑。读完本文你将能熟练地通过命令行创建精细化控制的恢复任务并能读懂恢复对象的底层数据结构。一、命令定位与历史沿革ark restore create是 v0.6.0 时代项目名为Ark用于创建恢复任务的子命令挂载在ark restore父命令之下。在 ark_restore.md 中定义其定位为 Work with restores。该项目后续更名为Velero命令也相应变为velero restore create但核心语法与参数设计一脉相承。在当前的仓库源码中该命令的现代版本实现在 pkg/cmd/cli/restore/create.go其Short描述仍是 Create a restore由 restore.go 将create、get、logs、describe、delete五个子命令统一挂载到velero restore下。也就是说v0.6.0 文档描述的这条命令在今天的 Velero 中依然存在、依然活跃。二、命令语法Synopsisark restore create BACKUP [flags]对应现代 Velero 的完整用法为velero restore create [RESTORE_NAME] [--from-backup BACKUP_NAME | --from-schedule SCHEDULE_NAME]命令的核心职责是根据一个已存在的备份Backup创建恢复Restore对象。恢复对象创建后Velero 服务端会异步执行真正的数据与资源回放命令本身只负责提交请求并返回结果。从源码的 NewCreateCommand 可以看到当前用法签名支持三种典型调用形态velero restore create restore-1 --from-backup backup-1显式命名恢复对象从指定备份恢复velero restore create --from-backup backup-1不指定名称时命令会自动生成backup-1-时间戳形式的默认名见 Complete 方法时间戳格式为20060102150405velero restore create --from-schedule schedule-1从某个调度最近一次成功触发的备份恢复。v0.6.0 文档中要求BACKUP为必填位置参数而现代版本将备份来源改为--from-backup/--from-schedule互斥选项并通过 Validate 方法 严格校验二者必须且只能指定其一。三、核心选项详解v0.6.0 文档列出的选项构成了恢复控制的基础能力。下表逐一说明每个选项的作用并对照现代源码中的实现字段选项说明对应RestoreSpec字段见 restore_types.go--exclude-namespaces stringArray从恢复中排除的命名空间列表ExcludedNamespaces--exclude-resources stringArray从恢复中排除的资源格式为resource.group如storageclasses.storage.k8s.ioExcludedResources--include-cluster-resources optionalBool[true]是否恢复集群级cluster-scoped资源默认 trueIncludeClusterResources--include-namespaces stringArray要恢复的命名空间默认*全部命名空间IncludedNamespaces--include-resources stringArray要恢复的资源格式resource.group默认*全部资源IncludedResources--label-columns stringArray以标签作为表格列展示配合输出表格使用—仅影响展示--labels mapStringString为恢复对象附加的标签ObjectMeta.Labels--namespace-mappings mapStringString命名空间映射格式src1:dst1,src2:dst2,...用于把备份中的命名空间恢复到新命名空间NamespaceMapping-o, --output string输出格式table/json/yaml对 create 类命令仅打印对象而不提交到服务端—--restore-volumes optionalBool[true]是否从快照恢复卷默认 trueRestorePVs-l, --selector labelSelector仅恢复匹配该标签选择器的资源默认noneLabelSelector--show-labels在最后一列显示标签—仅影响展示3.1 命名空间与资源的包含/排除--include-namespaces与--exclude-namespaces是一对互补过滤器--include-resources与--exclude-resources同理。在 RestoreSpec 中这些字段被定义为字符串切片语义为对应字段为空时不做限制如IncludedNamespaces为空表示包含所有命名空间显式给定*表示通配全部资源格式采用resource.group例如storageclasses.storage.k8s.io这是 Kubernetes API 发现机制下的标准资源标识。3.2 命名空间映射namespace-mappings--namespace-mappings是最常用的迁移利器当你想把prod命名空间的备份恢复到dev命名空间时使用ark restore create prod-backup --namespace-mappings prod:dev在源码中该参数通过 flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:) 解析即逗号分隔多组映射、冒号分隔源与目标。最终存入RestoreSpec.NamespaceMappingmap[string]string未出现在映射中的源命名空间将按原名恢复见 restore_types.go。3.3 标签选择器过滤selector-l, --selector用于在备份范围内做细粒度的对象过滤。例如只恢复带有appweb标签的 Podark restore create backup-1 -l appweb对应RestoreSpec.LabelSelector类型为metav1.LabelSelector当为空或 nil 时恢复所有对象。3.4 卷恢复控制restore-volumes--restore-volumes是 optionalBool 类型默认值为 true意味着裸写--restore-volumes等价于--restore-volumestrue。这一裸布尔设计在现代源码中通过f.NoOptDefVal cmd.TRUE实现见 BindFlags。置为false时恢复过程将跳过卷数据/快照的恢复只回放 Kubernetes 资源对象。对应字段为RestorePVs *bool。3.5 输出格式-o, --output-o table|json|yaml对 create 类命令有特殊语义只打印将要创建的对象不真正提交到服务端适合先做演练确认恢复配置是否符合预期再实际执行。四、从父命令继承的全局选项以下选项并非restore create独有而是所有 Ark/Velero CLI 子命令共享的全局日志与连接配置--alsologtostderr 同时输出日志到标准错误与文件 --kubeconfig string kubeconfig 文件路径未设置时依次尝试环境变量 KUBECONFIG 与集群内配置 --log_backtrace_at traceLocation 当日志命中 file:N 时输出堆栈跟踪默认 :0 --log_dir string 日志目录非空时写入文件 --logtostderr 日志输出到标准错误而非文件 --stderrthreshold severity 达到或超过该级别的日志进入 stderr默认 2 -v, --v Level V 日志级别 --vmodule moduleSpec 按文件的 patternN 过滤日志其中--kubeconfig是最常用的选项当你在本地机器上操作远端集群时需显式指定 kubeconfig 路径否则命令会按默认顺序寻找~/.kube/config或集群内配置。结合 client/config.go 的配置解析逻辑Velero CLI 会优先使用--kubeconfig显式指定的文件。五、现代 Velero 的扩展参数源码级补充v0.6.0 之后velero restore create在保留上述核心参数的基础上增加了大量能力。以下参数在 BindFlags 中注册当前仓库源码均可验证参数说明--from-backup string指定备份来源--from-schedule string从调度最近一次成功备份恢复--allow-partially-failed配合--from-schedule允许选择最近一次部分失败PartiallyFailed的备份--preserve-nodeports恢复 Service 时是否保留原有 nodePort对应PreserveNodePorts--existing-resource-policy恢复策略取值none或update决定对已存在 K8s 资源如何处理对应ExistingResourcePolicy--existing-volume-data-policy卷数据恢复策略取值none/full/incremental对应ExistingVolumeDataPolicy--or-selector多个标签选择器以 or 连接如foobar or appnginx与--selector互斥对应OrLabelSelectors--resource-modifier-configmap恢复前对资源应用 JSON patch 的 ConfigMap对应ResourceModifier--resource-policies-configmap引用包含恢复资源过滤策略的 ConfigMap对应ResourcePolicy--skip-default-resource-modifier跳过服务端配置的默认资源修改器--status-include-resources/--status-exclude-resources控制恢复哪些资源的 status 字段对应RestoreStatusSpec--item-operation-timeout异步插件操作的等待超时时间--wait, -w阻塞等待恢复完成期间可通过 Ctrl-C 安全退出恢复继续在后台执行--write-sparse-files文件系统恢复时是否以稀疏文件方式写入--parallel-files-download文件下载并行度0 表示默认node agent 所在节点的 CPU 数--delete-extra-files文件系统恢复时删除目标卷中备份里不存在的多余文件仅对 PodVolumeBackup / CSI 文件系统数据移动生效其中--existing-resource-policy与--existing-volume-data-policy的取值合法性由 Validate 方法 在命令提交前校验非法取值会直接报错。六、命令执行流程与源码解读从 create.go 可以看出一条restore create命令背后经历了四个阶段Complete补齐默认值未指定名称时生成来源名-时间戳的默认恢复名初始化 k8s 客户端。Validate校验校验备份/调度来源互斥性、selector 与 or-selector 互斥性、策略取值合法性并提前检查备份或调度是否存在从 create_test.go 的 create a restore from not-existed backup 用例 可以看到对不存在的备份会返回backups.velero.io not-exist not found错误。构建 Restore 对象将各选项映射为api.Restore对象。若指定了--resource-policies-configmap会构造TypedLocalObjectReference{Kind: configmap, Name: ...}存入Spec.ResourcePolicy该行为由 create_test.go 第 207-238 行 的测试用例验证。Run执行通过o.client.Create(...)提交 Restore 对象到 API Server打印Restore request name submitted successfully.若指定--wait则启动 informer 监听该 Restore 的状态变化直到进入Completed/PartiallyFailed/Failed/FailedValidation终态见 Run 方法。特别值得注意的mostRecentBackup逻辑create.go L265-L299当使用--from-schedule --allow-partially-failed时命令会把该调度触发的所有备份按开始时间倒序排列选取最近一个Completed或PartiallyFailed的备份作为恢复来源对应单测 TestMostRecentBackup 验证了排序与阶段过滤逻辑的正确性。七、典型使用场景汇总场景一全量恢复一个备份ark restore create backup-1等价于现代写法velero restore create restore-1 --from-backup backup-1默认恢复所有命名空间、所有资源并从快照恢复卷。场景二仅恢复 PVC 与 PVvelero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes该示例直接取自源码 NewCreateCommand 的 Example用于只恢复持久卷数据而不动工作负载。场景三恢复到新命名空间迁移/环境复制ark restore create backup-prod --namespace-mappings prod:staging将prod命名空间的全部资源恢复到staging命名空间实现环境克隆。场景四按标签选择性恢复ark restore create backup-1 -l tierfrontend只恢复备份中带有tierfrontend标签的对象。场景五从调度恢复velero restore create --from-schedule daily-backup velero restore create --from-schedule daily-backup --allow-partially-failed前者使用调度最近一次成功Completed的备份后者在最近一次备份部分失败时也允许基于它进行恢复。场景六先预览后执行ark restore create backup-1 -o yaml仅输出将要创建的 Restore YAML 对象不提交到集群便于审查与版本管理。八、恢复后的检查与排障恢复请求提交成功后建议按顺序执行以下命令确认结果相关子命令见 restore.goark restore get查看恢复列表及当前阶段状态ark restore describe RESTORE_NAME查看恢复的详细配置与每个资源的处理结果ark restore logs RESTORE_NAME查看恢复过程的详细日志。v0.6.0 文档在 SEE ALSO 中给出了指向 ark restore 的导航而当前仓库中与恢复排障相关的更完整资料还可参考 debugging-restores.md。九、注意事项与最佳实践备份与调度只能二选一--from-backup与--from-schedule同时指定或都不指定都会报错这是 Validate 的强制约束。selector 与 or-selector 互斥二者不可同时使用create.go L226-L228。集群级资源默认恢复--include-cluster-resources默认 true若恢复目标集群与源集群配置差异较大如 StorageClass、Namespace 本身建议先评估集群级资源的影响。卷恢复默认开启--restore-volumes默认 true若仅需要恢复资源清单而不恢复数据例如灾备演练可显式传--restore-volumesfalse。恢复是异步的命令成功返回只代表恢复请求被受理真正的执行状态需通过restore get/describe/logs跟踪需要同步等待时可使用-w/--wait。本文基于 v0.6.0 的 ark restore create 参考文档 展开并结合当前 Velero 仓库的 CLI 实现 与 Restore API 定义 做了源码级印证。掌握以上参数与流程你就可以精准控制每一次 Kubernetes 资源与数据的恢复行为。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
