Velero（Ark）`restore` 命令族详解：Kubernetes 集群资源恢复的 CLI 操作指南-二趣网

Velero（Ark）`restore`命令族详解：Kubernetes 集群资源恢复的 CLI 操作指南

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

本文以 Velero 仓库中 v0.7.0 时代的 CLI 参考文档 site/content/docs/v0.7.0/cli-reference/ark_restore.md 为核心，系统讲解早期 Ark（Velero 前身）中ark restore命令的定义、全局继承参数、全部子命令（create / delete / describe / get / logs）的用法与参数含义，并结合当前仓库源码说明该命令族的实现结构与演进脉络。读完本文，你将能熟练使用ark restore命令族完成备份的恢复、查询、描述、日志获取与删除等完整恢复工作流，并理解其底层命令注册与参数解析机制。

一、命令概述：`ark restore`

在 Velero 的早期版本（v0.7.0，当时项目名为Ark）中，ark restore是负责"处理恢复（restore）"操作的顶层命令。其官方 Synopsis 描述十分简洁：

Work with restores

它的作用域是恢复（restore）资源，即把此前通过ark backup创建的备份数据还原到 Kubernetes 集群中。restore 命令本身是一个"命令组"（command group），它本身不直接执行具体操作，而是将不同操作委托给五个子命令：create、delete、describe、get和logs。

这一点可以从当前仓库源码中得到印证：在 pkg/cmd/cli/restore/restore.go 中，NewCommand函数通过 Cobra 框架注册命令，其Use字段为restore，Short/Long描述均为Work with restores，随后挂载了五个子命令：

c.AddCommand( NewCreateCommand(f, "create"), NewGetCommand(f, "get"), NewLogsCommand(f), NewDescribeCommand(f, "describe"), NewDeleteCommand(f, "delete"), )

即：create（创建恢复）→ get（查询列表）→ logs（获取日志）→ describe（查看详情）→ delete（删除恢复），这就是 v0.7.0 文档SEE ALSO一节所列的子命令全集，两者完全一致。

二、`ark restore`自身的 Options

ark restore命令组本身只有一个通用参数：

-h, --help help for restore

-h/--help用于显示该命令的帮助信息。其余所有功能参数都分布在各个子命令上，这在 CLI 设计上属于"命令组 + 子命令"的典型模式。

三、Options inherited from parent commands：全局继承参数

ark restore及其所有子命令都继承自父命令ark的一组全局参数。这些参数控制着 Ark 客户端如何连接 Kubernetes 集群、如何输出日志，在任何ark restore *命令后均可使用：

参数	类型/默认值	说明
`--alsologtostderr`	bool（默认 false）	除了写日志文件外，同时将日志输出到标准错误（stderr）
`--kubeconfig string`	string	用于连接 Kubernetes apiserver 的 kubeconfig 文件路径。若未设置，则尝试使用环境变量`KUBECONFIG`，以及集群内（in-cluster）配置
`--log_backtrace_at traceLocation`	默认`:0`	当日志命中`file:N`位置时，输出堆栈跟踪
`--log_dir string`	string	若非空，则将日志文件写入该目录
`--logtostderr`	bool（默认 false）	将日志输出到标准错误（stderr）而非文件
`-n, --namespace string`	默认`heptio-ark`	Ark 工作所在的 Kubernetes 命名空间（当时 Ark 的默认部署命名空间为`heptio-ark`）
`--stderrthreshold severity`	默认 2	达到或超过该严重级别的日志输出到 stderr（级别对应 glog 的 severity，0=INFO、1=WARNING、2=ERROR、3=FATAL）
`-v, --v Level`	Level 类型	V 级别日志的详细程度（glog 风格）
`--vmodule moduleSpec`	string	按文件过滤日志的`pattern=N`逗号分隔列表

这些参数全部继承自父命令ark，其完整定义可参见同目录下的 ark.md。在实际使用中，-n heptio-ark与--kubeconfig是最常被显式指定的参数——前者指定 Ark 自身所在命名空间（即 restore 等 CRD 资源存放的位置），后者用于在多集群场景下切换目标 apiserver。

四、SEE ALSO：五个子命令详解

ark restore的子命令各自承担恢复工作流中的一项职责。v0.7.0 文档将其列为：

ark restore create— 创建一个恢复
ark restore delete— 删除一个恢复
ark restore describe— 描述（查看详情）恢复
ark restore get— 获取恢复列表
ark restore logs— 获取恢复日志

4.1`ark restore create`：创建恢复

创建恢复是恢复工作流的入口，语法为：

ark restore create BACKUP [flags]

在 v0.7.0 中，BACKUP作为位置参数传入，即指定要恢复的备份名称。其可用参数如下（完整继承自 ark_restore_create.md）：

参数	类型/默认值	说明
`--exclude-namespaces stringArray`	stringArray	恢复时排除的命名空间列表
`--exclude-resources stringArray`	stringArray	恢复时排除的资源类型，格式为`resource.group`，如`storageclasses.storage.k8s.io`
`--include-cluster-resources optionalBool[=true]`	optionalBool，默认 true	恢复时是否包含集群级（cluster-scoped）资源
`--include-namespaces stringArray`	默认`*`	恢复时包含的命名空间列表（使用`*`表示所有命名空间）
`--include-resources stringArray`	stringArray	恢复时包含的资源类型，格式为`resource.group`，如`storageclasses.storage.k8s.io`（使用`*`表示所有资源）
`--label-columns stringArray`	stringArray	以逗号分隔的标签列表，将标签显示为表格列
`--labels mapStringString`	mapStringString	应用到恢复对象上的标签（键值对）
`--namespace-mappings mapStringString`	mapStringString	命名空间映射，格式为`src1:dst1,src2:dst2,...`，将备份中的命名空间名映射为恢复后的目标命名空间名
`-o, --output string`	string	输出显示格式。对于 create 命令，仅显示对象而不发送到服务器。合法格式为`table`、`json`、`yaml`
`--restore-volumes optionalBool[=true]`	optionalBool，默认 true	是否从快照恢复卷
`-l, --selector labelSelector`	默认`<none>`	仅恢复匹配该标签选择器的资源
`--show-labels`	bool	在最后一列显示标签

需要特别强调两个在灾备场景中极具价值的能力：

--namespace-mappings：支持将备份中的命名空间"改名"恢复，例如将备份中的app-a命名空间恢复到目标集群的app-b命名空间，这在跨集群迁移、环境隔离（如测试环境 ← 生产环境备份）时非常实用，其格式为src1:dst1,src2:dst2,...。
--restore-volumes：控制是否从快照恢复卷数据。默认开启（=true）；当仅需恢复配置对象、不需要（或无法）恢复持久卷数据时，可显式传入--restore-volumes=false。

此外，--include-*/--exclude-*参数族提供了细粒度的资源过滤能力：既可按命名空间过滤，也可按resource.group格式（如storageclasses.storage.k8s.io）按资源类型过滤。

4.2`ark restore get`：获取恢复列表

语法：

ark restore get [flags]

用于列出当前集群中的恢复对象。其参数与 create 的展示类参数对应：

参数	类型/默认值	说明
`-h, --help`	bool	帮助信息
`--label-columns stringArray`	stringArray	以逗号分隔的标签列表，将标签显示为表格列
`-o, --output string`	默认`table`	输出格式，合法值为`table`、`json`、`yaml`
`-l, --selector string`	string	仅显示匹配该标签选择器的恢复
`--show-labels`	bool	在最后一列显示标签

默认以table格式输出，适合快速浏览恢复列表；-o json/-o yaml适合脚本化处理或与其他工具集成。

4.3`ark restore describe`：查看恢复详情

语法：

ark restore describe [NAME1] [NAME2] [NAME...] [flags]

支持一次传入多个恢复名称，同时查看多个恢复的详细状态信息：

参数	类型	说明
`-h, --help`	bool	帮助信息
`-l, --selector string`	string	仅显示匹配该标签选择器的项目

4.4`ark restore logs`：获取恢复日志

语法：

ark restore logs RESTORE [flags]

用于获取指定恢复的执行日志，是排查恢复失败问题的第一手工具：

参数	类型/默认值	说明
`-h, --help`	bool	帮助信息
`--timeout duration`	默认`1m0s`	等待接收日志的超时时间

--timeout控制从 apiserver 拉取恢复日志的最大等待时长，默认 1 分钟。对于包含大量资源的恢复，可适当调大该值。

4.5`ark restore delete`：删除恢复

语法：

ark restore delete NAME [flags]

删除指定的恢复对象，仅有一个-h, --help参数。

五、源码级印证：命令的实现结构与演进

5.1 命令注册的实现

从 pkg/cmd/cli/restore/restore.go 可以看出，restore命令组完全基于 Cobra 框架构建：NewCommand接收一个client.Factory（用于构建 Kubernetes 客户端），创建Use: "restore"的父命令后，依次AddCommand五个子命令。这与 v0.7.0 文档中SEE ALSO列出的子命令一一对应。

5.2 参数实现的源码证据

以 create 子命令为例，当前仓库 pkg/cmd/cli/restore/create.go 中的CreateOptions结构体定义了命令参数对应的字段，包括RestoreVolumes flag.OptionalBool（对应--restore-volumes）、IncludeNamespaces/ExcludeNamespaces（对应--include-namespaces/--exclude-namespaces）、IncludeResources/ExcludeResources（对应--include-resources/--exclude-resources）、NamespaceMappings flag.Map（对应--namespace-mappings）、Selector flag.LabelSelector（对应--selector）等。这些参数类型（OptionalBool、StringArray、Map、LabelSelector）均位于 pkg/cmd/util/flag 包中，是 Velero CLI 对 Cobra/pflag 的封装扩展——OptionalBool支持=true/=false显式赋值与"未指定"三态语义，这正是文档中optionalBool[=true]表达方式的由来。

5.3 版本演进：从`ark restore`到`velero restore`

需要说明的是，v0.7.0 文档是 Ark 时代的产物（默认命名空间heptio-ark、命令前缀ark）。而当前仓库主分支已演变为 Velero，CLI 命令前缀变为velero，默认命名空间变为velero，create 子命令的语法也由位置参数BACKUP演化为具名参数形式：

velero restore create [RESTORE_NAME] [--from-backup BACKUP_NAME | --from-schedule SCHEDULE_NAME]

正如 pkg/cmd/cli/restore/create.go 中的Example所示，当前版本支持--from-backup（从指定备份恢复）、--from-schedule（从某个调度最近一次成功的备份恢复）两种数据来源，并增加了--resource-policies-configmap、--resource-modifier-configmap、--wait、--allow-partially-failed等高级参数。但命令组的核心骨架——create / get / describe / logs / delete五个子命令——从 v0.7.0 一直延续至今，其设计意图保持不变。

六、典型使用流程小结

结合上述内容，一次完整的恢复操作通常按以下顺序进行：

查询可用备份，确定要恢复的备份名称；
执行ark restore create BACKUP（必要时配合--include-namespaces、--exclude-resources、--namespace-mappings、--restore-volumes等过滤与映射参数）创建恢复；
用ark restore get查看恢复列表与状态；
用ark restore describe RESTORE_NAME查看单个恢复的详细状态；
若恢复失败，用ark restore logs RESTORE_NAME（可调整--timeout）获取执行日志定位问题；
对已不再需要的恢复记录，用ark restore delete NAME清理。

关于恢复过程中常见问题的进一步排查方法，可参考同版本文档 debugging-restores.md；恢复对象的数据结构与字段语义可参见 api-types 相关说明。

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析