Ark/Veleroark create restore命令全解析从备份创建 Kubernetes 恢复任务【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读ark create restore在现代 Velero 中对应velero restore create是 Ark/Velero 命令行中用于从既有备份创建恢复Restore任务的核心命令。本文以仓库内 site/content/docs/v0.8.1/cli-reference/ark_create_restore.md 的 CLI 参考文档为骨架逐项解析该命令的语法、全部参数与典型用法并结合当前仓库中 pkg/cmd/cli/restore/create.go 的源码实现说明命令背后从 CLI 参数到RestoreAPI 对象的完整映射关系。阅读本文后你将能熟练使用该命令完成全量/选择性恢复、命名空间迁移、卷快照恢复、资源过滤等典型运维操作。命令概述与定位命令在 CLI 树中的位置ark create restore是ark create的子命令而ark create又是ark根命令的子命令。在 Ark 0.8.1 的命令树中ark备份和恢复 Kubernetes 集群资源的总入口ark create创建 Ark 资源backup / restore / schedule的父命令ark create restore从备份创建恢复任务。在 site/content/docs/v0.8.1/cli-reference/ark_create.md 的SEE ALSO一节中可以确认ark create下共有三个子命令ark create backup、ark create restore与ark create schedule。值得注意的是0.8.1 文档中同时存在ark create restore与ark restore create两种写法参见 ark_restore_create.md两者等价——前者是“创建”动作挂靠在create分组下后者则把 restore 提升为顶层命令分组。在今天的 Velero 中已统一为velero restore create由 pkg/cmd/cli/restore/restore.go 注册该命令组下包含create、get、logs、describe、delete五个子命令。Synopsis命令语法ark create restore [RESTORE_NAME] --from-backup BACKUP_NAME [flags]RESTORE_NAME可选。恢复任务的名称必须是合法的 Kubernetes 对象名称--from-backup BACKUP_NAME必选。指定从哪个备份创建恢复[flags]控制恢复行为的各类可选参数详见下文。典型使用示例官方文档给出了两个最基础的用法见 ark_create_restore.md# 从备份 backup-1 创建名为 restore-1 的恢复 ark restore create restore-1 --from-backup backup-1 # 从备份 backup-1 创建恢复使用默认名称backup-1-timestamp ark restore create --from-backup backup-1默认命名规则说明当不显式指定RESTORE_NAME时CLI 会按照来源名-时间戳的格式自动生成名称。这一行为在当前仓库源码 pkg/cmd/cli/restore/create.go 的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)) }即显式传名则使用用户给定的名称否则取--from-backup或--from-schedule的来源名拼上20060102150405格式年月日时分秒的时间戳。此外官方文档的示例还覆盖了“只恢复部分资源类型”的用法该示例在当前版本命令的Example文本中依然保留见 create.go# 只恢复备份中的 persistentvolumeclaims 和 persistentvolumes velero restore create --from-backup backup-2 --include-resources persistentvolumeclaims,persistentvolumes参数详解Options本节完整列出ark create restore支持的全部参数。其中核心过滤与行为参数如下参数类型说明--from-backup stringstring必选。指定从哪个备份恢复--include-namespaces stringArray字符串数组要包含的命名空间多个值用逗号分隔使用*表示所有命名空间默认*--exclude-namespaces stringArray字符串数组要从恢复中排除的命名空间--include-resources stringArray字符串数组要包含的资源类型格式为resource.group例如storageclasses.storage.k8s.io使用*表示全部资源--exclude-resources stringArray字符串数组要排除的资源类型格式同上--include-cluster-resources optionalBool[true]optionalBool是否包含集群级cluster-scoped资源可直接写--include-cluster-resources表示 true--namespace-mappings mapStringStringmap命名空间映射格式src1:dst1,src2:dst2,...用于把备份中的命名空间恢复到目标命名空间--restore-volumes optionalBool[true]optionalBool是否从快照恢复卷数据--selector labelSelector别名-llabelSelector只恢复匹配该标签选择器的资源默认none--labels mapStringStringmap应用到恢复对象上的标签--label-columns stringArray字符串数组显示为表格列的一组标签逗号分隔仅影响展示--show-labelsbool在最后一列显示标签-o, --output stringstring输出显示格式。对于 create 类命令仅打印对象而不发送到服务端合法值为table、json、yaml-h, --helpbool显示帮助信息关键参数深入说明--include-cluster-resources的三态语义该参数类型为optionalBool取值为 true / false / 不设置三种状态。若为 true包含全部集群级资源受 include/exclude resources 与 label selector 约束若为 false不包含任何集群级资源若未设置则当且仅当所有命名空间都被包含且没有排除命名空间时才包含全部集群级资源。反之只要includedNamespaces或excludedNamespaces中出现了具体命名空间就只包含与所包含的命名空间级资源相关联的集群级资源例如备份中包含某个 PVC则其关联的 PV 也会被恢复。这一语义在 pkg/apis/velero/v1/restore_types.go 的IncludeClusterResources *bool字段注释中同样有说明null 时默认 true。--restore-volumes与云快照该参数控制是否从云厂商快照恢复 PersistentVolume。在 Ark 0.8.1 时代快照能力对应 AWS/GCE/Azure 等云提供商参考 api-types/backup.md 中snapshotVolumes字段的说明。在现代版本中快照恢复还扩展到了 CSI 快照与文件系统备份PodVolumeBackup / DataUpload等多种数据移动路径。--namespace-mappings的解析实现该参数在NewCreateOptions中被初始化为带自定义分隔符的 map 类型create.goNamespaceMappings: flag.NewMap().WithEntryDelimiter(,).WithKeyValueDelimiter(:),即条目之间用逗号分隔、键值之间用冒号分隔最终通过o.NamespaceMappings.Data()写入RestoreSpec.NamespaceMapping字段对应 restore_types.go 中NamespaceMapping map[string]string的注释未出现在映射中的源命名空间将恢复到同名命名空间。继承自父命令的全局参数ark create restore还继承了一批来自ark根命令的全局参数主要与 kubeconfig、日志与运行环境相关参数说明--kubeconfig string连接 Kubernetes apiserver 使用的 kubeconfig 文件路径未设置时依次尝试环境变量KUBECONFIG与集群内配置in-cluster configuration--kubecontext string使用的 kubeconfig context未设置时使用kubectl config current-context的当前 context-n, --namespace stringArk 操作的命名空间默认heptio-ark即 Ark Server 所在命名空间--alsologtostderr除写日志文件外同时输出到标准错误--logtostderr只输出到标准错误不写日志文件--log_dir string非空时将日志写入该目录--log_backtrace_at traceLocation当日志命中的位置为file:N时输出堆栈跟踪默认:0--stderrthreshold severity达到该严重级别的日志输出到 stderr默认 2-v, --v LevelV 日志的日志级别--vmodule moduleSpec按文件过滤的patternN日志设置逗号分隔列表注意-n的默认值是heptio-arkArk 0.8.1 时代的命名空间名在更名为 Velero 后的版本中该默认值变为velero。命令执行流程从参数到 Restore API 对象尽管 0.8.1 的 CLI 参考文档只描述了命令的输入输出当前仓库中 pkg/cmd/cli/restore/create.go 保留了完整的实现可以让我们看清命令背后的三步流水线Run: func(c *cobra.Command, args []string) { cmd.CheckError(o.Complete(args, f)) cmd.CheckError(o.Validate(c, args, f)) cmd.CheckError(o.Run(c, f)) },1. Complete补全参数如前述Complete负责在没有显式命名时生成名称-时间戳形式的恢复名并初始化与 apiserver 交互的客户端。2. Validate校验参数Validate方法create.go执行如下检查--from-backup与--from-schedule必须二选一且不能同时给出“either a backup or schedule must be specified, but not both”若指定了--from-backup会先尝试从 apiserver 读取该 Backup 对象读取失败则报错保证恢复来源真实存在若指定了--from-schedule会按velero.io/schedule-name标签列出该 Schedule 产生的备份找不到任何备份时返回错误。3. Run构造 Restore 并提交Run方法将 CLI 参数逐一映射为api.Restore对象create.go字段与命令参数的对应关系包括CLI 参数RestoreSpec 字段--from-backupBackupName--from-scheduleScheduleName--include-namespaces/--exclude-namespacesIncludedNamespaces/ExcludedNamespaces--include-resources/--exclude-resourcesIncludedResources/ExcludedResources--namespace-mappingsNamespaceMapping--selectorLabelSelector--restore-volumesRestorePVs--include-cluster-resourcesIncludeClusterResources--labelsObjectMeta.Labels对象构造完成后调用o.client.Create(...)提交到集群对应ark.heptio.com/v1/velero.io/v1的Restore资源见 restore_types.go随后打印Restore request restore-1 submitted successfully.创建本身是异步的命令返回后由服务端RestoreController接手执行实际恢复流程。因此命令结尾会提示用ark restore describe或ark restore logs查看后续结果。关于默认命名与测试验证pkg/cmd/cli/restore/create_test.go中的TestCreateCommand覆盖了全量参数--from-backup、--from-schedule、--include-namespaces、--namespace-mappings、--selector、--restore-volumes等从 flag 解析到CreateOptions绑定的完整链路create_test.go可作为阅读命令实现的辅助测试用例。后续操作与关联命令创建恢复任务后可通过以下命令跟进状态均为ark restore子命令见 ark_restore.mdark restore get列出恢复任务ark restore describe查看恢复任务详情语法为ark restore describe [NAME1] [NAME2] [NAME...]支持-l/--selector过滤ark restore logs获取恢复日志语法为ark restore logs RESTORE [flags]可通过--timeout duration控制等待日志的最长时间默认1m0sark restore delete删除恢复任务。恢复完成后可通过status.phase观察最终状态。现代版本中RestorePhase的取值包括New、FailedValidation、InProgress、WaitingForPluginOperations、Completed、PartiallyFailed、Failed、Finalizing等枚举定义见 restore_types.go。其中PartiallyFailed表示恢复已执行完毕但个别条目出现错误Failed表示整个恢复无法执行具体原因记录在status.failureReason中。从 Ark 0.8.1 到 Velero 的演进ark create restore是 Velerovelero restore create命令的前身两者在核心参数上高度一致。需要特别提醒的是本仓库当前版本的velero restore create相比 0.8.1 文档新增了多项能力create.go 中CreateOptions可见--from-schedule从指定 Schedule 最近一次成功的备份恢复配合--allow-partially-failed可允许选择“部分失败”状态的备份对应mostRecentBackup函数的排序选择逻辑见 create.go其按 StartTimestamp 倒序挑选最晚的 Completed/PartiallyFailed 备份并有 create_test.go 中的TestMostRecentBackup用例验证--wait/-w等待恢复完成通过 informer 监听 Restore 对象的相位变化在终态Completed / PartiallyFailed / Failed / FailedValidation打印提示create.go--preserve-nodeports恢复 Service 时是否保留原 NodePort--existing-resource-policy对集群中已存在资源的处理策略none/update--existing-volume-data-policy对已存在卷数据的处理策略none/full/incremental--item-operation-timeout异步插件操作超时时间默认 4 小时--resource-modifier-configmap、--resource-policies-configmap等更细粒度的过滤与资源改写能力。因此若你使用的是现代 Velero建议优先阅读 pkg/cmd/cli/restore/create.go 与其命令帮助文本以获得最完整的参数集而 0.8.1 这份文档中的语法骨架、过滤语义与命名规则在今天依然完全适用是理解整个恢复创建流程的最佳起点。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考