企业官网建设流程全解析

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支持的全部参数。其中核心过滤与行为参数如下：

关键参数深入说明

--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.go）：

NamespaceMappings: flag.NewMap().WithEntryDelimiter(',').WithKeyValueDelimiter(':'),

即条目之间用逗号分隔、键值之间用冒号分隔，最终通过o.NamespaceMappings.Data()写入RestoreSpec.NamespaceMapping字段（对应 restore_types.go 中NamespaceMapping map[string]string的注释：未出现在映射中的源命名空间将恢复到同名命名空间）。

继承自父命令的全局参数

ark create restore还继承了一批来自ark根命令的全局参数，主要与 kubeconfig、日志与运行环境相关：

注意-n的默认值是heptio-ark（Ark 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），字段与命令参数的对应关系包括：

对象构造完成后调用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.md）：

• ark restore get：列出恢复任务；
• ark restore describe：查看恢复任务详情，语法为ark restore describe [NAME1] [NAME2] [NAME...]，支持-l/--selector过滤；
• ark restore logs：获取恢复日志，语法为ark restore logs RESTORE [flags]，可通过--timeout duration控制等待日志的最长时间（默认1m0s）；
• ark 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