VeleroArkark restore命令全解析集群资源恢复的子命令族与全局选项指南【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本篇技术指南聚焦 Velero 仓库 v0.8.1 文档中的ark restore命令族即 ark_restore.md 所定义的 restore 命令体系完整覆盖其命令语法、全部全局继承选项以及 create / delete / describe / get / logs 五个子命令的实操用法与参数语义并辅以当前仓库中 restore 命令源码 的实现佐证。读者学完后可熟练使用ark restore系列命令完成从备份创建恢复、查看恢复状态、诊断恢复失败、清理恢复记录的完整闭环操作。命令定位ark restore是什么在 Velerov0.8.1 时期还称为Heptio Ark命令行前缀为ark中restore 是将已完成的备份backup重新还原到 Kubernetes 集群的过程。ark restore是一个命令组command group本身不执行具体操作而是将相关操作按动词拆分为五个子命令统一管理。其 Synopsis命令摘要只有一句话Work with restores处理恢复操作。从当前仓库源码 pkg/cmd/cli/restore/restore.go 可以看到这个命令组的注册方式如下func NewCommand(f client.Factory) *cobra.Command { c : cobra.Command{ Use: restore, Short: Work with restores, Long: Work with restores, } c.AddCommand( NewCreateCommand(f, create), NewGetCommand(f, get), NewLogsCommand(f), NewDescribeCommand(f, describe), NewDeleteCommand(f, delete), ) return c }即ark restore下挂载五个子命令子命令功能文档ark restore create创建一个恢复ark_restore_create.mdark restore delete删除一个恢复ark_restore_delete.mdark restore describe查看恢复详情ark_restore_describe.mdark restore get列出恢复ark_restore_get.mdark restore logs获取恢复日志ark_restore_logs.md命令自身的 Optionsark restore本身不接收任何业务参数只提供一个标准的帮助参数-h, --help help for restore这与源码中命令组仅做子命令挂载、不绑定业务 flag 的实现完全一致。运行ark restore --help即可查看五个子命令的清单。Options inherited from parent commands全局继承选项ark restore及其所有子命令都继承自父命令ark的一组全局选项用于控制 Kubernetes 连接与日志输出行为。这组选项在每次运行任何 restore 子命令时均可用是排查连接与日志问题的基础--alsologtostderr log to standard error as well as files --kubeconfig string Path to the kubeconfig file to use to talk to the Kubernetes apiserver. If unset, try the environment variable KUBECONFIG, as well as in-cluster configuration --kubecontext string The context to use to talk to the Kubernetes apiserver. If unset defaults to whatever your current-context is (kubectl config current-context) --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) --log_dir string If non-empty, write log files in this directory --logtostderr log to standard error instead of files -n, --namespace string The namespace in which Ark should operate (default heptio-ark) --stderrthreshold severity logs at or above this threshold go to stderr (default 2) -v, --v Level log level for V logs --vmodule moduleSpec comma-separated list of patternN settings for file-filtered logging各选项含义与使用要点如下选项类型/默认值说明--alsologtostderr布尔开关同时将日志写入标准错误输出stderr与日志文件--kubeconfig string字符串连接 Kubernetes apiserver 使用的 kubeconfig 文件路径未设置时依次尝试环境变量KUBECONFIG以及集群内配置in-cluster configuration--kubecontext string字符串与 Kubernetes apiserver 通信所使用的 context未设置时默认使用当前 context即kubectl config current-context的输出--log_backtrace_at traceLocation位置默认:0当日志命中file:N指定位置时输出堆栈追踪常用于调试--log_dir string字符串指定日志文件写入目录留空则不写文件--logtostderr布尔开关将日志写入标准错误输出stderr而非文件-n, --namespace string默认heptio-arkArk 运行所在的 Kubernetes 命名空间。注意v0.8.1 时期默认命名空间为heptio-ark后续版本更名为velero--stderrthreshold severity默认2达到或超过该严重级别severity的日志输出到 stderr。severity 取值对应 glog 的INFO0, WARNING1, ERROR2, FATAL3默认 2 表示 ERROR 及以上才输出到 stderr-v, --v Level数值级别V 级日志verbose log的详细程度--vmodule moduleSpec逗号分隔的patternN列表按文件过滤的日志级别控制例如foo5,bar3实际使用中最常组合的排障姿势是ark restore describe name -v 4 --logtostderr以便在 stderr 直接看到详细日志多集群场景则通过--kubecontext切换目标集群--namespace指定 Ark 实例所在命名空间。ark restore create创建恢复ark restore create是 restore 命令族中最核心的子命令用于根据指定备份创建一次恢复。语法ark restore create [RESTORE_NAME] --from-backup BACKUP_NAME [flags][RESTORE_NAME]为可选的位置参数——显式指定恢复名称或省略让其自动生成见下文示例。示例文档给出的两个标准用法# 从备份 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时恢复名称默认形如backup-1-timestamp避免同名冲突适合脚本化批量恢复场景。Options 详解--exclude-namespaces stringArray namespaces to exclude from the restore --exclude-resources stringArray resources to exclude from the restore, formatted as resource.group, such as storageclasses.storage.k8s.io --from-backup string backup to restore from -h, --help help for create --include-cluster-resources optionalBool[true] include cluster-scoped resources in the restore --include-namespaces stringArray namespaces to include in the restore (use * for all namespaces) (default *) --include-resources stringArray resources to include in the restore, formatted as resource.group, such as storageclasses.storage.k8s.io (use * for all resources) --label-columns stringArray a comma-separated list of labels to be displayed as columns --labels mapStringString labels to apply to the restore --namespace-mappings mapStringString namespace mappings from name in the backup to desired restored name in the form src1:dst1,src2:dst2,... -o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are table, json, and yaml. --restore-volumes optionalBool[true] whether to restore volumes from snapshots -l, --selector labelSelector only restore resources matching this label selector (default none) --show-labels show labels in the last column各参数的核心语义参数类型/默认值语义与使用要点--from-backup string必填指定恢复来源的备份名称如--from-backup backup-1--include-namespaces stringArray默认*仅恢复这些命名空间内的资源*表示全部命名空间可多次指定多个命名空间--exclude-namespaces stringArray空排除这些命名空间的资源可与 include 组合实现全量减去黑名单--include-resources stringArray空*为全资源仅恢复这些资源格式为resource.group如storageclasses.storage.k8s.io*表示全部资源--exclude-resources stringArray空排除这些资源格式同上如--exclude-resources events,secrets--include-cluster-resources optionalBool[true]默认true是否在恢复中包含集群级cluster-scoped资源。注意类型为optionalBool——该类型是三态布尔true / false / 未指定未显式指定时由 Ark 依据集群上下文自动推断若恢复的是同一集群通常保持原值若为跨集群迁移未指定时自动推断为 true以保证集群级资源一并还原--restore-volumes optionalBool[true]默认true是否从快照恢复卷。仅在备份包含卷快照时生效设为false可跳过卷恢复--namespace-mappings mapStringString空命名空间映射格式src1:dst1,src2:dst2,...将备份中的命名空间恢复到新的命名空间是命名空间迁移/重命名的关键参数--selector labelSelector默认none标签选择器仅恢复匹配该标签选择器的资源--labels mapStringString空为创建的 restore 对象附加标签格式如envprod,teamops--label-columns stringArray空以逗号分隔的标签列表作为结果表格的附加列展示--show-labels布尔开关在结果最后一列展示标签-o, --output string空输出格式。对 create 类命令只展示对象而不实际提交到服务器合法格式为table、json、yaml。用-o yaml可预览将要创建的 restore 对象定义实现干跑dry-run效果典型组合示例将备份prod-backup中app命名空间恢复到staging命名空间且跳过卷恢复ark restore create restore-staging \ --from-backup prod-backup \ --namespace-mappings app:staging \ --restore-volumesfalse \ --include-namespaces appoptionalBool 类型的说明文档中--include-cluster-resources与--restore-volumes的类型标注为optionalBool[true]这是一种特殊的三态布尔 flag未指定该 flag不向 restore 对象写入该字段由服务端按语义自动处理指定true强制启用指定false强制禁用。例如--restore-volumesfalse与完全不传--restore-volumes行为不同前者明确要求不恢复卷后者让系统按默认策略快照存在则恢复处理。理解这一点对精确控制恢复行为非常重要。ark restore delete删除恢复删除一个已存在的 restore 记录。ark restore delete NAME [flags]例如ark restore delete restore-1。该命令仅有的业务参数是NAME位置参数与-h/--help。删除 restore 对象本身不会反向影响其来源备份也不会删除已经恢复到集群中的资源它清理的是 Ark 存储中的 restore 元数据与记录。ark restore describe查看恢复详情查看一个或多个 restore 的详细状态信息。ark restore describe [NAME1] [NAME2] [NAME...] [flags]支持一次传入多个名称。Options 如下-h, --help help for describe -l, --selector string only show items matching this label selector参数说明-l, --selector string仅展示匹配该标签选择器的恢复对象describe 输出通常包含restore 的总体状态如 New / InProgress / Completed / Failed / PartiallyFailed 等阶段、通过/失败的资源条目统计、从哪个备份恢复、应用了哪些过滤规则include/exclude、namespace-mappings、selector 等。这是判断恢复是否成功、哪些资源失败的首选排障命令。ark restore get列出恢复以表格形式列出命名空间内的所有恢复。ark restore get [flags]-h, --help help for get --label-columns stringArray a comma-separated list of labels to be displayed as columns -o, --output string Output display format. For create commands, display the object but do not send it to the server. Valid formats are table, json, and yaml. (default table) -l, --selector string only show items matching this label selector --show-labels show labels in the last column参数类型/默认值说明-o, --output string默认table输出格式合法值为table、json、yaml。与 create 不同get 的-o是查询后的展示格式而非不提交-l, --selector string空仅显示匹配该标签选择器的恢复--label-columns stringArray空指定标签作为表格附加列展示--show-labels布尔开关在最后一列显示标签典型使用ark restore get查看所有恢复及其状态ark restore get -o yaml以 YAML 形式导出恢复定义。ark restore logs获取恢复日志获取指定 restore 的执行日志是恢复失败时定位根因的核心手段。ark restore logs RESTORE [flags]-h, --help help for logs --timeout duration how long to wait to receive logs (default 1m0s)参数默认值说明--timeout duration1m0s等待日志就绪的超时时间Go duration 格式如30s、2m。恢复完成后日志可能需要短暂时间才可获取超时会报错典型用法ark restore logs restore-1对于大型恢复可增大超时ark restore logs restore-1 --timeout 3m。日志中包含每个资源项的恢复结果与错误信息配合ark restore describe可以完整还原一次恢复的执行过程。源码视角restore 命令族的实现结构当前仓库中restore 命令族实现位于 pkg/cmd/cli/restore/ 目录包含restore.go、create.go、delete.go、describe.go、get.go、logs.go及对应测试文件与 v0.8.1 文档中的子命令一一对应。以 create.go 为例其CreateOptions结构体集中定义了创建恢复的全部可选字段除文档中 v0.8.1 已有的参数外后续版本还演进出了ScheduleName--from-schedule从定时调度的最新成功备份恢复、ExistingResourcePolicy、Wait、ItemOperationTimeout等扩展能力。命令行定义部分create.go还提供了--from-backup与--from-schedule的参数自动补全flag completion通过RegisterFlagCompletionFunc从集群中动态列出可用的备份与调度名称。从命令行流程看每个子命令执行时均遵循Complete → Validate → Run三步Complete解析并补全用户输入Validate校验参数合法性Run才真正执行与 Kubernetes API 的交互例如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)) },从ark到velero命令名的演进需要特别说明本指南依据的 v0.8.1 文档位于仓库的 site/content/docs/v0.8.1/cli-reference/ 目录彼时项目名为Heptio Ark二进制与命令前缀均为ark默认命名空间为heptio-ark。项目后续更名为 VeleroVMware Tanzu 维护当前仓库源码中对应命令已变为velero restore见 pkg/cmd/cli/restore/restore.go默认命名空间也改为velero。因此在实际使用中若你的环境是 Ark v0.8.x请按本文档原样使用ark restore ...若使用新版本 Velero将命令前缀替换为velero即可如velero restore create restore-1 --from-backup backup-1子命令结构与核心参数--from-backup、--include-namespaces、--namespace-mappings、--selector等保持延续。实战一次完整的恢复排查闭环综合以上命令一次标准的创建—监控—诊断—清理恢复流程如下# 1. 从备份创建恢复自动命名 ark restore create --from-backup backup-1 # 2. 查看恢复状态与资源统计 ark restore get # 3. 查看单个恢复的详细结果哪些资源失败 ark restore describe backup-1-1600000000 # 4. 若失败拉取恢复日志定位根因 ark restore logs backup-1-1600000000 --timeout 2m # 5. 确认不再需要记录后删除 ark restore delete backup-1-1600000000这一闭环覆盖了 restore 命令族的全部核心能力无论是日常演练恢复还是灾难恢复DR场景都可直接套用。参考文档命令族总览ark_restore.md子命令文档ark_restore_create.md / ark_restore_delete.md / ark_restore_describe.md / ark_restore_get.md / ark_restore_logs.md源码实现pkg/cmd/cli/restore/restore.go命令组注册、pkg/cmd/cli/restore/create.go创建参数定义【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考