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

VeleroArkrestore命令族详解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 为核心系统讲解早期 ArkVelero 前身中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字段为restoreShort/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自身的 Optionsark restore命令组本身只有一个通用参数-h, --help help for restore-h/--help用于显示该命令的帮助信息。其余所有功能参数都分布在各个子命令上这在 CLI 设计上属于命令组 子命令的典型模式。三、Options inherited from parent commands全局继承参数ark restore及其所有子命令都继承自父命令ark的一组全局参数。这些参数控制着 Ark 客户端如何连接 Kubernetes 集群、如何输出日志在任何ark restore *命令后均可使用参数类型/默认值说明--alsologtostderrbool默认 false除了写日志文件外同时将日志输出到标准错误stderr--kubeconfig stringstring用于连接 Kubernetes apiserver 的 kubeconfig 文件路径。若未设置则尝试使用环境变量KUBECONFIG以及集群内in-cluster配置--log_backtrace_at traceLocation默认:0当日志命中file:N位置时输出堆栈跟踪--log_dir stringstring若非空则将日志文件写入该目录--logtostderrbool默认 false将日志输出到标准错误stderr而非文件-n, --namespace string默认heptio-arkArk 工作所在的 Kubernetes 命名空间当时 Ark 的默认部署命名空间为heptio-ark--stderrthreshold severity默认 2达到或超过该严重级别的日志输出到 stderr级别对应 glog 的 severity0INFO、1WARNING、2ERROR、3FATAL-v, --v LevelLevel 类型V 级别日志的详细程度glog 风格--vmodule moduleSpecstring按文件过滤日志的patternN逗号分隔列表这些参数全部继承自父命令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.1ark restore create创建恢复创建恢复是恢复工作流的入口语法为ark restore create BACKUP [flags]在 v0.7.0 中BACKUP作为位置参数传入即指定要恢复的备份名称。其可用参数如下完整继承自 ark_restore_create.md参数类型/默认值说明--exclude-namespaces stringArraystringArray恢复时排除的命名空间列表--exclude-resources stringArraystringArray恢复时排除的资源类型格式为resource.group如storageclasses.storage.k8s.io--include-cluster-resources optionalBool[true]optionalBool默认 true恢复时是否包含集群级cluster-scoped资源--include-namespaces stringArray默认*恢复时包含的命名空间列表使用*表示所有命名空间--include-resources stringArraystringArray恢复时包含的资源类型格式为resource.group如storageclasses.storage.k8s.io使用*表示所有资源--label-columns stringArraystringArray以逗号分隔的标签列表将标签显示为表格列--labels mapStringStringmapStringString应用到恢复对象上的标签键值对--namespace-mappings mapStringStringmapStringString命名空间映射格式为src1:dst1,src2:dst2,...将备份中的命名空间名映射为恢复后的目标命名空间名-o, --output stringstring输出显示格式。对于 create 命令仅显示对象而不发送到服务器。合法格式为table、json、yaml--restore-volumes optionalBool[true]optionalBool默认 true是否从快照恢复卷-l, --selector labelSelector默认none仅恢复匹配该标签选择器的资源--show-labelsbool在最后一列显示标签需要特别强调两个在灾备场景中极具价值的能力--namespace-mappings支持将备份中的命名空间改名恢复例如将备份中的app-a命名空间恢复到目标集群的app-b命名空间这在跨集群迁移、环境隔离如测试环境 ← 生产环境备份时非常实用其格式为src1:dst1,src2:dst2,...。--restore-volumes控制是否从快照恢复卷数据。默认开启true当仅需恢复配置对象、不需要或无法恢复持久卷数据时可显式传入--restore-volumesfalse。此外--include-*/--exclude-*参数族提供了细粒度的资源过滤能力既可按命名空间过滤也可按resource.group格式如storageclasses.storage.k8s.io按资源类型过滤。4.2ark restore get获取恢复列表语法ark restore get [flags]用于列出当前集群中的恢复对象。其参数与 create 的展示类参数对应参数类型/默认值说明-h, --helpbool帮助信息--label-columns stringArraystringArray以逗号分隔的标签列表将标签显示为表格列-o, --output string默认table输出格式合法值为table、json、yaml-l, --selector stringstring仅显示匹配该标签选择器的恢复--show-labelsbool在最后一列显示标签默认以table格式输出适合快速浏览恢复列表-o json/-o yaml适合脚本化处理或与其他工具集成。4.3ark restore describe查看恢复详情语法ark restore describe [NAME1] [NAME2] [NAME...] [flags]支持一次传入多个恢复名称同时查看多个恢复的详细状态信息参数类型说明-h, --helpbool帮助信息-l, --selector stringstring仅显示匹配该标签选择器的项目4.4ark restore logs获取恢复日志语法ark restore logs RESTORE [flags]用于获取指定恢复的执行日志是排查恢复失败问题的第一手工具参数类型/默认值说明-h, --helpbool帮助信息--timeout duration默认1m0s等待接收日志的超时时间--timeout控制从 apiserver 拉取恢复日志的最大等待时长默认 1 分钟。对于包含大量资源的恢复可适当调大该值。4.5ark 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。而当前仓库主分支已演变为 VeleroCLI 命令前缀变为velero默认命名空间变为velerocreate 子命令的语法也由位置参数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），仅供参考